1gnutls-cli(1) User Commands gnutls-cli(1)
2
3
4
6 gnutls-cli - GnuTLS client
7
9 gnutls-cli [-flags] [-flag [value]] [--option-name[[=| ]value]] [host‐
10 name]
11
12 Operands and options may be intermixed. They will be reordered.
13
14
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
26 Specifies the debug level.
27
28 -V, --verbose
29 More verbose output. This option may appear an unlimited number
30 of times.
31
32
33 --tofu, --no-tofu
34 Enable trust on first use authentication. The no-tofu form will
35 disable the option.
36
37 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
43 --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
48 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
52 --dane, --no-dane
53 Enable DANE certificate verification (DNSSEC). The no-dane form
54 will disable the option.
55
56 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
60 --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
64 This option will use the local DNS server for DNSSEC. This is
65 disabled by default due to many servers not allowing DNSSEC.
66
67 --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
71 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
74 --ocsp, --no-ocsp
75 Enable OCSP certificate verification. The no-ocsp form will
76 disable the option.
77
78 This option will enable verification of the peer's certificate
79 using ocsp
80
81 -r, --resume
82 Establish a session and resume.
83
84 Connect, establish a session, reconnect and resume.
85
86 --earlydata=string
87 Send early data on resumption from the specified file.
88
89
90 -e, --rehandshake
91 Establish a session and rehandshake.
92
93 Connect, establish a session and rehandshake immediately.
94
95 --sni-hostname=string
96 Server's hostname for server name indication extension.
97
98 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
105 --verify-hostname=string
106 Server's hostname to use for validation.
107
108 Set explicitly the server name to be used when validating the
109 server's certificate.
110
111 -s, --starttls
112 Connect, establish a plain session and start TLS.
113
114 The TLS session will be initiated when EOF or a SIGALRM is
115 received.
116
117 --app-proto
118 This is an alias for the --starttls-proto option.
119
120 --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
126 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
130 -u, --udp
131 Use DTLS (datagram TLS) over UDP.
132
133
134 --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
139
140 --crlf Send CR LF instead of LF.
141
142
143 --fastopen
144 Enable TCP Fast Open.
145
146
147 --x509fmtder
148 Use DER format for certificates to read from.
149
150
151 --print-cert
152 Print peer's certificate in PEM format.
153
154
155 --save-cert=string
156 Save the peer's certificate chain in the specified file in PEM
157 format.
158
159
160 --save-ocsp=string
161 Save the peer's OCSP status response in the provided file.
162
163
164 --save-server-trace=string
165 Save the server-side TLS message trace in the provided file.
166
167
168 --save-client-trace=string
169 Save the client-side TLS message trace in the provided file.
170
171
172 --dh-bits=number
173 The minimum number of bits allowed for DH. This option takes an
174 integer number as its argument.
175
176 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
181 --priority=string
182 Priorities string.
183
184 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
188 Check the GnuTLS manual on section “Priority strings” for
189 more information on the allowed keywords
190
191 --x509cafile=string
192 Certificate file or PKCS #11 URL to use.
193
194
195 --x509crlfile=file
196 CRL file to use.
197
198
199 --x509keyfile=string
200 X.509 key file or PKCS #11 URL to use.
201
202
203 --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
207
208 --rawpkkeyfile=string
209 Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
210
211 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
215 Check the GnuTLS manual on section “Priority strings” for
216 more information on how to set certificate types.
217
218 --rawpkfile=string
219 Raw public-key file to use. This option must appear in combina‐
220 tion with the following options: rawpkkeyfile.
221
222 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
226 Check the GnuTLS manual on section “Priority strings” for
227 more information on how to set certificate types.
228
229 --srpusername=string
230 SRP username to use.
231
232
233 --srppasswd=string
234 SRP password to use.
235
236
237 --pskusername=string
238 PSK username to use.
239
240
241 --pskkey=string
242 PSK key (in hex) to use.
243
244
245 -p string, --port=string
246 The port or service to connect to.
247
248
249 --insecure
250 Don't abort program if server certificate can't be validated.
251
252
253 --verify-allow-broken
254 Allow broken algorithms, such as MD5 for certificate verifica‐
255 tion.
256
257
258 --ranges
259 Use length-hiding padding to prevent traffic analysis.
260
261 When possible (e.g., when using CBC ciphersuites), use length-
262 hiding padding to prevent traffic analysis.
263
264 NOTE: THIS OPTION IS DEPRECATED
265
266 --benchmark-ciphers
267 Benchmark individual ciphers.
268
269 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
274 --benchmark-tls-kx
275 Benchmark TLS key exchange methods.
276
277
278 --benchmark-tls-ciphers
279 Benchmark TLS ciphers.
280
281 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
286 -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
291 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
295 --priority-list
296 Print a list of the supported priority strings.
297
298 Print a list of the supported priority strings. The ciphersuites
299 corresponding to each priority string can be examined using -l
300 -p.
301
302 --noticket
303 Don't allow session tickets.
304
305 Disable the request of receiving of session tickets under TLS1.2
306 or earlier
307
308 --srtp-profiles=string
309 Offer SRTP profiles.
310
311
312 --alpn=string
313 Application layer protocol. This option may appear an unlimited
314 number of times.
315
316 This option will set and enable the Application Layer Protocol
317 Negotiation (ALPN) in the TLS protocol.
318
319 -b, --heartbeat
320 Activate heartbeat support.
321
322
323 --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
329
330 --disable-sni
331 Do not send a Server Name Indication (SNI).
332
333
334 --disable-extensions
335 Disable all the TLS extensions.
336
337 This option disables all TLS extensions. Deprecated option. Use
338 the priority string.
339
340 NOTE: THIS OPTION IS DEPRECATED
341
342 --single-key-share
343 Send a single key share under TLS1.3.
344
345 This option switches the default mode of sending multiple key
346 shares, to send a single one (the top one).
347
348 --post-handshake-auth
349 Enable post-handshake authentication under TLS1.3.
350
351 This option enables post-handshake authentication when under
352 TLS1.3.
353
354 --inline-commands
355 Inline commands of the form ^<cmd>^.
356
357 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
362 --inline-commands-prefix=string
363 Change the default delimiter for inline commands..
364
365 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
370 --provider=file
371 Specify the PKCS #11 provider library.
372
373 This will override the default options in
374 /etc/gnutls/pkcs11.conf
375
376 --fips140-mode
377 Reports the status of the FIPS140-2 mode in gnutls library.
378
379
380 --logfile=string
381 Redirect informational messages to a specific file..
382
383 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
388 --keymatexport=string
389 Label used for exporting keying material.
390
391
392 --keymatexportsize=number
393 Size of the exported keying material. This option takes an
394 integer number as its argument.
395
396
397 -h, --help
398 Display usage information and exit.
399
400 -!, --more-help
401 Pass the extended usage information through a pager.
402
403 -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
427 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
446 Connecting to STARTTLS services
447
448 You could also use the client to connect to services with starttls
449 capability.
450 $ gnutls-cli --starttls-proto smtp --port 25 localhost
451
452 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
463 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
469 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
474 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
478 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
485 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
486
487 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
493 $ 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
497 $ 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
504 0 (EXIT_SUCCESS)
505 Successful program execution.
506
507 1 (EXIT_FAILURE)
508 The operation failed or the command syntax was not valid.
509
510 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.
532
533
534
5353.6.11 01 Dec 2019 gnutls-cli(1)