1gnutls-cli(1)                    User Commands                   gnutls-cli(1)
2
3
4

NAME

6       gnutls-cli - GnuTLS client
7

SYNOPSIS

9       gnutls-cli  [-flags] [-flag [value]] [--option-name[[=| ]value]] [host‐
10       name]
11
12       Operands and options may be intermixed.  They will be reordered.
13
14

DESCRIPTION

16       Simple client program to set up a TLS connection  to  some  other  com‐
17       puter.  It sets up a TLS connection and forwards data from the standard
18       input to the secured socket and vice versa.
19

OPTIONS

21       -d number, --debug=number
22              Enable debugging.  This option takes an integer  number  as  its
23              argument.  The value of number is constrained to being:
24                  in the range  0 through 9999
25
26              Specifies the debug level.
27
28       -V, --verbose
29              More verbose output.  This option may appear an unlimited number
30              of times.
31
32
33       --tofu, --no-tofu
34              Enable trust on first use authentication.  The no-tofu form will
35              disable the option.
36
37              This option will, in addition to certificate authentication,
38              perform authentication based on previously seen public keys, a
39              model similar to SSH authentication. Note that when tofu is
40              specified (PKI) and DANE authentication will become advisory to
41              assist the public key acceptance process.
42
43       --strict-tofu, --no-strict-tofu
44              Fail to connect if a certificate is unknown or a known certifi‐
45              cate has changed.  The no-strict-tofu form will disable the
46              option.
47
48              This option will perform authentication as with option --tofu;
49              however, no questions shall be asked whatsoever, neither to
50              accept an unknown certificate nor a changed one.
51
52       --dane, --no-dane
53              Enable DANE certificate verification (DNSSEC).  The no-dane form
54              will disable the option.
55
56              This option will, in addition to certificate authentication
57              using the trusted CAs, verify the server certificates using on
58              the DANE information available via DNSSEC.
59
60       --local-dns, --no-local-dns
61              Use the local DNS server for DNSSEC resolving.  The no-local-dns
62              form will disable the option.
63
64              This option will use the local DNS server for DNSSEC.  This is
65              disabled by default due to many servers not allowing DNSSEC.
66
67       --ca-verification, --no-ca-verification
68              Enable CA certificate verification.  The no-ca-verification form
69              will disable the option.  This option is enabled by default.
70
71              This option can be used to enable or disable CA certificate ver‐
72              ification. It is to be used with the --dane or --tofu options.
73
74       --ocsp, --no-ocsp
75              Enable OCSP certificate verification.  The no-ocsp form will
76              disable the option.
77
78              This option will enable verification of the peer's certificate
79              using ocsp
80
81       -r, --resume
82              Establish a session and resume.
83
84              Connect, establish a session, reconnect and resume.
85
86       --earlydata=string
87              Send early data on resumption from the specified file.
88
89
90       -e, --rehandshake
91              Establish a session and rehandshake.
92
93              Connect, establish a session and rehandshake immediately.
94
95       --sni-hostname=string
96              Server's hostname for server name indication extension.
97
98              Set explicitly the server name used in the TLS server name indi‐
99              cation extension. That is useful when testing with servers setup
100              on different DNS name than the intended. If not specified, the
101              provided hostname is used. Even with this option server certifi‐
102              cate verification still uses the hostname passed on the main
103              commandline. Use --verify-hostname to change this.
104
105       --verify-hostname=string
106              Server's hostname to use for validation.
107
108              Set explicitly the server name to be used when validating the
109              server's certificate.
110
111       -s, --starttls
112              Connect, establish a plain session and start TLS.
113
114              The TLS session will be initiated when EOF or a SIGALRM is
115              received.
116
117       --app-proto
118              This is an alias for the --starttls-proto option.
119
120       --starttls-proto=string
121              The application protocol to be used to obtain the server's cer‐
122              tificate (https, ftp, smtp, imap, ldap, xmpp, lmtp, pop3, nntp,
123              sieve, postgres).  This option must not appear in combination
124              with any of the following options: starttls.
125
126              Specify the application layer protocol for STARTTLS. If the pro‐
127              tocol is supported, gnutls-cli will proceed to the TLS negotia‐
128              tion.
129
130       -u, --udp
131              Use DTLS (datagram TLS) over UDP.
132
133
134       --mtu=number
135              Set MTU for datagram TLS.  This option takes an integer number
136              as its argument.  The value of number is constrained to being:
137                  in the range  0 through 17000
138
139
140       --crlf Send CR LF instead of LF.
141
142
143       --fastopen
144              Enable TCP Fast Open.
145
146
147       --x509fmtder
148              Use DER format for certificates to read from.
149
150
151       --print-cert
152              Print peer's certificate in PEM format.
153
154
155       --save-cert=string
156              Save the peer's certificate chain in the specified file in PEM
157              format.
158
159
160       --save-ocsp=string
161              Save the peer's OCSP status response in the provided file.
162
163
164       --save-server-trace=string
165              Save the server-side TLS message trace in the provided file.
166
167
168       --save-client-trace=string
169              Save the client-side TLS message trace in the provided file.
170
171
172       --dh-bits=number
173              The minimum number of bits allowed for DH.  This option takes an
174              integer number as its argument.
175
176              This option sets the minimum number of bits allowed for a
177              Diffie-Hellman key exchange. You may want to lower the default
178              value if the peer sends a weak prime and you get an connection
179              error with unacceptable prime.
180
181       --priority=string
182              Priorities string.
183
184              TLS algorithms and protocols to enable. You can use predefined
185              sets of ciphersuites such as PERFORMANCE, NORMAL, PFS,
186              SECURE128, SECURE256. The default is NORMAL.
187
188              Check  the  GnuTLS  manual  on  section  “Priority strings” for
189              more information on the allowed keywords
190
191       --x509cafile=string
192              Certificate file or PKCS #11 URL to use.
193
194
195       --x509crlfile=file
196              CRL file to use.
197
198
199       --x509keyfile=string
200              X.509 key file or PKCS #11 URL to use.
201
202
203       --x509certfile=string
204              X.509 Certificate file or PKCS #11 URL to use.  This option must
205              appear in combination with the following options: x509keyfile.
206
207
208       --srpusername=string
209              SRP username to use.
210
211
212       --srppasswd=string
213              SRP password to use.
214
215
216       --pskusername=string
217              PSK username to use.
218
219
220       --pskkey=string
221              PSK key (in hex) to use.
222
223
224       -p string, --port=string
225              The port or service to connect to.
226
227
228       --insecure
229              Don't abort program if server certificate can't be validated.
230
231
232       --verify-allow-broken
233              Allow broken algorithms, such as MD5 for certificate verifica‐
234              tion.
235
236
237       --ranges
238              Use length-hiding padding to prevent traffic analysis.
239
240              When possible (e.g., when using CBC ciphersuites), use length-
241              hiding padding to prevent traffic analysis.
242
243              NOTE: THIS OPTION IS DEPRECATED
244
245       --benchmark-ciphers
246              Benchmark individual ciphers.
247
248              By default the benchmarked ciphers will utilize any capabilities
249              of the local CPU to improve performance. To test against the raw
250              software implementation set the environment variable
251              GNUTLS_CPUID_OVERRIDE to 0x1.
252
253       --benchmark-tls-kx
254              Benchmark TLS key exchange methods.
255
256
257       --benchmark-tls-ciphers
258              Benchmark TLS ciphers.
259
260              By default the benchmarked ciphers will utilize any capabilities
261              of the local CPU to improve performance. To test against the raw
262              software implementation set the environment variable
263              GNUTLS_CPUID_OVERRIDE to 0x1.
264
265       -l, --list
266              Print a list of the supported algorithms and modes.  This option
267              must not appear in combination with any of the following
268              options: port.
269
270              Print a list of the supported algorithms and modes. If a prior‐
271              ity string is given then only the enabled ciphersuites are
272              shown.
273
274       --priority-list
275              Print a list of the supported priority strings.
276
277              Print a list of the supported priority strings. The ciphersuites
278              corresponding to each priority string can be examined using -l
279              -p.
280
281       --noticket
282              Don't allow session tickets.
283
284              Disable the request of receiving of session tickets under TLS1.2
285              or earlier
286
287       --srtp-profiles=string
288              Offer SRTP profiles.
289
290
291       --alpn=string
292              Application layer protocol.  This option may appear an unlimited
293              number of times.
294
295              This option will set and enable the Application Layer Protocol
296              Negotiation  (ALPN) in the TLS protocol.
297
298       -b, --heartbeat
299              Activate heartbeat support.
300
301
302       --recordsize=number
303              The maximum record size to advertize.  This option takes an
304              integer number as its argument.  The value of number is con‐
305              strained to being:
306                  in the range  0 through 4096
307
308
309       --disable-sni
310              Do not send a Server Name Indication (SNI).
311
312
313       --disable-extensions
314              Disable all the TLS extensions.
315
316              This option disables all TLS extensions. Deprecated option. Use
317              the priority string.
318
319              NOTE: THIS OPTION IS DEPRECATED
320
321       --single-key-share
322              Send a single key share under TLS1.3.
323
324              This option switches the default mode of sending multiple key
325              shares, to send a single one (the top one).
326
327       --post-handshake-auth
328              Enable post-handshake authentication under TLS1.3.
329
330              This option enables post-handshake authentication when under
331              TLS1.3.
332
333       --inline-commands
334              Inline commands of the form ^<cmd>^.
335
336              Enable inline commands of the form ^<cmd>^. The inline commands
337              are expected to be in a line by themselves. The available com‐
338              mands are: resume, rekey1 (local rekey), rekey (rekey on both
339              peers) and renegotiate.
340
341       --inline-commands-prefix=string
342              Change the default delimiter for inline commands..
343
344              Change the default delimiter (^) used for inline commands. The
345              delimiter is expected to be a single US-ASCII character (octets
346              0 - 127). This option is only relevant if inline commands are
347              enabled via the inline-commands option
348
349       --provider=file
350              Specify the PKCS #11 provider library.
351
352              This will override the default options in
353              /etc/gnutls/pkcs11.conf
354
355       --fips140-mode
356              Reports the status of the FIPS140-2 mode in gnutls library.
357
358
359       --logfile=string
360              Redirect informational messages to a specific file..
361
362
363       -h, --help
364              Display usage information and exit.
365
366       -!, --more-help
367              Pass the extended usage information through a pager.
368
369       -v [{v|c|n --version [{v|c|n}]}]
370              Output version of program and exit.  The default mode is `v', a
371              simple version.  The `c' mode will print copyright information
372              and `n' will print the full copyright notice.
373

EXAMPLES

375       Connecting using PSK authentication
376       To connect to a server using PSK authentication, you need to enable the
377       choice of PSK by using a cipher priority parameter such as in the exam‐
378       ple below.
379           $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity     --pskkey 88f3824b3e5659f52d00e959bacab954b6540344     --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
380           Resolving 'localhost'...
381           Connecting to '127.0.0.1:5556'...
382           - PSK authentication.
383           - Version: TLS1.1
384           - Key Exchange: PSK
385           - Cipher: AES-128-CBC
386           - MAC: SHA1
387           - Compression: NULL
388           - Handshake was completed
389           - Simple Client Mode:
390       By keeping the --pskusername parameter and removing the --pskkey param‐
391       eter, it will query only for the password during the handshake.
392
393       Connecting to STARTTLS services
394
395       You could also use the client to connect to services with starttls
396       capability.
397           $ gnutls-cli --starttls-proto smtp --port 25 localhost
398
399       Listing ciphersuites in a priority string
400       To list the ciphersuites in a priority string:
401           $ ./gnutls-cli --priority SECURE192 -l
402           Cipher suites for SECURE192
403           TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24  TLS1.2
404           TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e  TLS1.2
405           TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30  TLS1.2
406           TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b  TLS1.2
407           TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a  TLS1.2
408           TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d  TLS1.2
409
410           Certificate types: CTYPE-X.509
411           Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
412           Compression: COMP-NULL
413           Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
414           PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
415
416       Connecting using a PKCS #11 token
417       To connect to a server using a certificate and a private key present in
418       a PKCS #11 token you need to substitute the PKCS 11 URLs in the
419       x509certfile and x509keyfile parameters.
420
421       Those can be found using "p11tool --list-tokens" and then listing all
422       the objects in the needed token, and using the appropriate.
423           $ p11tool --list-tokens
424
425           Token 0:
426           URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
427           Label: Test
428           Manufacturer: EnterSafe
429           Model: PKCS15
430           Serial: 1234
431
432           $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
433
434           Object 0:
435           URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
436           Type: X.509 Certificate
437           Label: client
438           ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
439
440           $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
441           $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
442           $ export MYCERT MYKEY
443
444           $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
445       Notice that the private key only differs from the certificate in the
446       type.
447

EXIT STATUS

449       One of the following exit values will be returned:
450
451       0  (EXIT_SUCCESS)
452              Successful program execution.
453
454       1  (EXIT_FAILURE)
455              The operation failed or the command syntax was not valid.
456
457       70  (EX_SOFTWARE)
458              libopts had an internal operational error.  Please report it to
459              autogen-users@lists.sourceforge.net.  Thank you.
460

SEE ALSO

462       gnutls-cli-debug(1), gnutls-serv(1)
463

AUTHORS

465       Nikos Mavrogiannopoulos, Simon Josefsson and others; see
466       /usr/share/doc/gnutls/AUTHORS for a complete list.
467
469       Copyright (C) 2000-2019 Free Software Foundation, and others all rights
470       reserved.  This program is released under the terms of the GNU General
471       Public License, version 3 or later.
472

BUGS

474       Please send bug reports to: bugs@gnutls.org
475

NOTES

477       This manual page was AutoGen-erated from the gnutls-cli option defini‐
478       tions.
479
480
481
4823.6.7                             27 Mar 2019                    gnutls-cli(1)
Impressum