1gnutls-cli(1)                    User Commands                   gnutls-cli(1)
2
3
4

NAME

6       gnutls-cli - GnuTLS client
7

SYNOPSIS

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

DESCRIPTION

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
19

OPTIONS

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
26              Specifies the debug level.
27
28       -V, --verbose
29              More verbose output.
30
31
32       --tofu, --no-tofu
33              Enable trust on first use authentication.  The no-tofu form will
34              disable the option.
35
36              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
42       --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
47              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
51       --dane, --no-dane
52              Enable DANE certificate verification (DNSSEC).  The no-dane form
53              will disable the option.
54
55              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
59       --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
63              This option will use the local DNS server for DNSSEC.  This is
64              disabled by default due to many servers not allowing DNSSEC.
65
66       --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
70              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
73       --ocsp, --no-ocsp
74              Enable OCSP certificate verification.  The no-ocsp form will
75              disable the option.
76
77              This option will enable verification of the peer's certificate
78              using ocsp
79
80       -r, --resume
81              Establish a session and resume.
82
83              Connect, establish a session, reconnect and resume.
84
85       --earlydata=str
86              Send early data on resumption from the specified file.
87
88
89       -e, --rehandshake
90              Establish a session and rehandshake.
91
92              Connect, establish a session and rehandshake immediately.
93
94       --sni-hostname=str
95              Server's hostname for server name indication extension.
96
97              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
104       --verify-hostname=str
105              Server's hostname to use for validation.
106
107              Set explicitly the server name to be used when validating the
108              server's certificate.
109
110       -s, --starttls
111              Connect, establish a plain session and start TLS.
112
113              The TLS session will be initiated when EOF or a SIGALRM is re‐
114              ceived.
115
116       --app-proto
117              This is an alias for the --starttls-proto option.
118
119       --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
125              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
129       -u, --udp
130              Use DTLS (datagram TLS) over UDP.
131
132
133       --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
138
139       --crlf Send CR LF instead of LF.
140
141
142       --fastopen
143              Enable TCP Fast Open.
144
145
146       --x509fmtder
147              Use DER format for certificates to read from.
148
149
150       --print-cert
151              Print peer's certificate in PEM format.
152
153
154       --save-cert=str
155              Save the peer's certificate chain in the specified file in PEM
156              format.
157
158
159       --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
164
165       --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
170              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
174       --save-server-trace=str
175              Save the server-side TLS message trace in the provided file.
176
177
178       --save-client-trace=str
179              Save the client-side TLS message trace in the provided file.
180
181
182       --dh-bits=num
183              The minimum number of bits allowed for DH.  This option takes an
184              integer number as its argument.
185
186              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
191       --priority=str
192              Priorities string.
193
194              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
198              Check  the  GnuTLS  manual  on  section  “Priority strings” for
199              more information on the allowed keywords
200
201       --x509cafile=str
202              Certificate file or PKCS #11 URL to use.
203
204
205       --x509crlfile=file
206              CRL file to use.
207
208
209       --x509keyfile=str
210              X.509 key file or PKCS #11 URL to use.
211
212
213       --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
217
218       --rawpkkeyfile=str
219              Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
220
221              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
225              Check  the  GnuTLS  manual  on  section  “Priority strings” for
226              more information on how to set certificate types.
227
228       --rawpkfile=str
229              Raw public-key file to use.  This option must appear in combina‐
230              tion with the following options: rawpkkeyfile.
231
232              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
236              Check  the  GnuTLS  manual  on  section  “Priority strings” for
237              more information on how to set certificate types.
238
239       --srpusername=str
240              SRP username to use.
241
242
243       --srppasswd=str
244              SRP password to use.
245
246
247       --pskusername=str
248              PSK username to use.
249
250
251       --pskkey=str
252              PSK key (in hex) to use.
253
254
255       -p str, --port=str
256              The port or service to connect to.
257
258
259       --insecure
260              Don't abort program if server certificate can't be validated.
261
262
263       --verify-allow-broken
264              Allow broken algorithms, such as MD5 for certificate verifica‐
265              tion.
266
267
268       --ranges
269              Use length-hiding padding to prevent traffic analysis.
270
271              When possible (e.g., when using CBC ciphersuites), use
272              length-hiding padding to prevent traffic analysis.
273
274              NOTE: THIS OPTION IS DEPRECATED
275
276       --benchmark-ciphers
277              Benchmark individual ciphers.
278
279              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
284       --benchmark-tls-kx
285              Benchmark TLS key exchange methods.
286
287
288       --benchmark-tls-ciphers
289              Benchmark TLS ciphers.
290
291              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
296       -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
301              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
305       --priority-list
306              Print a list of the supported priority strings.
307
308              Print a list of the supported priority strings. The ciphersuites
309              corresponding to each priority string can be examined using -l
310              -p.
311
312       --noticket
313              Don't allow session tickets.
314
315              Disable the request of receiving of session tickets under TLS1.2
316              or earlier
317
318       --srtp-profiles=str
319              Offer SRTP profiles.
320
321
322       --alpn=str
323              Application layer protocol.  This option may appear an unlimited
324              number of times.
325
326              This option will set and enable the Application Layer Protocol
327              Negotiation  (ALPN) in the TLS protocol.
328
329       --compress-cert=str
330              Compress certificate.  This option may appear an unlimited num‐
331              ber of times.
332
333              This option sets a supported compression method for certificate
334              compression.
335
336       -b, --heartbeat
337              Activate heartbeat support.
338
339
340       --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
346
347       --disable-sni
348              Do not send a Server Name Indication (SNI).
349
350
351       --disable-extensions
352              Disable all the TLS extensions.
353
354              This option disables all TLS extensions. Deprecated option. Use
355              the priority string.
356
357              NOTE: THIS OPTION IS DEPRECATED
358
359       --single-key-share
360              Send a single key share under TLS1.3.
361
362              This option switches the default mode of sending multiple key
363              shares, to send a single one (the top one).
364
365       --post-handshake-auth
366              Enable post-handshake authentication under TLS1.3.
367
368              This option enables post-handshake authentication when under
369              TLS1.3.
370
371       --inline-commands
372              Inline commands of the form ^<cmd>^.
373
374              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
379       --inline-commands-prefix=str
380              Change the default delimiter for inline commands.
381
382              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
387       --provider=file
388              Specify the PKCS #11 provider library.
389
390              This will override the default options in
391              /etc/gnutls/pkcs11.conf
392
393       --fips140-mode
394              Reports the status of the FIPS140-2 mode in gnutls library.
395
396
397       --list-config
398              Reports the configuration of the library.
399
400
401       --logfile=str
402              Redirect informational messages to a specific file.
403
404              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
409       --keymatexport=str
410              Label used for exporting keying material.
411
412
413       --keymatexportsize=num
414              Size of the exported keying material.  This option takes an in‐
415              teger number as its argument.
416
417
418       --waitresumption
419              Block waiting for the resumption data under TLS1.3.
420
421              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
425       --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
429              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
433       -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
438       -h, --help
439              Display usage information and exit.
440
441       -!, --more-help
442              Pass the extended usage information through a pager.
443
444
445

EXAMPLES

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
462           - 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
466       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
484           - Simple Client Mode:
485
486       Connecting to STARTTLS services
487
488       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
492       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
503           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
509       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
514       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
518           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
525           $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
526
527           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
533           $ 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
537           $ 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

EXIT STATUS

542       One of the following exit values will be returned:
543
544       0  (EXIT_SUCCESS)
545              Successful program execution.
546
547       1  (EXIT_FAILURE)
548              The operation failed or the command syntax was not valid.
549

SEE ALSO

551       gnutls-cli-debug(1), gnutls-serv(1)
552

AUTHORS

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

BUGS

560       Please send bug reports to: bugs@gnutls.org
561
562
563
5643.7.6                             27 May 2022                    gnutls-cli(1)
Impressum