1gnutls-cli(1) User Commands gnutls-cli(1)
2
6 gnutls-cli - GnuTLS client
7
9 gnutls-cli [-flags] [-flag [value]] [--option-name[[=| ]value]] [host‐
10 name]
11 Operands and options may be intermixed. They will be reordered.
13
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
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 Specifies the debug level.
27 -V, --verbose
29 More verbose output. This option may appear an unlimited number
30 of times.
31 --tofu, --no-tofu
34 Enable trust on first use authentication. The no-tofu form will
35 disable the option.
36 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 --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 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 --dane, --no-dane
53 Enable DANE certificate verification (DNSSEC). The no-dane form
54 will disable the option.
55 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 --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 This option will use the local DNS server for DNSSEC. This is
65 disabled by default due to many servers not allowing DNSSEC.
66 --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 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 --ocsp, --no-ocsp
75 Enable OCSP certificate verification. The no-ocsp form will
76 disable the option.
77 This option will enable verification of the peer's certificate
79 using ocsp
80 -r, --resume
82 Establish a session and resume.
83 Connect, establish a session, reconnect and resume.
85 --earlydata=string
87 Send early data on resumption from the specified file.
88 -e, --rehandshake
91 Establish a session and rehandshake.
92 Connect, establish a session and rehandshake immediately.
94 --sni-hostname=string
96 Server's hostname for server name indication extension.
97 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 --verify-hostname=string
106 Server's hostname to use for validation.
107 Set explicitly the server name to be used when validating the
109 server's certificate.
110 -s, --starttls
112 Connect, establish a plain session and start TLS.
113 The TLS session will be initiated when EOF or a SIGALRM is
115 received.
116 --app-proto
118 This is an alias for the --starttls-proto option.
119 --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 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 -u, --udp
131 Use DTLS (datagram TLS) over UDP.
132 --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 --crlf Send CR LF instead of LF.
141 --fastopen
144 Enable TCP Fast Open.
145 --x509fmtder
148 Use DER format for certificates to read from.
149 --print-cert
152 Print peer's certificate in PEM format.
153 --save-cert=string
156 Save the peer's certificate chain in the specified file in PEM
157 format.
158 --save-ocsp=string
161 Save the peer's OCSP status response in the provided file. This
162 option must not appear in combination with any of the following
163 options: save-ocsp-multi.
164 --save-ocsp-multi=string
167 Save all OCSP responses provided by the peer in this file. This
168 option must not appear in combination with any of the following
169 options: save-ocsp.
170 The file will contain a list of PEM encoded OCSP status
172 responses if any were provided by the peer, starting with the
173 one for the peer's server certificate.
174 --save-server-trace=string
176 Save the server-side TLS message trace in the provided file.
177 --save-client-trace=string
180 Save the client-side TLS message trace in the provided file.
181 --dh-bits=number
184 The minimum number of bits allowed for DH. This option takes an
185 integer number as its argument.
186 This option sets the minimum number of bits allowed for a
188 Diffie-Hellman key exchange. You may want to lower the default
189 value if the peer sends a weak prime and you get an connection
190 error with unacceptable prime.
191 --priority=string
193 Priorities string.
194 TLS algorithms and protocols to enable. You can use predefined
196 sets of ciphersuites such as PERFORMANCE, NORMAL, PFS,
197 SECURE128, SECURE256. The default is NORMAL.
198 Check the GnuTLS manual on section “Priority strings” for
200 more information on the allowed keywords
201 --x509cafile=string
203 Certificate file or PKCS #11 URL to use.
204 --x509crlfile=file
207 CRL file to use.
208 --x509keyfile=string
211 X.509 key file or PKCS #11 URL to use.
212 --x509certfile=string
215 X.509 Certificate file or PKCS #11 URL to use. This option must
216 appear in combination with the following options: x509keyfile.
217 --rawpkkeyfile=string
220 Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
221 In order to instruct the application to negotiate raw public
223 keys one must enable the respective certificate types via the
224 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
225 Check the GnuTLS manual on section “Priority strings” for
227 more information on how to set certificate types.
228 --rawpkfile=string
230 Raw public-key file to use. This option must appear in combina‐
231 tion with the following options: rawpkkeyfile.
232 In order to instruct the application to negotiate raw public
234 keys one must enable the respective certificate types via the
235 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
236 Check the GnuTLS manual on section “Priority strings” for
238 more information on how to set certificate types.
239 --srpusername=string
241 SRP username to use.
242 --srppasswd=string
245 SRP password to use.
246 --pskusername=string
249 PSK username to use.
250 --pskkey=string
253 PSK key (in hex) to use.
254 -p string, --port=string
257 The port or service to connect to.
258 --insecure
261 Don't abort program if server certificate can't be validated.
262 --verify-allow-broken
265 Allow broken algorithms, such as MD5 for certificate verifica‐
266 tion.
267 --ranges
270 Use length-hiding padding to prevent traffic analysis.
271 When possible (e.g., when using CBC ciphersuites), use length-
273 hiding padding to prevent traffic analysis.
274 NOTE: THIS OPTION IS DEPRECATED
276 --benchmark-ciphers
278 Benchmark individual ciphers.
279 By default the benchmarked ciphers will utilize any capabilities
281 of the local CPU to improve performance. To test against the raw
282 software implementation set the environment variable
283 GNUTLS_CPUID_OVERRIDE to 0x1.
284 --benchmark-tls-kx
286 Benchmark TLS key exchange methods.
287 --benchmark-tls-ciphers
290 Benchmark TLS ciphers.
291 By default the benchmarked ciphers will utilize any capabilities
293 of the local CPU to improve performance. To test against the raw
294 software implementation set the environment variable
295 GNUTLS_CPUID_OVERRIDE to 0x1.
296 -l, --list
298 Print a list of the supported algorithms and modes. This option
299 must not appear in combination with any of the following
300 options: port.
301 Print a list of the supported algorithms and modes. If a prior‐
303 ity string is given then only the enabled ciphersuites are
304 shown.
305 --priority-list
307 Print a list of the supported priority strings.
308 Print a list of the supported priority strings. The ciphersuites
310 corresponding to each priority string can be examined using -l
311 -p.
312 --noticket
314 Don't allow session tickets.
315 Disable the request of receiving of session tickets under TLS1.2
317 or earlier
318 --srtp-profiles=string
320 Offer SRTP profiles.
321 --alpn=string
324 Application layer protocol. This option may appear an unlimited
325 number of times.
326 This option will set and enable the Application Layer Protocol
328 Negotiation (ALPN) in the TLS protocol.
329 -b, --heartbeat
331 Activate heartbeat support.
332 --recordsize=number
335 The maximum record size to advertize. This option takes an
336 integer number as its argument. The value of number is con‐
337 strained to being:
338 in the range 0 through 4096
339 --disable-sni
342 Do not send a Server Name Indication (SNI).
343 --disable-extensions
346 Disable all the TLS extensions.
347 This option disables all TLS extensions. Deprecated option. Use
349 the priority string.
350 NOTE: THIS OPTION IS DEPRECATED
352 --single-key-share
354 Send a single key share under TLS1.3.
355 This option switches the default mode of sending multiple key
357 shares, to send a single one (the top one).
358 --post-handshake-auth
360 Enable post-handshake authentication under TLS1.3.
361 This option enables post-handshake authentication when under
363 TLS1.3.
364 --inline-commands
366 Inline commands of the form ^<cmd>^.
367 Enable inline commands of the form ^<cmd>^. The inline commands
369 are expected to be in a line by themselves. The available com‐
370 mands are: resume, rekey1 (local rekey), rekey (rekey on both
371 peers) and renegotiate.
372 --inline-commands-prefix=string
374 Change the default delimiter for inline commands..
375 Change the default delimiter (^) used for inline commands. The
377 delimiter is expected to be a single US-ASCII character (octets
378 0 - 127). This option is only relevant if inline commands are
379 enabled via the inline-commands option
380 --provider=file
382 Specify the PKCS #11 provider library.
383 This will override the default options in
385 /etc/gnutls/pkcs11.conf
386 --fips140-mode
388 Reports the status of the FIPS140-2 mode in gnutls library.
389 --logfile=string
392 Redirect informational messages to a specific file..
393 Redirect informational messages to a specific file. The file may
395 be /dev/null also to make the gnutls client quiet to use it in
396 piped server connections where only the server communication may
397 appear on stdout.
398 --keymatexport=string
400 Label used for exporting keying material.
401 --keymatexportsize=number
404 Size of the exported keying material. This option takes an
405 integer number as its argument.
406 -h, --help
409 Display usage information and exit.
410 -!, --more-help
412 Pass the extended usage information through a pager.
413 -v [{v|c|n --version [{v|c|n}]}]
415 Output version of program and exit. The default mode is `v', a
416 simple version. The `c' mode will print copyright information
417 and `n' will print the full copyright notice.
418
420 Connecting using PSK authentication
421 To connect to a server using PSK authentication, you need to enable the
422 choice of PSK by using a cipher priority parameter such as in the exam‐
423 ple below.
424 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
425 Resolving 'localhost'...
426 Connecting to '127.0.0.1:5556'...
427 - PSK authentication.
428 - Version: TLS1.1
429 - Key Exchange: PSK
430 - Cipher: AES-128-CBC
431 - MAC: SHA1
432 - Compression: NULL
433 - Handshake was completed
434 - Simple Client Mode:
435 By keeping the --pskusername parameter and removing the --pskkey param‐
436 eter, it will query only for the password during the handshake.
437 Connecting using raw public-key authentication
439 To connect to a server using raw public-key authentication, you need to
440 enable the option to negotiate raw public-keys via the priority strings
441 such as in the example below.
442 $ ./gnutls-cli -p 5556 localhost --priority NORMAL:-CTYPE-CLI-ALL:+CTYPE-CLI-RAWPK --rawpkkeyfile cli.key.pem --rawpkfile cli.rawpk.pem
443 Processed 1 client raw public key pair...
444 Resolving 'localhost'...
445 Connecting to '127.0.0.1:5556'...
446 - Successfully sent 1 certificate(s) to server.
447 - Server has requested a certificate.
448 - Certificate type: X.509
449 - Got a certificate list of 1 certificates.
450 - Certificate[0] info:
451 - skipped
452 - Description: (TLS1.3-Raw Public Key-X.509)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM)
453 - Options:
454 - Handshake was completed
455 - Simple Client Mode:
456 Connecting to STARTTLS services
458 You could also use the client to connect to services with starttls
460 capability.
461 $ gnutls-cli --starttls-proto smtp --port 25 localhost
462 Listing ciphersuites in a priority string
464 To list the ciphersuites in a priority string:
465 $ ./gnutls-cli --priority SECURE192 -l
466 Cipher suites for SECURE192
467 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
468 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
469 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
470 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
471 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
472 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
473 Certificate types: CTYPE-X.509
475 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
476 Compression: COMP-NULL
477 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
478 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
479 Connecting using a PKCS #11 token
481 To connect to a server using a certificate and a private key present in
482 a PKCS #11 token you need to substitute the PKCS 11 URLs in the
483 x509certfile and x509keyfile parameters.
484 Those can be found using "p11tool --list-tokens" and then listing all
486 the objects in the needed token, and using the appropriate.
487 $ p11tool --list-tokens
488 Token 0:
490 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
491 Label: Test
492 Manufacturer: EnterSafe
493 Model: PKCS15
494 Serial: 1234
495 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
497 Object 0:
499 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
500 Type: X.509 Certificate
501 Label: client
502 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
503 $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
505 $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
506 $ export MYCERT MYKEY
507 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
509 Notice that the private key only differs from the certificate in the
510 type.
511
513 One of the following exit values will be returned:
514 0 (EXIT_SUCCESS)
516 Successful program execution.
517 1 (EXIT_FAILURE)
519 The operation failed or the command syntax was not valid.
520 70 (EX_SOFTWARE)
522 libopts had an internal operational error. Please report it to
523 autogen-users@lists.sourceforge.net. Thank you.
524
526 gnutls-cli-debug(1), gnutls-serv(1)
527
529 Nikos Mavrogiannopoulos, Simon Josefsson and others; see
530 /usr/share/doc/gnutls/AUTHORS for a complete list.
531
533 Copyright (C) 2000-2020 Free Software Foundation, and others all rights
534 reserved. This program is released under the terms of the GNU General
535 Public License, version 3 or later.
536
538 Please send bug reports to: bugs@gnutls.org
539
541 This manual page was AutoGen-erated from the gnutls-cli option defini‐
542 tions.
5433.6.12 28 Mar 2020 gnutls-cli(1)