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 op‐
46 tion.
47 This option will perform authentication as with option --tofu;
49 however, no questions shall be asked whatsoever, neither to ac‐
50 cept 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 us‐
57 ing the trusted CAs, verify the server certificates using on the
58 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 re‐
115 ceived.
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 re‐
172 sponses if any were provided by the peer, starting with the one
173 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, SE‐
197 CURE128, 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 op‐
300 tions: 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 advertise. This option takes an in‐
336 teger 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 in‐
405 teger number as its argument.
406 --waitresumption
409 Block waiting for the resumption data under TLS1.3.
410 This option makes the client to block waiting for the resumption
412 data under TLS1.3. The option has effect only when --resume is
413 provided.
414 --ca-auto-retrieve, --no-ca-auto-retrieve
416 Enable automatic retrieval of missing CA certificates. The
417 no-ca-auto-retrieve form will disable the option.
418 This option enables the client to automatically retrieve the
420 missing intermediate CA certificates in the certificate chain,
421 based on the Authority Information Access (AIA) extension.
422 -h, --help
424 Display usage information and exit.
425 -!, --more-help
427 Pass the extended usage information through a pager.
428 -v [{v|c|n --version [{v|c|n}]}]
430 Output version of program and exit. The default mode is `v', a
431 simple version. The `c' mode will print copyright information
432 and `n' will print the full copyright notice.
433
435 Connecting using PSK authentication
436 To connect to a server using PSK authentication, you need to enable the
437 choice of PSK by using a cipher priority parameter such as in the exam‐
438 ple below.
439 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
440 Resolving 'localhost'...
441 Connecting to '127.0.0.1:5556'...
442 - PSK authentication.
443 - Version: TLS1.1
444 - Key Exchange: PSK
445 - Cipher: AES-128-CBC
446 - MAC: SHA1
447 - Compression: NULL
448 - Handshake was completed
449 - Simple Client Mode:
450 By keeping the --pskusername parameter and removing the --pskkey param‐
451 eter, it will query only for the password during the handshake.
452 Connecting using raw public-key authentication
454 To connect to a server using raw public-key authentication, you need to
455 enable the option to negotiate raw public-keys via the priority strings
456 such as in the example below.
457 $ ./gnutls-cli -p 5556 localhost --priority NORMAL:-CTYPE-CLI-ALL:+CTYPE-CLI-RAWPK --rawpkkeyfile cli.key.pem --rawpkfile cli.rawpk.pem
458 Processed 1 client raw public key pair...
459 Resolving 'localhost'...
460 Connecting to '127.0.0.1:5556'...
461 - Successfully sent 1 certificate(s) to server.
462 - Server has requested a certificate.
463 - Certificate type: X.509
464 - Got a certificate list of 1 certificates.
465 - Certificate[0] info:
466 - skipped
467 - Description: (TLS1.3-Raw Public Key-X.509)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM)
468 - Options:
469 - Handshake was completed
470 - Simple Client Mode:
471 Connecting to STARTTLS services
473 You could also use the client to connect to services with starttls ca‐
475 pability.
476 $ gnutls-cli --starttls-proto smtp --port 25 localhost
477 Listing ciphersuites in a priority string
479 To list the ciphersuites in a priority string:
480 $ ./gnutls-cli --priority SECURE192 -l
481 Cipher suites for SECURE192
482 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
483 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
484 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
485 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
486 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
487 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
488 Certificate types: CTYPE-X.509
490 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
491 Compression: COMP-NULL
492 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
493 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
494 Connecting using a PKCS #11 token
496 To connect to a server using a certificate and a private key present in
497 a PKCS #11 token you need to substitute the PKCS 11 URLs in the
498 x509certfile and x509keyfile parameters.
499 Those can be found using "p11tool --list-tokens" and then listing all
501 the objects in the needed token, and using the appropriate.
502 $ p11tool --list-tokens
503 Token 0:
505 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
506 Label: Test
507 Manufacturer: EnterSafe
508 Model: PKCS15
509 Serial: 1234
510 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
512 Object 0:
514 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
515 Type: X.509 Certificate
516 Label: client
517 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
518 $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
520 $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
521 $ export MYCERT MYKEY
522 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
524 Notice that the private key only differs from the certificate in the
525 type.
526
528 One of the following exit values will be returned:
529 0 (EXIT_SUCCESS)
531 Successful program execution.
532 1 (EXIT_FAILURE)
534 The operation failed or the command syntax was not valid.
535 70 (EX_SOFTWARE)
537 libopts had an internal operational error. Please report it to
538 autogen-users@lists.sourceforge.net. Thank you.
539
541 gnutls-cli-debug(1), gnutls-serv(1)
542
544 Nikos Mavrogiannopoulos, Simon Josefsson and others; see
545 /usr/share/doc/gnutls/AUTHORS for a complete list.
546
548 Copyright (C) 2000-2020 Free Software Foundation, and others all rights
549 reserved. This program is released under the terms of the GNU General
550 Public License, version 3 or later.
551
553 Please send bug reports to: bugs@gnutls.org
554
556 This manual page was AutoGen-erated from the gnutls-cli option defini‐
557 tions.
5583.7.2 29 May 2021 gnutls-cli(1)