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
14

DESCRIPTION

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

OPTIONS

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.  This
162              option must not appear in combination with any of the following
163              options: save-ocsp-multi.
164
165
166       --save-ocsp-multi=string
167              Save all OCSP responses provided by the peer in this file.  This
168              option must not appear in combination with any of the following
169              options: save-ocsp.
170
171              The file will contain a list of PEM encoded OCSP status
172              responses if any were provided by the peer, starting with the
173              one for the peer's server certificate.
174
175       --save-server-trace=string
176              Save the server-side TLS message trace in the provided file.
177
178
179       --save-client-trace=string
180              Save the client-side TLS message trace in the provided file.
181
182
183       --dh-bits=number
184              The minimum number of bits allowed for DH.  This option takes an
185              integer number as its argument.
186
187              This option sets the minimum number of bits allowed for a
188              Diffie-Hellman key exchange. You may want to lower the default
189              value if the peer sends a weak prime and you get an connection
190              error with unacceptable prime.
191
192       --priority=string
193              Priorities string.
194
195              TLS algorithms and protocols to enable. You can use predefined
196              sets of ciphersuites such as PERFORMANCE, NORMAL, PFS,
197              SECURE128, SECURE256. The default is NORMAL.
198
199              Check  the  GnuTLS  manual  on  section  “Priority strings” for
200              more information on the allowed keywords
201
202       --x509cafile=string
203              Certificate file or PKCS #11 URL to use.
204
205
206       --x509crlfile=file
207              CRL file to use.
208
209
210       --x509keyfile=string
211              X.509 key file or PKCS #11 URL to use.
212
213
214       --x509certfile=string
215              X.509 Certificate file or PKCS #11 URL to use.  This option must
216              appear in combination with the following options: x509keyfile.
217
218
219       --rawpkkeyfile=string
220              Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
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       --rawpkfile=string
230              Raw public-key file to use.  This option must appear in combina‐
231              tion with the following options: rawpkkeyfile.
232
233              In order to instruct the application to negotiate raw public
234              keys one must enable the respective certificate types via the
235              priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
236
237              Check  the  GnuTLS  manual  on  section  “Priority strings” for
238              more information on how to set certificate types.
239
240       --srpusername=string
241              SRP username to use.
242
243
244       --srppasswd=string
245              SRP password to use.
246
247
248       --pskusername=string
249              PSK username to use.
250
251
252       --pskkey=string
253              PSK key (in hex) to use.
254
255
256       -p string, --port=string
257              The port or service to connect to.
258
259
260       --insecure
261              Don't abort program if server certificate can't be validated.
262
263
264       --verify-allow-broken
265              Allow broken algorithms, such as MD5 for certificate verifica‐
266              tion.
267
268
269       --ranges
270              Use length-hiding padding to prevent traffic analysis.
271
272              When possible (e.g., when using CBC ciphersuites), use length-
273              hiding padding to prevent traffic analysis.
274
275              NOTE: THIS OPTION IS DEPRECATED
276
277       --benchmark-ciphers
278              Benchmark individual ciphers.
279
280              By default the benchmarked ciphers will utilize any capabilities
281              of the local CPU to improve performance. To test against the raw
282              software implementation set the environment variable
283              GNUTLS_CPUID_OVERRIDE to 0x1.
284
285       --benchmark-tls-kx
286              Benchmark TLS key exchange methods.
287
288
289       --benchmark-tls-ciphers
290              Benchmark TLS ciphers.
291
292              By default the benchmarked ciphers will utilize any capabilities
293              of the local CPU to improve performance. To test against the raw
294              software implementation set the environment variable
295              GNUTLS_CPUID_OVERRIDE to 0x1.
296
297       -l, --list
298              Print a list of the supported algorithms and modes.  This option
299              must not appear in combination with any of the following
300              options: port.
301
302              Print a list of the supported algorithms and modes. If a prior‐
303              ity string is given then only the enabled ciphersuites are
304              shown.
305
306       --priority-list
307              Print a list of the supported priority strings.
308
309              Print a list of the supported priority strings. The ciphersuites
310              corresponding to each priority string can be examined using -l
311              -p.
312
313       --noticket
314              Don't allow session tickets.
315
316              Disable the request of receiving of session tickets under TLS1.2
317              or earlier
318
319       --srtp-profiles=string
320              Offer SRTP profiles.
321
322
323       --alpn=string
324              Application layer protocol.  This option may appear an unlimited
325              number of times.
326
327              This option will set and enable the Application Layer Protocol
328              Negotiation  (ALPN) in the TLS protocol.
329
330       -b, --heartbeat
331              Activate heartbeat support.
332
333
334       --recordsize=number
335              The maximum record size to advertize.  This option takes an
336              integer number as its argument.  The value of number is con‐
337              strained to being:
338                  in the range  0 through 4096
339
340
341       --disable-sni
342              Do not send a Server Name Indication (SNI).
343
344
345       --disable-extensions
346              Disable all the TLS extensions.
347
348              This option disables all TLS extensions. Deprecated option. Use
349              the priority string.
350
351              NOTE: THIS OPTION IS DEPRECATED
352
353       --single-key-share
354              Send a single key share under TLS1.3.
355
356              This option switches the default mode of sending multiple key
357              shares, to send a single one (the top one).
358
359       --post-handshake-auth
360              Enable post-handshake authentication under TLS1.3.
361
362              This option enables post-handshake authentication when under
363              TLS1.3.
364
365       --inline-commands
366              Inline commands of the form ^<cmd>^.
367
368              Enable inline commands of the form ^<cmd>^. The inline commands
369              are expected to be in a line by themselves. The available com‐
370              mands are: resume, rekey1 (local rekey), rekey (rekey on both
371              peers) and renegotiate.
372
373       --inline-commands-prefix=string
374              Change the default delimiter for inline commands..
375
376              Change the default delimiter (^) used for inline commands. The
377              delimiter is expected to be a single US-ASCII character (octets
378              0 - 127). This option is only relevant if inline commands are
379              enabled via the inline-commands option
380
381       --provider=file
382              Specify the PKCS #11 provider library.
383
384              This will override the default options in
385              /etc/gnutls/pkcs11.conf
386
387       --fips140-mode
388              Reports the status of the FIPS140-2 mode in gnutls library.
389
390
391       --logfile=string
392              Redirect informational messages to a specific file..
393
394              Redirect informational messages to a specific file. The file may
395              be /dev/null also to make the gnutls client quiet to use it in
396              piped server connections where only the server communication may
397              appear on stdout.
398
399       --keymatexport=string
400              Label used for exporting keying material.
401
402
403       --keymatexportsize=number
404              Size of the exported keying material.  This option takes an
405              integer number as its argument.
406
407
408       -h, --help
409              Display usage information and exit.
410
411       -!, --more-help
412              Pass the extended usage information through a pager.
413
414       -v [{v|c|n --version [{v|c|n}]}]
415              Output version of program and exit.  The default mode is `v', a
416              simple version.  The `c' mode will print copyright information
417              and `n' will print the full copyright notice.
418

EXAMPLES

420       Connecting using PSK authentication
421       To connect to a server using PSK authentication, you need to enable the
422       choice of PSK by using a cipher priority parameter such as in the exam‐
423       ple below.
424           $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity     --pskkey 88f3824b3e5659f52d00e959bacab954b6540344     --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
425           Resolving 'localhost'...
426           Connecting to '127.0.0.1:5556'...
427           - PSK authentication.
428           - Version: TLS1.1
429           - Key Exchange: PSK
430           - Cipher: AES-128-CBC
431           - MAC: SHA1
432           - Compression: NULL
433           - Handshake was completed
434           - Simple Client Mode:
435       By keeping the --pskusername parameter and removing the --pskkey param‐
436       eter, it will query only for the password during the handshake.
437
438       Connecting using raw public-key authentication
439       To connect to a server using raw public-key authentication, you need to
440       enable the option to negotiate raw public-keys via the priority strings
441       such as in the example below.
442           $ ./gnutls-cli -p 5556 localhost --priority NORMAL:-CTYPE-CLI-ALL:+CTYPE-CLI-RAWPK     --rawpkkeyfile cli.key.pem     --rawpkfile cli.rawpk.pem
443           Processed 1 client raw public key pair...
444           Resolving 'localhost'...
445           Connecting to '127.0.0.1:5556'...
446           - Successfully sent 1 certificate(s) to server.
447           - Server has requested a certificate.
448           - Certificate type: X.509
449           - Got a certificate list of 1 certificates.
450           - Certificate[0] info:
451            - skipped
452           - Description: (TLS1.3-Raw Public Key-X.509)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM)
453           - Options:
454           - Handshake was completed
455           - Simple Client Mode:
456
457       Connecting to STARTTLS services
458
459       You could also use the client to connect to services with starttls
460       capability.
461           $ gnutls-cli --starttls-proto smtp --port 25 localhost
462
463       Listing ciphersuites in a priority string
464       To list the ciphersuites in a priority string:
465           $ ./gnutls-cli --priority SECURE192 -l
466           Cipher suites for SECURE192
467           TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24  TLS1.2
468           TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e  TLS1.2
469           TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30  TLS1.2
470           TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b  TLS1.2
471           TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a  TLS1.2
472           TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d  TLS1.2
473
474           Certificate types: CTYPE-X.509
475           Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
476           Compression: COMP-NULL
477           Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
478           PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
479
480       Connecting using a PKCS #11 token
481       To connect to a server using a certificate and a private key present in
482       a PKCS #11 token you need to substitute the PKCS 11 URLs in the
483       x509certfile and x509keyfile parameters.
484
485       Those can be found using "p11tool --list-tokens" and then listing all
486       the objects in the needed token, and using the appropriate.
487           $ p11tool --list-tokens
488
489           Token 0:
490           URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
491           Label: Test
492           Manufacturer: EnterSafe
493           Model: PKCS15
494           Serial: 1234
495
496           $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
497
498           Object 0:
499           URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert
500           Type: X.509 Certificate
501           Label: client
502           ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
503
504           $ MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=cert"
505           $ MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;type=private"
506           $ export MYCERT MYKEY
507
508           $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile $MYCERT
509       Notice that the private key only differs from the certificate in the
510       type.
511

EXIT STATUS

513       One of the following exit values will be returned:
514
515       0  (EXIT_SUCCESS)
516              Successful program execution.
517
518       1  (EXIT_FAILURE)
519              The operation failed or the command syntax was not valid.
520
521       70  (EX_SOFTWARE)
522              libopts had an internal operational error.  Please report it to
523              autogen-users@lists.sourceforge.net.  Thank you.
524

SEE ALSO

526       gnutls-cli-debug(1), gnutls-serv(1)
527

AUTHORS

529       Nikos Mavrogiannopoulos, Simon Josefsson and others; see
530       /usr/share/doc/gnutls/AUTHORS for a complete list.
531
533       Copyright (C) 2000-2020 Free Software Foundation, and others all rights
534       reserved.  This program is released under the terms of the GNU General
535       Public License, version 3 or later.
536

BUGS

538       Please send bug reports to: bugs@gnutls.org
539

NOTES

541       This manual page was AutoGen-erated from the gnutls-cli option defini‐
542       tions.
543
544
545
5463.6.12                            28 Mar 2020                    gnutls-cli(1)
Impressum