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 --srpusername=string
209 SRP username to use.
210 --srppasswd=string
213 SRP password to use.
214 --pskusername=string
217 PSK username to use.
218 --pskkey=string
221 PSK key (in hex) to use.
222 -p string, --port=string
225 The port or service to connect to.
226 --insecure
229 Don't abort program if server certificate can't be validated.
230 --verify-allow-broken
233 Allow broken algorithms, such as MD5 for certificate verifica‐
234 tion.
235 --ranges
238 Use length-hiding padding to prevent traffic analysis.
239 When possible (e.g., when using CBC ciphersuites), use length-
241 hiding padding to prevent traffic analysis.
242 NOTE: THIS OPTION IS DEPRECATED
244 --benchmark-ciphers
246 Benchmark individual ciphers.
247 By default the benchmarked ciphers will utilize any capabilities
249 of the local CPU to improve performance. To test against the raw
250 software implementation set the environment variable
251 GNUTLS_CPUID_OVERRIDE to 0x1.
252 --benchmark-tls-kx
254 Benchmark TLS key exchange methods.
255 --benchmark-tls-ciphers
258 Benchmark TLS ciphers.
259 By default the benchmarked ciphers will utilize any capabilities
261 of the local CPU to improve performance. To test against the raw
262 software implementation set the environment variable
263 GNUTLS_CPUID_OVERRIDE to 0x1.
264 -l, --list
266 Print a list of the supported algorithms and modes. This option
267 must not appear in combination with any of the following
268 options: port.
269 Print a list of the supported algorithms and modes. If a prior‐
271 ity string is given then only the enabled ciphersuites are
272 shown.
273 --priority-list
275 Print a list of the supported priority strings.
276 Print a list of the supported priority strings. The ciphersuites
278 corresponding to each priority string can be examined using -l
279 -p.
280 --noticket
282 Don't allow session tickets.
283 Disable the request of receiving of session tickets under TLS1.2
285 or earlier
286 --srtp-profiles=string
288 Offer SRTP profiles.
289 --alpn=string
292 Application layer protocol. This option may appear an unlimited
293 number of times.
294 This option will set and enable the Application Layer Protocol
296 Negotiation (ALPN) in the TLS protocol.
297 -b, --heartbeat
299 Activate heartbeat support.
300 --recordsize=number
303 The maximum record size to advertize. This option takes an
304 integer number as its argument. The value of number is con‐
305 strained to being:
306 in the range 0 through 4096
307 --disable-sni
310 Do not send a Server Name Indication (SNI).
311 --disable-extensions
314 Disable all the TLS extensions.
315 This option disables all TLS extensions. Deprecated option. Use
317 the priority string.
318 NOTE: THIS OPTION IS DEPRECATED
320 --single-key-share
322 Send a single key share under TLS1.3.
323 This option switches the default mode of sending multiple key
325 shares, to send a single one (the top one).
326 --post-handshake-auth
328 Enable post-handshake authentication under TLS1.3.
329 This option enables post-handshake authentication when under
331 TLS1.3.
332 --inline-commands
334 Inline commands of the form ^<cmd>^.
335 Enable inline commands of the form ^<cmd>^. The inline commands
337 are expected to be in a line by themselves. The available com‐
338 mands are: resume, rekey1 (local rekey), rekey (rekey on both
339 peers) and renegotiate.
340 --inline-commands-prefix=string
342 Change the default delimiter for inline commands..
343 Change the default delimiter (^) used for inline commands. The
345 delimiter is expected to be a single US-ASCII character (octets
346 0 - 127). This option is only relevant if inline commands are
347 enabled via the inline-commands option
348 --provider=file
350 Specify the PKCS #11 provider library.
351 This will override the default options in
353 /etc/gnutls/pkcs11.conf
354 --fips140-mode
356 Reports the status of the FIPS140-2 mode in gnutls library.
357 --logfile=string
360 Redirect informational messages to a specific file..
361 --keymatexport=string
364 Label used for exporting keying material.
365 --keymatexportsize=number
368 Size of the exported keying material. This option takes an
369 integer number as its argument.
370 -h, --help
373 Display usage information and exit.
374 -!, --more-help
376 Pass the extended usage information through a pager.
377 -v [{v|c|n --version [{v|c|n}]}]
379 Output version of program and exit. The default mode is `v', a
380 simple version. The `c' mode will print copyright information
381 and `n' will print the full copyright notice.
382
384 Connecting using PSK authentication
385 To connect to a server using PSK authentication, you need to enable the
386 choice of PSK by using a cipher priority parameter such as in the exam‐
387 ple below.
388 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
389 Resolving 'localhost'...
390 Connecting to '127.0.0.1:5556'...
391 - PSK authentication.
392 - Version: TLS1.1
393 - Key Exchange: PSK
394 - Cipher: AES-128-CBC
395 - MAC: SHA1
396 - Compression: NULL
397 - Handshake was completed
398 - Simple Client Mode:
399 By keeping the --pskusername parameter and removing the --pskkey param‐
400 eter, it will query only for the password during the handshake.
401 Connecting to STARTTLS services
403 You could also use the client to connect to services with starttls
405 capability.
406 $ gnutls-cli --starttls-proto smtp --port 25 localhost
407 Listing ciphersuites in a priority string
409 To list the ciphersuites in a priority string:
410 $ ./gnutls-cli --priority SECURE192 -l
411 Cipher suites for SECURE192
412 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
413 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
414 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
415 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
416 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
417 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
418 Certificate types: CTYPE-X.509
420 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
421 Compression: COMP-NULL
422 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
423 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
424 Connecting using a PKCS #11 token
426 To connect to a server using a certificate and a private key present in
427 a PKCS #11 token you need to substitute the PKCS 11 URLs in the
428 x509certfile and x509keyfile parameters.
429 Those can be found using "p11tool --list-tokens" and then listing all
431 the objects in the needed token, and using the appropriate.
432 $ p11tool --list-tokens
433 Token 0:
435 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
436 Label: Test
437 Manufacturer: EnterSafe
438 Model: PKCS15
439 Serial: 1234
440 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
442 Object 0:
444 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
445 Type: X.509 Certificate
446 Label: client
447 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
448 $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
450 $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
451 $ export MYCERT MYKEY
452 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
454 Notice that the private key only differs from the certificate in the
455 type.
456
458 One of the following exit values will be returned:
459 0 (EXIT_SUCCESS)
461 Successful program execution.
462 1 (EXIT_FAILURE)
464 The operation failed or the command syntax was not valid.
465 70 (EX_SOFTWARE)
467 libopts had an internal operational error. Please report it to
468 autogen-users@lists.sourceforge.net. Thank you.
469
471 gnutls-cli-debug(1), gnutls-serv(1)
472
474 Nikos Mavrogiannopoulos, Simon Josefsson and others; see
475 /usr/share/doc/gnutls/AUTHORS for a complete list.
476
478 Copyright (C) 2000-2019 Free Software Foundation, and others all rights
479 reserved. This program is released under the terms of the GNU General
480 Public License, version 3 or later.
481
483 Please send bug reports to: bugs@gnutls.org
484
486 This manual page was AutoGen-erated from the gnutls-cli option defini‐
487 tions.
4883.6.8 25 May 2019 gnutls-cli(1)