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.
162 --save-server-trace=string
165 Save the server-side TLS message trace in the provided file.
166 --save-client-trace=string
169 Save the client-side TLS message trace in the provided file.
170 --dh-bits=number
173 The minimum number of bits allowed for DH. This option takes an
174 integer number as its argument.
175 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 --priority=string
182 Priorities string.
183 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 Check the GnuTLS manual on section “Priority strings” for
189 more information on the allowed keywords
190 --x509cafile=string
192 Certificate file or PKCS #11 URL to use.
193 --x509crlfile=file
196 CRL file to use.
197 --x509keyfile=string
200 X.509 key file or PKCS #11 URL to use.
201 --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 --rawpkkeyfile=string
209 Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
210 In order to instruct the application to negotiate raw public
212 keys one must enable the respective certificate types via the
213 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
214 Check the GnuTLS manual on section “Priority strings” for
216 more information on how to set certificate types.
217 --rawpkfile=string
219 Raw public-key file to use. This option must appear in combina‐
220 tion with the following options: rawpkkeyfile.
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 --srpusername=string
230 SRP username to use.
231 --srppasswd=string
234 SRP password to use.
235 --pskusername=string
238 PSK username to use.
239 --pskkey=string
242 PSK key (in hex) to use.
243 -p string, --port=string
246 The port or service to connect to.
247 --insecure
250 Don't abort program if server certificate can't be validated.
251 --verify-allow-broken
254 Allow broken algorithms, such as MD5 for certificate verifica‐
255 tion.
256 --ranges
259 Use length-hiding padding to prevent traffic analysis.
260 When possible (e.g., when using CBC ciphersuites), use length-
262 hiding padding to prevent traffic analysis.
263 NOTE: THIS OPTION IS DEPRECATED
265 --benchmark-ciphers
267 Benchmark individual ciphers.
268 By default the benchmarked ciphers will utilize any capabilities
270 of the local CPU to improve performance. To test against the raw
271 software implementation set the environment variable
272 GNUTLS_CPUID_OVERRIDE to 0x1.
273 --benchmark-tls-kx
275 Benchmark TLS key exchange methods.
276 --benchmark-tls-ciphers
279 Benchmark TLS ciphers.
280 By default the benchmarked ciphers will utilize any capabilities
282 of the local CPU to improve performance. To test against the raw
283 software implementation set the environment variable
284 GNUTLS_CPUID_OVERRIDE to 0x1.
285 -l, --list
287 Print a list of the supported algorithms and modes. This option
288 must not appear in combination with any of the following
289 options: port.
290 Print a list of the supported algorithms and modes. If a prior‐
292 ity string is given then only the enabled ciphersuites are
293 shown.
294 --priority-list
296 Print a list of the supported priority strings.
297 Print a list of the supported priority strings. The ciphersuites
299 corresponding to each priority string can be examined using -l
300 -p.
301 --noticket
303 Don't allow session tickets.
304 Disable the request of receiving of session tickets under TLS1.2
306 or earlier
307 --srtp-profiles=string
309 Offer SRTP profiles.
310 --alpn=string
313 Application layer protocol. This option may appear an unlimited
314 number of times.
315 This option will set and enable the Application Layer Protocol
317 Negotiation (ALPN) in the TLS protocol.
318 -b, --heartbeat
320 Activate heartbeat support.
321 --recordsize=number
324 The maximum record size to advertize. This option takes an
325 integer number as its argument. The value of number is con‐
326 strained to being:
327 in the range 0 through 4096
328 --disable-sni
331 Do not send a Server Name Indication (SNI).
332 --disable-extensions
335 Disable all the TLS extensions.
336 This option disables all TLS extensions. Deprecated option. Use
338 the priority string.
339 NOTE: THIS OPTION IS DEPRECATED
341 --single-key-share
343 Send a single key share under TLS1.3.
344 This option switches the default mode of sending multiple key
346 shares, to send a single one (the top one).
347 --post-handshake-auth
349 Enable post-handshake authentication under TLS1.3.
350 This option enables post-handshake authentication when under
352 TLS1.3.
353 --inline-commands
355 Inline commands of the form ^<cmd>^.
356 Enable inline commands of the form ^<cmd>^. The inline commands
358 are expected to be in a line by themselves. The available com‐
359 mands are: resume, rekey1 (local rekey), rekey (rekey on both
360 peers) and renegotiate.
361 --inline-commands-prefix=string
363 Change the default delimiter for inline commands..
364 Change the default delimiter (^) used for inline commands. The
366 delimiter is expected to be a single US-ASCII character (octets
367 0 - 127). This option is only relevant if inline commands are
368 enabled via the inline-commands option
369 --provider=file
371 Specify the PKCS #11 provider library.
372 This will override the default options in
374 /etc/gnutls/pkcs11.conf
375 --fips140-mode
377 Reports the status of the FIPS140-2 mode in gnutls library.
378 --logfile=string
381 Redirect informational messages to a specific file..
382 Redirect informational messages to a specific file. The file may
384 be /dev/null also to make the gnutls client quiet to use it in
385 piped server connections where only the server communication may
386 appear on stdout.
387 --keymatexport=string
389 Label used for exporting keying material.
390 --keymatexportsize=number
393 Size of the exported keying material. This option takes an
394 integer number as its argument.
395 -h, --help
398 Display usage information and exit.
399 -!, --more-help
401 Pass the extended usage information through a pager.
402 -v [{v|c|n --version [{v|c|n}]}]
404 Output version of program and exit. The default mode is `v', a
405 simple version. The `c' mode will print copyright information
406 and `n' will print the full copyright notice.
407
409 Connecting using PSK authentication
410 To connect to a server using PSK authentication, you need to enable the
411 choice of PSK by using a cipher priority parameter such as in the exam‐
412 ple below.
413 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
414 Resolving 'localhost'...
415 Connecting to '127.0.0.1:5556'...
416 - PSK authentication.
417 - Version: TLS1.1
418 - Key Exchange: PSK
419 - Cipher: AES-128-CBC
420 - MAC: SHA1
421 - Compression: NULL
422 - Handshake was completed
423 - Simple Client Mode:
424 By keeping the --pskusername parameter and removing the --pskkey param‐
425 eter, it will query only for the password during the handshake.
426 Connecting using raw public-key authentication
428 To connect to a server using raw public-key authentication, you need to
429 enable the option to negotiate raw public-keys via the priority strings
430 such as in the example below.
431 $ ./gnutls-cli -p 5556 localhost --priority NORMAL:-CTYPE-CLI-ALL:+CTYPE-CLI-RAWPK --rawpkkeyfile cli.key.pem --rawpkfile cli.rawpk.pem
432 Processed 1 client raw public key pair...
433 Resolving 'localhost'...
434 Connecting to '127.0.0.1:5556'...
435 - Successfully sent 1 certificate(s) to server.
436 - Server has requested a certificate.
437 - Certificate type: X.509
438 - Got a certificate list of 1 certificates.
439 - Certificate[0] info:
440 - skipped
441 - Description: (TLS1.3-Raw Public Key-X.509)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM)
442 - Options:
443 - Handshake was completed
444 - Simple Client Mode:
445 Connecting to STARTTLS services
447 You could also use the client to connect to services with starttls
449 capability.
450 $ gnutls-cli --starttls-proto smtp --port 25 localhost
451 Listing ciphersuites in a priority string
453 To list the ciphersuites in a priority string:
454 $ ./gnutls-cli --priority SECURE192 -l
455 Cipher suites for SECURE192
456 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
457 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
458 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
459 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
460 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
461 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
462 Certificate types: CTYPE-X.509
464 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
465 Compression: COMP-NULL
466 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
467 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
468 Connecting using a PKCS #11 token
470 To connect to a server using a certificate and a private key present in
471 a PKCS #11 token you need to substitute the PKCS 11 URLs in the
472 x509certfile and x509keyfile parameters.
473 Those can be found using "p11tool --list-tokens" and then listing all
475 the objects in the needed token, and using the appropriate.
476 $ p11tool --list-tokens
477 Token 0:
479 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
480 Label: Test
481 Manufacturer: EnterSafe
482 Model: PKCS15
483 Serial: 1234
484 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
486 Object 0:
488 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
489 Type: X.509 Certificate
490 Label: client
491 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
492 $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
494 $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
495 $ export MYCERT MYKEY
496 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
498 Notice that the private key only differs from the certificate in the
499 type.
500
502 One of the following exit values will be returned:
503 0 (EXIT_SUCCESS)
505 Successful program execution.
506 1 (EXIT_FAILURE)
508 The operation failed or the command syntax was not valid.
509 70 (EX_SOFTWARE)
511 libopts had an internal operational error. Please report it to
512 autogen-users@lists.sourceforge.net. Thank you.
513
515 gnutls-cli-debug(1), gnutls-serv(1)
516
518 Nikos Mavrogiannopoulos, Simon Josefsson and others; see
519 /usr/share/doc/gnutls/AUTHORS for a complete list.
520
522 Copyright (C) 2000-2019 Free Software Foundation, and others all rights
523 reserved. This program is released under the terms of the GNU General
524 Public License, version 3 or later.
525
527 Please send bug reports to: bugs@gnutls.org
528
530 This manual page was AutoGen-erated from the gnutls-cli option defini‐
531 tions.
5323.6.11 01 Dec 2019 gnutls-cli(1)