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
15 Simple client program to set up a TLS connection to some other com‐
16 puter. It sets up a TLS connection and forwards data from the standard
17 input to the secured socket and vice versa.
18
21 -d num, --debug=num
22 Enable debugging. This option takes an integer number as its
23 argument. The value of num is constrained to being:
24 in the range 0 through 9999
25 Specifies the debug level.
27 -V, --verbose
29 More verbose output.
30 --tofu, --no-tofu
33 Enable trust on first use authentication. The no-tofu form will
34 disable the option.
35 This option will, in addition to certificate authentication,
37 perform authentication based on previously seen public keys, a
38 model similar to SSH authentication. Note that when tofu is
39 specified (PKI) and DANE authentication will become advisory to
40 assist the public key acceptance process.
41 --strict-tofu, --no-strict-tofu
43 Fail to connect if a certificate is unknown or a known certifi‐
44 cate has changed. The no-strict-tofu form will disable the op‐
45 tion.
46 This option will perform authentication as with option --tofu;
48 however, no questions shall be asked whatsoever, neither to ac‐
49 cept an unknown certificate nor a changed one.
50 --dane, --no-dane
52 Enable DANE certificate verification (DNSSEC). The no-dane form
53 will disable the option.
54 This option will, in addition to certificate authentication us‐
56 ing the trusted CAs, verify the server certificates using on the
57 DANE information available via DNSSEC.
58 --local-dns, --no-local-dns
60 Use the local DNS server for DNSSEC resolving. The no-local-dns
61 form will disable the option.
62 This option will use the local DNS server for DNSSEC. This is
64 disabled by default due to many servers not allowing DNSSEC.
65 --ca-verification, --no-ca-verification
67 Enable CA certificate verification. The no-ca-verification form
68 will disable the option. This option is enabled by default.
69 This option can be used to enable or disable CA certificate ver‐
71 ification. It is to be used with the --dane or --tofu options.
72 --ocsp, --no-ocsp
74 Enable OCSP certificate verification. The no-ocsp form will
75 disable the option.
76 This option will enable verification of the peer's certificate
78 using ocsp
79 -r, --resume
81 Establish a session and resume.
82 Connect, establish a session, reconnect and resume.
84 --earlydata=str
86 Send early data on resumption from the specified file.
87 -e, --rehandshake
90 Establish a session and rehandshake.
91 Connect, establish a session and rehandshake immediately.
93 --sni-hostname=str
95 Server's hostname for server name indication extension.
96 Set explicitly the server name used in the TLS server name indi‐
98 cation extension. That is useful when testing with servers setup
99 on different DNS name than the intended. If not specified, the
100 provided hostname is used. Even with this option server certifi‐
101 cate verification still uses the hostname passed on the main
102 commandline. Use --verify-hostname to change this.
103 --verify-hostname=str
105 Server's hostname to use for validation.
106 Set explicitly the server name to be used when validating the
108 server's certificate.
109 -s, --starttls
111 Connect, establish a plain session and start TLS.
112 The TLS session will be initiated when EOF or a SIGALRM is re‐
114 ceived.
115 --app-proto
117 This is an alias for the --starttls-proto option.
118 --starttls-proto=str
120 The application protocol to be used to obtain the server's cer‐
121 tificate (https, ftp, smtp, imap, ldap, xmpp, lmtp, pop3, nntp,
122 sieve, postgres). This option must not appear in combination
123 with any of the following options: starttls.
124 Specify the application layer protocol for STARTTLS. If the pro‐
126 tocol is supported, gnutls-cli will proceed to the TLS negotia‐
127 tion.
128 --starttls-name=str
130 The hostname presented to the application protocol for STARTTLS
131 (for smtp, xmpp, lmtp). This option must not appear in combina‐
132 tion with any of the following options: starttls. This option
133 must appear in combination with the following options: starttls-
134 proto.
135 Specify the hostname presented to the application protocol for
137 STARTTLS.
138 -u, --udp
140 Use DTLS (datagram TLS) over UDP.
141 --mtu=num
144 Set MTU for datagram TLS. This option takes an integer number
145 as its argument. The value of num is constrained to being:
146 in the range 0 through 17000
147 --crlf Send CR LF instead of LF.
150 --fastopen
153 Enable TCP Fast Open.
154 --x509fmtder
157 Use DER format for certificates to read from.
158 --print-cert
161 Print peer's certificate in PEM format.
162 --save-cert=str
165 Save the peer's certificate chain in the specified file in PEM
166 format.
167 --save-ocsp=str
170 Save the peer's OCSP status response in the provided file. This
171 option must not appear in combination with any of the following
172 options: save-ocsp-multi.
173 --save-ocsp-multi=str
176 Save all OCSP responses provided by the peer in this file. This
177 option must not appear in combination with any of the following
178 options: save-ocsp.
179 The file will contain a list of PEM encoded OCSP status re‐
181 sponses if any were provided by the peer, starting with the one
182 for the peer's server certificate.
183 --save-server-trace=str
185 Save the server-side TLS message trace in the provided file.
186 --save-client-trace=str
189 Save the client-side TLS message trace in the provided file.
190 --dh-bits=num
193 The minimum number of bits allowed for DH. This option takes an
194 integer number as its argument.
195 This option sets the minimum number of bits allowed for a
197 Diffie-Hellman key exchange. You may want to lower the default
198 value if the peer sends a weak prime and you get an connection
199 error with unacceptable prime.
200 --priority=str
202 Priorities string.
203 TLS algorithms and protocols to enable. You can use predefined
205 sets of ciphersuites such as PERFORMANCE, NORMAL, PFS, SE‐
206 CURE128, SECURE256. The default is NORMAL.
207 Check the GnuTLS manual on section “Priority strings” for
209 more information on the allowed keywords
210 --x509cafile=str
212 Certificate file or PKCS #11 URL to use.
213 --x509crlfile=file
216 CRL file to use.
217 --x509keyfile=str
220 X.509 key file or PKCS #11 URL to use.
221 --x509certfile=str
224 X.509 Certificate file or PKCS #11 URL to use. This option must
225 appear in combination with the following options: x509keyfile.
226 --rawpkkeyfile=str
229 Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
230 In order to instruct the application to negotiate raw public
232 keys one must enable the respective certificate types via the
233 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
234 Check the GnuTLS manual on section “Priority strings” for
236 more information on how to set certificate types.
237 --rawpkfile=str
239 Raw public-key file to use. This option must appear in combina‐
240 tion with the following options: rawpkkeyfile.
241 In order to instruct the application to negotiate raw public
243 keys one must enable the respective certificate types via the
244 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
245 Check the GnuTLS manual on section “Priority strings” for
247 more information on how to set certificate types.
248 --srpusername=str
250 SRP username to use.
251 --srppasswd=str
254 SRP password to use.
255 --pskusername=str
258 PSK username to use.
259 --pskkey=str
262 PSK key (in hex) to use.
263 -p str, --port=str
266 The port or service to connect to.
267 --insecure
270 Don't abort program if server certificate can't be validated.
271 --verify-allow-broken
274 Allow broken algorithms, such as MD5 for certificate verifica‐
275 tion.
276 --ranges
279 Use length-hiding padding to prevent traffic analysis.
280 When possible (e.g., when using CBC ciphersuites), use
282 length-hiding padding to prevent traffic analysis.
283 NOTE: THIS OPTION IS DEPRECATED
285 --benchmark-ciphers
287 Benchmark individual ciphers.
288 By default the benchmarked ciphers will utilize any capabilities
290 of the local CPU to improve performance. To test against the raw
291 software implementation set the environment variable
292 GNUTLS_CPUID_OVERRIDE to 0x1.
293 --benchmark-tls-kx
295 Benchmark TLS key exchange methods.
296 --benchmark-tls-ciphers
299 Benchmark TLS ciphers.
300 By default the benchmarked ciphers will utilize any capabilities
302 of the local CPU to improve performance. To test against the raw
303 software implementation set the environment variable
304 GNUTLS_CPUID_OVERRIDE to 0x1.
305 -l, --list
307 Print a list of the supported algorithms and modes. This option
308 must not appear in combination with any of the following op‐
309 tions: port.
310 Print a list of the supported algorithms and modes. If a prior‐
312 ity string is given then only the enabled ciphersuites are
313 shown.
314 --priority-list
316 Print a list of the supported priority strings.
317 Print a list of the supported priority strings. The ciphersuites
319 corresponding to each priority string can be examined using -l
320 -p.
321 --noticket
323 Don't allow session tickets.
324 Disable the request of receiving of session tickets under TLS1.2
326 or earlier
327 --srtp-profiles=str
329 Offer SRTP profiles.
330 --alpn=str
333 Application layer protocol. This option may appear an unlimited
334 number of times.
335 This option will set and enable the Application Layer Protocol
337 Negotiation (ALPN) in the TLS protocol.
338 --compress-cert=str
340 Compress certificate. This option may appear an unlimited num‐
341 ber of times.
342 This option sets a supported compression method for certificate
344 compression.
345 -b, --heartbeat
347 Activate heartbeat support.
348 --recordsize=num
351 The maximum record size to advertise. This option takes an in‐
352 teger number as its argument. The value of num is constrained
353 to being:
354 in the range 0 through 4096
355 --disable-sni
358 Do not send a Server Name Indication (SNI).
359 --disable-extensions
362 Disable all the TLS extensions.
363 This option disables all TLS extensions. Deprecated option. Use
365 the priority string.
366 NOTE: THIS OPTION IS DEPRECATED
368 --single-key-share
370 Send a single key share under TLS1.3.
371 This option switches the default mode of sending multiple key
373 shares, to send a single one (the top one).
374 --post-handshake-auth
376 Enable post-handshake authentication under TLS1.3.
377 This option enables post-handshake authentication when under
379 TLS1.3.
380 --inline-commands
382 Inline commands of the form ^<cmd>^.
383 Enable inline commands of the form ^<cmd>^. The inline commands
385 are expected to be in a line by themselves. The available com‐
386 mands are: resume, rekey1 (local rekey), rekey (rekey on both
387 peers) and renegotiate.
388 --inline-commands-prefix=str
390 Change the default delimiter for inline commands.
391 Change the default delimiter (^) used for inline commands. The
393 delimiter is expected to be a single US-ASCII character (octets
394 0 - 127). This option is only relevant if inline commands are
395 enabled via the inline-commands option
396 --provider=file
398 Specify the PKCS #11 provider library.
399 This will override the default options in
401 /etc/gnutls/pkcs11.conf
402 --fips140-mode
404 Reports the status of the FIPS140-2 mode in gnutls library.
405 --list-config
408 Reports the configuration of the library.
409 --logfile=str
412 Redirect informational messages to a specific file.
413 Redirect informational messages to a specific file. The file may
415 be /dev/null also to make the gnutls client quiet to use it in
416 piped server connections where only the server communication may
417 appear on stdout.
418 --keymatexport=str
420 Label used for exporting keying material.
421 --keymatexportsize=num
424 Size of the exported keying material. This option takes an in‐
425 teger number as its argument.
426 --waitresumption
429 Block waiting for the resumption data under TLS1.3.
430 This option makes the client to block waiting for the resumption
432 data under TLS1.3. The option has effect only when --resume is
433 provided.
434 --ca-auto-retrieve, --no-ca-auto-retrieve
436 Enable automatic retrieval of missing CA certificates. The
437 no-ca-auto-retrieve form will disable the option.
438 This option enables the client to automatically retrieve the
440 missing intermediate CA certificates in the certificate chain,
441 based on the Authority Information Access (AIA) extension.
442 --attime=timestamp
444 Perform validation at the timestamp instead of the system time.
445 timestamp is an instance in time encoded as Unix time or in a
447 human
448 readable timestring such as "29 Feb 2004", "2004-02-29". Full
449 documentation available at <https://www.gnu.org/software/core‐
450 utils/manual/html_node/Date-input-formats.html> or locally via
451 info '(coreutils) date invocation'.
452 -v arg, --version=arg
454 Output version of program and exit. The default mode is `v', a
455 simple version. The `c' mode will print copyright information
456 and `n' will print the full copyright notice.
457 -h, --help
459 Display usage information and exit.
460 -!, --more-help
462 Pass the extended usage information through a pager.
463
467 Connecting using PSK authentication
468 To connect to a server using PSK authentication, you need to enable the
469 choice of PSK by using a cipher priority parameter such as in the exam‐
470 ple below.
471 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
472 Resolving 'localhost'...
473 Connecting to '127.0.0.1:5556'...
474 - PSK authentication.
475 - Version: TLS1.1
476 - Key Exchange: PSK
477 - Cipher: AES-128-CBC
478 - MAC: SHA1
479 - Compression: NULL
480 - Handshake was completed
481 - Simple Client Mode:
483 By keeping the --pskusername parameter and removing the --pskkey param‐
484 eter, it will query only for the password during the handshake.
485 Connecting using raw public-key authentication
487 To connect to a server using raw public-key authentication, you need to
488 enable the option to negotiate raw public-keys via the priority strings
489 such as in the example below.
490 $ ./gnutls-cli -p 5556 localhost --priority NORMAL:-CTYPE-CLI-ALL:+CTYPE-CLI-RAWPK --rawpkkeyfile cli.key.pem --rawpkfile cli.rawpk.pem
491 Processed 1 client raw public key pair...
492 Resolving 'localhost'...
493 Connecting to '127.0.0.1:5556'...
494 - Successfully sent 1 certificate(s) to server.
495 - Server has requested a certificate.
496 - Certificate type: X.509
497 - Got a certificate list of 1 certificates.
498 - Certificate[0] info:
499 - skipped
500 - Description: (TLS1.3-Raw Public Key-X.509)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM)
501 - Options:
502 - Handshake was completed
503 - Simple Client Mode:
505 Connecting to STARTTLS services
507 You could also use the client to connect to services with starttls ca‐
509 pability.
510 $ gnutls-cli --starttls-proto smtp --port 25 localhost
511 Listing ciphersuites in a priority string
513 To list the ciphersuites in a priority string:
514 $ ./gnutls-cli --priority SECURE192 -l
515 Cipher suites for SECURE192
516 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
517 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
518 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
519 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
520 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
521 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
522 Certificate types: CTYPE-X.509
524 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
525 Compression: COMP-NULL
526 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
527 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
528 Connecting using a PKCS #11 token
530 To connect to a server using a certificate and a private key present in
531 a PKCS #11 token you need to substitute the PKCS 11 URLs in the
532 x509certfile and x509keyfile parameters.
533 Those can be found using "p11tool --list-tokens" and then listing all
535 the objects in the needed token, and using the appropriate.
536 $ p11tool --list-tokens
537 Token 0:
539 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
540 Label: Test
541 Manufacturer: EnterSafe
542 Model: PKCS15
543 Serial: 1234
544 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
546 Object 0:
548 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
549 Type: X.509 Certificate
550 Label: client
551 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
552 $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
554 $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
555 $ export MYCERT MYKEY
556 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
558 Notice that the private key only differs from the certificate in the
559 type.
560
562 One of the following exit values will be returned:
563 0 (EXIT_SUCCESS)
565 Successful program execution.
566 1 (EXIT_FAILURE)
568 The operation failed or the command syntax was not valid.
569
571 gnutls-cli-debug(1), gnutls-serv(1)
572
575 Copyright (C) 2020-2023 Free Software Foundation, and others all rights
576 reserved. This program is released under the terms of the GNU General
577 Public License, version 3 or later
578
580 Please send bug reports to: bugs@gnutls.org
5813.8.2 15 Nov 2023 gnutls-cli(1)