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 --srpusername=string
209 SRP username to use.
210
211
212 --srppasswd=string
213 SRP password to use.
214
215
216 --pskusername=string
217 PSK username to use.
218
219
220 --pskkey=string
221 PSK key (in hex) to use.
222
223
224 -p string, --port=string
225 The port or service to connect to.
226
227
228 --insecure
229 Don't abort program if server certificate can't be validated.
230
231
232 --verify-allow-broken
233 Allow broken algorithms, such as MD5 for certificate verifica‐
234 tion.
235
236
237 --ranges
238 Use length-hiding padding to prevent traffic analysis.
239
240 When possible (e.g., when using CBC ciphersuites), use length-
241 hiding padding to prevent traffic analysis.
242
243 NOTE: THIS OPTION IS DEPRECATED
244
245 --benchmark-ciphers
246 Benchmark individual ciphers.
247
248 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
253 --benchmark-tls-kx
254 Benchmark TLS key exchange methods.
255
256
257 --benchmark-tls-ciphers
258 Benchmark TLS ciphers.
259
260 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
265 -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
270 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
274 --priority-list
275 Print a list of the supported priority strings.
276
277 Print a list of the supported priority strings. The ciphersuites
278 corresponding to each priority string can be examined using -l
279 -p.
280
281 --noticket
282 Don't allow session tickets.
283
284 Disable the request of receiving of session tickets under TLS1.2
285 or earlier
286
287 --srtp-profiles=string
288 Offer SRTP profiles.
289
290
291 --alpn=string
292 Application layer protocol. This option may appear an unlimited
293 number of times.
294
295 This option will set and enable the Application Layer Protocol
296 Negotiation (ALPN) in the TLS protocol.
297
298 -b, --heartbeat
299 Activate heartbeat support.
300
301
302 --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
308
309 --disable-sni
310 Do not send a Server Name Indication (SNI).
311
312
313 --disable-extensions
314 Disable all the TLS extensions.
315
316 This option disables all TLS extensions. Deprecated option. Use
317 the priority string.
318
319 NOTE: THIS OPTION IS DEPRECATED
320
321 --single-key-share
322 Send a single key share under TLS1.3.
323
324 This option switches the default mode of sending multiple key
325 shares, to send a single one (the top one).
326
327 --post-handshake-auth
328 Enable post-handshake authentication under TLS1.3.
329
330 This option enables post-handshake authentication when under
331 TLS1.3.
332
333 --inline-commands
334 Inline commands of the form ^<cmd>^.
335
336 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
341 --inline-commands-prefix=string
342 Change the default delimiter for inline commands..
343
344 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
349 --provider=file
350 Specify the PKCS #11 provider library.
351
352 This will override the default options in
353 /etc/gnutls/pkcs11.conf
354
355 --fips140-mode
356 Reports the status of the FIPS140-2 mode in gnutls library.
357
358
359 -h, --help
360 Display usage information and exit.
361
362 -!, --more-help
363 Pass the extended usage information through a pager.
364
365 -v [{v|c|n --version [{v|c|n}]}]
366 Output version of program and exit. The default mode is `v', a
367 simple version. The `c' mode will print copyright information
368 and `n' will print the full copyright notice.
369
371 Connecting using PSK authentication
372 To connect to a server using PSK authentication, you need to enable the
373 choice of PSK by using a cipher priority parameter such as in the exam‐
374 ple below.
375 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
376 Resolving 'localhost'...
377 Connecting to '127.0.0.1:5556'...
378 - PSK authentication.
379 - Version: TLS1.1
380 - Key Exchange: PSK
381 - Cipher: AES-128-CBC
382 - MAC: SHA1
383 - Compression: NULL
384 - Handshake was completed
385 - Simple Client Mode:
386 By keeping the --pskusername parameter and removing the --pskkey param‐
387 eter, it will query only for the password during the handshake.
388
389 Connecting to STARTTLS services
390
391 You could also use the client to connect to services with starttls
392 capability.
393 $ gnutls-cli --starttls-proto smtp --port 25 localhost
394
395 Listing ciphersuites in a priority string
396 To list the ciphersuites in a priority string:
397 $ ./gnutls-cli --priority SECURE192 -l
398 Cipher suites for SECURE192
399 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
400 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
401 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
402 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
403 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
404 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
405
406 Certificate types: CTYPE-X.509
407 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
408 Compression: COMP-NULL
409 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
410 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
411
412 Connecting using a PKCS #11 token
413 To connect to a server using a certificate and a private key present in
414 a PKCS #11 token you need to substitute the PKCS 11 URLs in the
415 x509certfile and x509keyfile parameters.
416
417 Those can be found using "p11tool --list-tokens" and then listing all
418 the objects in the needed token, and using the appropriate.
419 $ p11tool --list-tokens
420
421 Token 0:
422 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
423 Label: Test
424 Manufacturer: EnterSafe
425 Model: PKCS15
426 Serial: 1234
427
428 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
429
430 Object 0:
431 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
432 Type: X.509 Certificate
433 Label: client
434 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
435
436 $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
437 $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
438 $ export MYCERT MYKEY
439
440 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
441 Notice that the private key only differs from the certificate in the
442 type.
443
445 One of the following exit values will be returned:
446
447 0 (EXIT_SUCCESS)
448 Successful program execution.
449
450 1 (EXIT_FAILURE)
451 The operation failed or the command syntax was not valid.
452
453 70 (EX_SOFTWARE)
454 libopts had an internal operational error. Please report it to
455 autogen-users@lists.sourceforge.net. Thank you.
456
458 gnutls-cli-debug(1), gnutls-serv(1)
459
461 Nikos Mavrogiannopoulos, Simon Josefsson and others; see
462 /usr/share/doc/gnutls/AUTHORS for a complete list.
463
465 Copyright (C) 2000-2018 Free Software Foundation, and others all rights
466 reserved. This program is released under the terms of the GNU General
467 Public License, version 3 or later.
468
470 Please send bug reports to: bugs@gnutls.org
471
473 This manual page was AutoGen-erated from the gnutls-cli option defini‐
474 tions.
475
476
477
4783.6.4 30 Nov 2018 gnutls-cli(1)