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 -u, --udp
130 Use DTLS (datagram TLS) over UDP.
131 --mtu=num
134 Set MTU for datagram TLS. This option takes an integer number
135 as its argument. The value of num is constrained to being:
136 in the range 0 through 17000
137 --crlf Send CR LF instead of LF.
140 --fastopen
143 Enable TCP Fast Open.
144 --x509fmtder
147 Use DER format for certificates to read from.
148 --print-cert
151 Print peer's certificate in PEM format.
152 --save-cert=str
155 Save the peer's certificate chain in the specified file in PEM
156 format.
157 --save-ocsp=str
160 Save the peer's OCSP status response in the provided file. This
161 option must not appear in combination with any of the following
162 options: save-ocsp-multi.
163 --save-ocsp-multi=str
166 Save all OCSP responses provided by the peer in this file. This
167 option must not appear in combination with any of the following
168 options: save-ocsp.
169 The file will contain a list of PEM encoded OCSP status re‐
171 sponses if any were provided by the peer, starting with the one
172 for the peer's server certificate.
173 --save-server-trace=str
175 Save the server-side TLS message trace in the provided file.
176 --save-client-trace=str
179 Save the client-side TLS message trace in the provided file.
180 --dh-bits=num
183 The minimum number of bits allowed for DH. This option takes an
184 integer number as its argument.
185 This option sets the minimum number of bits allowed for a
187 Diffie-Hellman key exchange. You may want to lower the default
188 value if the peer sends a weak prime and you get an connection
189 error with unacceptable prime.
190 --priority=str
192 Priorities string.
193 TLS algorithms and protocols to enable. You can use predefined
195 sets of ciphersuites such as PERFORMANCE, NORMAL, PFS, SE‐
196 CURE128, SECURE256. The default is NORMAL.
197 Check the GnuTLS manual on section “Priority strings” for
199 more information on the allowed keywords
200 --x509cafile=str
202 Certificate file or PKCS #11 URL to use.
203 --x509crlfile=file
206 CRL file to use.
207 --x509keyfile=str
210 X.509 key file or PKCS #11 URL to use.
211 --x509certfile=str
214 X.509 Certificate file or PKCS #11 URL to use. This option must
215 appear in combination with the following options: x509keyfile.
216 --rawpkkeyfile=str
219 Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
220 In order to instruct the application to negotiate raw public
222 keys one must enable the respective certificate types via the
223 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
224 Check the GnuTLS manual on section “Priority strings” for
226 more information on how to set certificate types.
227 --rawpkfile=str
229 Raw public-key file to use. This option must appear in combina‐
230 tion with the following options: rawpkkeyfile.
231 In order to instruct the application to negotiate raw public
233 keys one must enable the respective certificate types via the
234 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
235 Check the GnuTLS manual on section “Priority strings” for
237 more information on how to set certificate types.
238 --srpusername=str
240 SRP username to use.
241 --srppasswd=str
244 SRP password to use.
245 --pskusername=str
248 PSK username to use.
249 --pskkey=str
252 PSK key (in hex) to use.
253 -p str, --port=str
256 The port or service to connect to.
257 --insecure
260 Don't abort program if server certificate can't be validated.
261 --verify-allow-broken
264 Allow broken algorithms, such as MD5 for certificate verifica‐
265 tion.
266 --ranges
269 Use length-hiding padding to prevent traffic analysis.
270 When possible (e.g., when using CBC ciphersuites), use
272 length-hiding padding to prevent traffic analysis.
273 NOTE: THIS OPTION IS DEPRECATED
275 --benchmark-ciphers
277 Benchmark individual ciphers.
278 By default the benchmarked ciphers will utilize any capabilities
280 of the local CPU to improve performance. To test against the raw
281 software implementation set the environment variable
282 GNUTLS_CPUID_OVERRIDE to 0x1.
283 --benchmark-tls-kx
285 Benchmark TLS key exchange methods.
286 --benchmark-tls-ciphers
289 Benchmark TLS ciphers.
290 By default the benchmarked ciphers will utilize any capabilities
292 of the local CPU to improve performance. To test against the raw
293 software implementation set the environment variable
294 GNUTLS_CPUID_OVERRIDE to 0x1.
295 -l, --list
297 Print a list of the supported algorithms and modes. This option
298 must not appear in combination with any of the following op‐
299 tions: port.
300 Print a list of the supported algorithms and modes. If a prior‐
302 ity string is given then only the enabled ciphersuites are
303 shown.
304 --priority-list
306 Print a list of the supported priority strings.
307 Print a list of the supported priority strings. The ciphersuites
309 corresponding to each priority string can be examined using -l
310 -p.
311 --noticket
313 Don't allow session tickets.
314 Disable the request of receiving of session tickets under TLS1.2
316 or earlier
317 --srtp-profiles=str
319 Offer SRTP profiles.
320 --alpn=str
323 Application layer protocol. This option may appear an unlimited
324 number of times.
325 This option will set and enable the Application Layer Protocol
327 Negotiation (ALPN) in the TLS protocol.
328 --compress-cert=str
330 Compress certificate. This option may appear an unlimited num‐
331 ber of times.
332 This option sets a supported compression method for certificate
334 compression.
335 -b, --heartbeat
337 Activate heartbeat support.
338 --recordsize=num
341 The maximum record size to advertise. This option takes an in‐
342 teger number as its argument. The value of num is constrained
343 to being:
344 in the range 0 through 4096
345 --disable-sni
348 Do not send a Server Name Indication (SNI).
349 --disable-extensions
352 Disable all the TLS extensions.
353 This option disables all TLS extensions. Deprecated option. Use
355 the priority string.
356 NOTE: THIS OPTION IS DEPRECATED
358 --single-key-share
360 Send a single key share under TLS1.3.
361 This option switches the default mode of sending multiple key
363 shares, to send a single one (the top one).
364 --post-handshake-auth
366 Enable post-handshake authentication under TLS1.3.
367 This option enables post-handshake authentication when under
369 TLS1.3.
370 --inline-commands
372 Inline commands of the form ^<cmd>^.
373 Enable inline commands of the form ^<cmd>^. The inline commands
375 are expected to be in a line by themselves. The available com‐
376 mands are: resume, rekey1 (local rekey), rekey (rekey on both
377 peers) and renegotiate.
378 --inline-commands-prefix=str
380 Change the default delimiter for inline commands.
381 Change the default delimiter (^) used for inline commands. The
383 delimiter is expected to be a single US-ASCII character (octets
384 0 - 127). This option is only relevant if inline commands are
385 enabled via the inline-commands option
386 --provider=file
388 Specify the PKCS #11 provider library.
389 This will override the default options in
391 /etc/gnutls/pkcs11.conf
392 --fips140-mode
394 Reports the status of the FIPS140-2 mode in gnutls library.
395 --list-config
398 Reports the configuration of the library.
399 --logfile=str
402 Redirect informational messages to a specific file.
403 Redirect informational messages to a specific file. The file may
405 be /dev/null also to make the gnutls client quiet to use it in
406 piped server connections where only the server communication may
407 appear on stdout.
408 --keymatexport=str
410 Label used for exporting keying material.
411 --keymatexportsize=num
414 Size of the exported keying material. This option takes an in‐
415 teger number as its argument.
416 --waitresumption
419 Block waiting for the resumption data under TLS1.3.
420 This option makes the client to block waiting for the resumption
422 data under TLS1.3. The option has effect only when --resume is
423 provided.
424 --ca-auto-retrieve, --no-ca-auto-retrieve
426 Enable automatic retrieval of missing CA certificates. The
427 no-ca-auto-retrieve form will disable the option.
428 This option enables the client to automatically retrieve the
430 missing intermediate CA certificates in the certificate chain,
431 based on the Authority Information Access (AIA) extension.
432 -v arg, --version=arg
434 Output version of program and exit. The default mode is `v', a
435 simple version. The `c' mode will print copyright information
436 and `n' will print the full copyright notice.
437 -h, --help
439 Display usage information and exit.
440 -!, --more-help
442 Pass the extended usage information through a pager.
443
447 Connecting using PSK authentication
448 To connect to a server using PSK authentication, you need to enable the
449 choice of PSK by using a cipher priority parameter such as in the exam‐
450 ple below.
451 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
452 Resolving 'localhost'...
453 Connecting to '127.0.0.1:5556'...
454 - PSK authentication.
455 - Version: TLS1.1
456 - Key Exchange: PSK
457 - Cipher: AES-128-CBC
458 - MAC: SHA1
459 - Compression: NULL
460 - Handshake was completed
461 - Simple Client Mode:
463 By keeping the --pskusername parameter and removing the --pskkey param‐
464 eter, it will query only for the password during the handshake.
465 Connecting using raw public-key authentication
467 To connect to a server using raw public-key authentication, you need to
468 enable the option to negotiate raw public-keys via the priority strings
469 such as in the example below.
470 $ ./gnutls-cli -p 5556 localhost --priority NORMAL:-CTYPE-CLI-ALL:+CTYPE-CLI-RAWPK --rawpkkeyfile cli.key.pem --rawpkfile cli.rawpk.pem
471 Processed 1 client raw public key pair...
472 Resolving 'localhost'...
473 Connecting to '127.0.0.1:5556'...
474 - Successfully sent 1 certificate(s) to server.
475 - Server has requested a certificate.
476 - Certificate type: X.509
477 - Got a certificate list of 1 certificates.
478 - Certificate[0] info:
479 - skipped
480 - Description: (TLS1.3-Raw Public Key-X.509)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM)
481 - Options:
482 - Handshake was completed
483 - Simple Client Mode:
485 Connecting to STARTTLS services
487 You could also use the client to connect to services with starttls ca‐
489 pability.
490 $ gnutls-cli --starttls-proto smtp --port 25 localhost
491 Listing ciphersuites in a priority string
493 To list the ciphersuites in a priority string:
494 $ ./gnutls-cli --priority SECURE192 -l
495 Cipher suites for SECURE192
496 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
497 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
498 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
499 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
500 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
501 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
502 Certificate types: CTYPE-X.509
504 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
505 Compression: COMP-NULL
506 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
507 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
508 Connecting using a PKCS #11 token
510 To connect to a server using a certificate and a private key present in
511 a PKCS #11 token you need to substitute the PKCS 11 URLs in the
512 x509certfile and x509keyfile parameters.
513 Those can be found using "p11tool --list-tokens" and then listing all
515 the objects in the needed token, and using the appropriate.
516 $ p11tool --list-tokens
517 Token 0:
519 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
520 Label: Test
521 Manufacturer: EnterSafe
522 Model: PKCS15
523 Serial: 1234
524 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
526 Object 0:
528 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
529 Type: X.509 Certificate
530 Label: client
531 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
532 $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
534 $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
535 $ export MYCERT MYKEY
536 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
538 Notice that the private key only differs from the certificate in the
539 type.
540
542 One of the following exit values will be returned:
543 0 (EXIT_SUCCESS)
545 Successful program execution.
546 1 (EXIT_FAILURE)
548 The operation failed or the command syntax was not valid.
549
551 gnutls-cli-debug(1), gnutls-serv(1)
552
555 Copyright (C) 2020-2021 Free Software Foundation, and others all rights
556 reserved. This program is released under the terms of the GNU General
557 Public License, version 3 or later
558
560 Please send bug reports to: bugs@gnutls.org
5613.7.6 27 May 2022 gnutls-cli(1)