gnutls-cli: added --save-cert option
[gnutls:gnutls.git] / src / cli-args.def
1 AutoGen Definitions options;
2 prog-name     = gnutls-cli;
3 prog-title    = "GnuTLS client";
4 prog-desc     = "Simple client program to set up a TLS connection.";
5 short-usage   = "Usage: gnutls-cli [options] hostname\ngnutls-cli --help for usage instructions.\n";
6 explain       = "";
7 detail        = "Simple client program to set up a TLS connection to some other computer. 
8 It sets up a TLS connection and forwards data from the standard input to the secured socket and vice versa.";
9 reorder-args;
10 argument = "[hostname]";
11
12 #define  VERBOSE_OPT 1
13 #include args-std.def
14
15 flag = {
16     name      = tofu;
17     descrip   = "Enable trust on first use authentication";
18     disabled;
19     disable   = "no";
20     doc       = "This option will, in addition to certificate authentication, perform authentication
21 based on previously seen public keys, a model similar to SSH authentication. Note that when tofu 
22 is specified (PKI) and DANE authentication will become advisory to assist the public key acceptance
23 process.";
24 };
25
26 flag = {
27     name      = strict-tofu;
28     descrip   = "Fail to connect if a known certificate has changed";
29     disabled;
30     disable   = "no";
31     doc       = "This option will perform authentication as with option --tofu; however, while --tofu asks whether to trust a changed public key, this option will fail in case of public key changes.";
32 };
33
34 flag = {
35     name      = dane;
36     descrip   = "Enable DANE certificate verification (DNSSEC)";
37     disabled;
38     disable   = "no";
39     doc       = "This option will, in addition to certificate authentication using 
40 the trusted CAs, verify the server certificates using on the DANE information
41 available via DNSSEC.";
42 };
43
44 flag = {
45     name      = local-dns;
46     descrip   = "Use the local DNS server for DNSSEC resolving";
47     disabled;
48     disable   = "no";
49     doc       = "This option will use the local DNS server for DNSSEC.
50 This is disabled by default due to many servers not allowing DNSSEC.";
51 };
52
53 flag = {
54     name      = ca-verification;
55     descrip   = "Disable CA certificate verification";
56     enabled;
57     disable   = "no";
58     doc       = "This option will disable CA certificate verification. It is to be used with the --dane or --tofu options.";
59 };
60
61 flag = {
62     name      = ocsp;
63     descrip   = "Enable OCSP certificate verification";
64     disabled;
65     disable   = "no";
66     doc       = "This option will enable verification of the peer's certificate using ocsp";
67 };
68
69 flag = {
70     name      = resume;
71     value     = r;
72     descrip   = "Establish a session and resume";
73     doc       = "Connect, establish a session, reconnect and resume.";
74 };
75
76 flag = {
77     name      = rehandshake;
78     value     = e;
79     descrip   = "Establish a session and rehandshake";
80     doc       = "Connect, establish a session and rehandshake immediately.";
81 };
82
83 flag = {
84     name      = starttls;
85     value     = s;
86     descrip   = "Connect, establish a plain session and start TLS";
87     doc       = "The TLS session will be initiated when EOF or a SIGALRM is received.";
88 };
89
90 flag = {
91     name      = app-proto;
92     aliases   = starttls-proto;
93 };
94
95 flag = {
96     name      = starttls-proto;
97     descrip   = "The application protocol to be used to obtain the server's certificate (https, smtp, imap)";
98     arg-type  = string;
99     doc       = "Specify the application layer protocol for STARTTLS. If the protocol is supported, gnutls-cli will proceed to the TLS negotiation.";
100 };
101
102 flag = {
103     name      = udp;
104     value     = u;
105     descrip   = "Use DTLS (datagram TLS) over UDP";
106     doc      = "";
107 };
108
109 flag = {
110     name      = mtu;
111     arg-type  = number;
112     arg-range = "0->17000";
113     descrip   = "Set MTU for datagram TLS";
114     doc      = "";
115 };
116
117 flag = {
118     name      = crlf;
119     descrip   = "Send CR LF instead of LF";
120     doc      = "";
121 };
122
123 flag = {
124     name      = x509fmtder;
125     descrip   = "Use DER format for certificates to read from";
126     doc      = "";
127 };
128
129 flag = {
130     name      = fingerprint;
131     value     = f;
132     descrip   = "Send the openpgp fingerprint, instead of the key";
133     doc      = "";
134 };
135
136 flag = {
137     name      = print-cert;
138     descrip   = "Print peer's certificate in PEM format";
139     doc      = "";
140 };
141
142 flag = {
143     name      = save-cert;
144     arg-type  = string;
145     descrip   = "Save the peer's certificate chain in the specified file in PEM format";
146     doc      = "";
147 };
148
149 flag = {
150     name      = save-ocsp;
151     arg-type  = string;
152     descrip   = "Save the peer's OCSP status response in the provided file";
153     doc      = "";
154 };
155
156 flag = {
157     name      = dh-bits;
158     arg-type  = number;
159     descrip   = "The minimum number of bits allowed for DH";
160     doc      = "This option sets the minimum number of bits allowed for a Diffie-Hellman key exchange. You may want to lower the default value if the peer sends a weak prime and you get an connection error with unacceptable prime.";
161 };
162
163 flag = {
164     name      = priority;
165     arg-type  = string;
166     descrip   = "Priorities string";
167     doc      = "TLS algorithms and protocols to enable. You can
168 use predefined sets of ciphersuites such as PERFORMANCE,
169 NORMAL, PFS, SECURE128, SECURE256. The default is NORMAL.
170
171 Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
172 information on the allowed keywords";
173 };
174
175 flag = {
176     name      = x509cafile;
177     arg-type  = string;
178     descrip   = "Certificate file or PKCS #11 URL to use";
179     doc      = "";
180 };
181
182 flag = {
183     name      = x509crlfile;
184     arg-type  = file;
185     file-exists = yes;
186     descrip   = "CRL file to use";
187     doc      = "";
188 };
189
190 flag = {
191     name      = pgpkeyfile;
192     arg-type  = file;
193     file-exists = yes;
194     descrip   = "PGP Key file to use";
195     doc      = "";
196 };
197
198 flag = {
199     name      = pgpkeyring;
200     arg-type  = file;
201     file-exists = yes;
202     descrip   = "PGP Key ring file to use";
203     doc      = "";
204 };
205
206 flag = {
207     name      = pgpcertfile;
208     arg-type  = file;
209     file-exists = yes;
210     descrip   = "PGP Public Key (certificate) file to use";
211     doc      = "";
212 };
213
214 flag = {
215     name      = x509keyfile;
216     arg-type  = string;
217     descrip   = "X.509 key file or PKCS #11 URL to use";
218     doc      = "";
219 };
220
221 flag = {
222     name      = x509certfile;
223     arg-type  = string;
224     descrip   = "X.509 Certificate file or PKCS #11 URL to use";
225     doc      = "";
226 };
227
228 flag = {
229     name      = pgpsubkey;
230     arg-type  = string;
231     descrip   = "PGP subkey to use (hex or auto)";
232     doc      = "";
233 };
234
235 flag = {
236     name      = srpusername;
237     arg-type  = string;
238     descrip   = "SRP username to use";
239     doc      = "";
240 };
241
242 flag = {
243     name      = srppasswd;
244     arg-type  = string;
245     descrip   = "SRP password to use";
246     doc      = "";
247 };
248
249 flag = {
250     name      = pskusername;
251     arg-type  = string;
252     descrip   = "PSK username to use";
253     doc      = "";
254 };
255
256 flag = {
257     name      = pskkey;
258     arg-type  = string;
259     descrip   = "PSK key (in hex) to use";
260     doc      = "";
261 };
262
263
264 flag = {
265     name      = port;
266     value     = p;
267     arg-type  = string;
268     descrip   = "The port or service to connect to";
269     doc      = "";
270 };
271
272 flag = {
273     name      = insecure;
274     descrip   = "Don't abort program if server certificate can't be validated";
275     doc      = "";
276 };
277
278 flag = {
279     name      = ranges;
280     descrip   = "Use length-hiding padding to prevent traffic analysis";
281     doc      = "When possible (e.g., when using CBC ciphersuites), use length-hiding padding to prevent traffic analysis.";
282 };
283
284 flag = {
285     name      = benchmark-ciphers;
286     descrip   = "Benchmark individual ciphers";
287     doc      = "";
288 };
289
290 flag = {
291     name      = benchmark-tls-kx;
292     descrip   = "Benchmark TLS key exchange methods";
293     doc      = "";
294 };
295
296 flag = {
297     name      = benchmark-tls-ciphers;
298     descrip   = "Benchmark TLS ciphers";
299     doc      = "";
300 };
301
302 flag = {
303     name      = list;
304     value     = l;
305     descrip   = "Print a list of the supported algorithms and modes";
306     doc      = "Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.";
307     flags-cant = port;
308 };
309
310 flag = {
311     name      = priority-list;
312     descrip   = "Print a list of the supported priority strings";
313     doc      = "Print a list of the supported priority strings. The ciphersuites corresponding to each priority string can be examined using -l -p.";
314 };
315
316 flag = {
317     name      = noticket;
318     descrip   = "Don't allow session tickets";
319     doc      = "";
320 };
321
322 flag = {
323     name      = srtp_profiles;
324     arg-type  = string;
325     descrip   = "Offer SRTP profiles";
326     doc       = "";
327 };
328
329 flag = {
330     name      = alpn;
331     arg-type  = string;
332     descrip   = "Application layer protocol";
333     max       = NOLIMIT;  /* occurrence limit (none)     */
334     stack-arg;            /* save opt args in a stack    */
335     doc      = "This option will set and enable the Application Layer Protocol Negotiation  (ALPN) in the TLS protocol.";
336 };
337
338 flag = {
339     name      = heartbeat;
340     value     = b;
341     descrip   = "Activate heartbeat support";
342     doc      = "";
343 };
344
345 flag = {
346     name      = recordsize;
347     arg-type  = number;
348     arg-range = "0->4096";
349     descrip   = "The maximum record size to advertize";
350     doc      = "";
351 };
352
353 flag = {
354     name      = disable-sni;
355     descrip   = "Do not send a Server Name Indication (SNI)";
356     doc      = "";
357 };
358
359 flag = {
360     name      = disable-extensions;
361     descrip   = "Disable all the TLS extensions";
362     doc      = "This option disables all TLS extensions. Deprecated option. Use the priority string.";
363 };
364
365 flag = {
366     name      = inline-commands;
367     descrip   = "Inline commands of the form ^<cmd>^";
368     doc       = "Enable inline commands of the form ^<cmd>^. The inline commands are expected to be in a line by themselves. The available commands are: resume and renegotiate.";
369 };
370
371 flag = {
372     name      = inline-commands-prefix;
373     arg-type  = string;
374     descrip   = "Change the default delimiter for inline commands.";
375     doc       = "Change the default delimiter (^) used for inline commands. The delimiter is expected to be a single US-ASCII character (octets 0 - 127). This option is only relevant if inline commands are enabled via the inline-commands option";
376 };
377
378 flag = {
379     name      = provider;
380     arg-type  = file;
381     file-exists = yes;
382     descrip   = "Specify the PKCS #11 provider library";
383     doc      = "This will override the default options in /etc/gnutls/pkcs11.conf";
384 };
385
386 flag = {
387     name      = fips140-mode;
388     descrip   = "Reports the status of the FIPS140-2 mode in gnutls library";
389     doc      = "";
390 };
391
392 doc-section = {
393   ds-type   = 'SEE ALSO'; // or anything else
394   ds-format = 'texi';      // or texi or mdoc format
395   ds-text   = <<-_EOF_
396 gnutls-cli-debug(1), gnutls-serv(1)
397 _EOF_;
398 };
399
400 doc-section = {
401   ds-type = 'EXAMPLES';
402   ds-format = 'texi';
403   ds-text   = <<-_EOF_
404 @subheading Connecting using PSK authentication
405 To connect to a server using PSK authentication, you need to enable the choice of PSK by using a cipher priority parameter such as in the example below. 
406 @example
407 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
408     --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
409     --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
410 Resolving 'localhost'...
411 Connecting to '127.0.0.1:5556'...
412 - PSK authentication.
413 - Version: TLS1.1
414 - Key Exchange: PSK
415 - Cipher: AES-128-CBC
416 - MAC: SHA1
417 - Compression: NULL
418 - Handshake was completed
419     
420 - Simple Client Mode:
421 @end example
422 By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake. 
423
424 @subheading Listing ciphersuites in a priority string
425 To list the ciphersuites in a priority string:
426 @example
427 $ ./gnutls-cli --priority SECURE192 -l
428 Cipher suites for SECURE192
429 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24   TLS1.2
430 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e   TLS1.2
431 TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30   TLS1.2
432 TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b   TLS1.2
433 TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a   TLS1.2
434 TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d   TLS1.2
435
436 Certificate types: CTYPE-X.509
437 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
438 Compression: COMP-NULL
439 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
440 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
441 @end example
442
443 @subheading Connecting using a PKCS #11 token
444 To connect to a server using a certificate and a private key present in a PKCS #11 token you 
445 need to substitute the PKCS 11 URLs in the x509certfile and x509keyfile parameters.
446
447 Those can be found using "p11tool --list-tokens" and then listing all the objects in the
448 needed token, and using the appropriate.
449 @example
450 $ p11tool --list-tokens
451
452 Token 0:
453         URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
454         Label: Test
455         Manufacturer: EnterSafe
456         Model: PKCS15
457         Serial: 1234
458
459 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
460
461 Object 0:
462         URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert
463         Type: X.509 Certificate
464         Label: client
465         ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
466
467 $ export MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert"
468 $ export MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=private"
469
470 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile MYCERT
471 @end example
472 Notice that the private key only differs from the certificate in the object-type.
473 _EOF_;
474 };