gnutls-cli: added --starttls-proto 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-ocsp;
144     arg-type  = string;
145     descrip   = "Save the peer's OCSP status response in the provided file";
146     doc      = "";
147 };
148
149 flag = {
150     name      = dh-bits;
151     arg-type  = number;
152     descrip   = "The minimum number of bits allowed for DH";
153     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.";
154 };
155
156 flag = {
157     name      = priority;
158     arg-type  = string;
159     descrip   = "Priorities string";
160     doc      = "TLS algorithms and protocols to enable. You can
161 use predefined sets of ciphersuites such as PERFORMANCE,
162 NORMAL, PFS, SECURE128, SECURE256. The default is NORMAL.
163
164 Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
165 information on the allowed keywords";
166 };
167
168 flag = {
169     name      = x509cafile;
170     arg-type  = string;
171     descrip   = "Certificate file or PKCS #11 URL to use";
172     doc      = "";
173 };
174
175 flag = {
176     name      = x509crlfile;
177     arg-type  = file;
178     file-exists = yes;
179     descrip   = "CRL file to use";
180     doc      = "";
181 };
182
183 flag = {
184     name      = pgpkeyfile;
185     arg-type  = file;
186     file-exists = yes;
187     descrip   = "PGP Key file to use";
188     doc      = "";
189 };
190
191 flag = {
192     name      = pgpkeyring;
193     arg-type  = file;
194     file-exists = yes;
195     descrip   = "PGP Key ring file to use";
196     doc      = "";
197 };
198
199 flag = {
200     name      = pgpcertfile;
201     arg-type  = file;
202     file-exists = yes;
203     descrip   = "PGP Public Key (certificate) file to use";
204     doc      = "";
205 };
206
207 flag = {
208     name      = x509keyfile;
209     arg-type  = string;
210     descrip   = "X.509 key file or PKCS #11 URL to use";
211     doc      = "";
212 };
213
214 flag = {
215     name      = x509certfile;
216     arg-type  = string;
217     descrip   = "X.509 Certificate file or PKCS #11 URL to use";
218     doc      = "";
219 };
220
221 flag = {
222     name      = pgpsubkey;
223     arg-type  = string;
224     descrip   = "PGP subkey to use (hex or auto)";
225     doc      = "";
226 };
227
228 flag = {
229     name      = srpusername;
230     arg-type  = string;
231     descrip   = "SRP username to use";
232     doc      = "";
233 };
234
235 flag = {
236     name      = srppasswd;
237     arg-type  = string;
238     descrip   = "SRP password to use";
239     doc      = "";
240 };
241
242 flag = {
243     name      = pskusername;
244     arg-type  = string;
245     descrip   = "PSK username to use";
246     doc      = "";
247 };
248
249 flag = {
250     name      = pskkey;
251     arg-type  = string;
252     descrip   = "PSK key (in hex) to use";
253     doc      = "";
254 };
255
256
257 flag = {
258     name      = port;
259     value     = p;
260     arg-type  = string;
261     descrip   = "The port or service to connect to";
262     doc      = "";
263 };
264
265 flag = {
266     name      = insecure;
267     descrip   = "Don't abort program if server certificate can't be validated";
268     doc      = "";
269 };
270
271 flag = {
272     name      = ranges;
273     descrip   = "Use length-hiding padding to prevent traffic analysis";
274     doc      = "When possible (e.g., when using CBC ciphersuites), use length-hiding padding to prevent traffic analysis.";
275 };
276
277 flag = {
278     name      = benchmark-ciphers;
279     descrip   = "Benchmark individual ciphers";
280     doc      = "";
281 };
282
283 flag = {
284     name      = benchmark-tls-kx;
285     descrip   = "Benchmark TLS key exchange methods";
286     doc      = "";
287 };
288
289 flag = {
290     name      = benchmark-tls-ciphers;
291     descrip   = "Benchmark TLS ciphers";
292     doc      = "";
293 };
294
295 flag = {
296     name      = list;
297     value     = l;
298     descrip   = "Print a list of the supported algorithms and modes";
299     doc      = "Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.";
300     flags-cant = port;
301 };
302
303 flag = {
304     name      = priority-list;
305     descrip   = "Print a list of the supported priority strings";
306     doc      = "Print a list of the supported priority strings. The ciphersuites corresponding to each priority string can be examined using -l -p.";
307 };
308
309 flag = {
310     name      = noticket;
311     descrip   = "Don't allow session tickets";
312     doc      = "";
313 };
314
315 flag = {
316     name      = srtp_profiles;
317     arg-type  = string;
318     descrip   = "Offer SRTP profiles";
319     doc       = "";
320 };
321
322 flag = {
323     name      = alpn;
324     arg-type  = string;
325     descrip   = "Application layer protocol";
326     max       = NOLIMIT;  /* occurrence limit (none)     */
327     stack-arg;            /* save opt args in a stack    */
328     doc      = "This option will set and enable the Application Layer Protocol Negotiation  (ALPN) in the TLS protocol.";
329 };
330
331 flag = {
332     name      = heartbeat;
333     value     = b;
334     descrip   = "Activate heartbeat support";
335     doc      = "";
336 };
337
338 flag = {
339     name      = recordsize;
340     arg-type  = number;
341     arg-range = "0->4096";
342     descrip   = "The maximum record size to advertize";
343     doc      = "";
344 };
345
346 flag = {
347     name      = disable-sni;
348     descrip   = "Do not send a Server Name Indication (SNI)";
349     doc      = "";
350 };
351
352 flag = {
353     name      = disable-extensions;
354     descrip   = "Disable all the TLS extensions";
355     doc      = "This option disables all TLS extensions. Deprecated option. Use the priority string.";
356 };
357
358 flag = {
359     name      = inline-commands;
360     descrip   = "Inline commands of the form ^<cmd>^";
361     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.";
362 };
363
364 flag = {
365     name      = inline-commands-prefix;
366     arg-type  = string;
367     descrip   = "Change the default (^) used as a delimiter for inline commands.
368 \t\t\t\tThe value is a single US-ASCII character (octets 0 - 127).";
369     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";
370 };
371
372 flag = {
373     name      = provider;
374     arg-type  = file;
375     file-exists = yes;
376     descrip   = "Specify the PKCS #11 provider library";
377     doc      = "This will override the default options in /etc/gnutls/pkcs11.conf";
378 };
379
380 flag = {
381     name      = fips140-mode;
382     descrip   = "Reports the status of the FIPS140-2 mode in gnutls library";
383     doc      = "";
384 };
385
386 doc-section = {
387   ds-type   = 'SEE ALSO'; // or anything else
388   ds-format = 'texi';      // or texi or mdoc format
389   ds-text   = <<-_EOF_
390 gnutls-cli-debug(1), gnutls-serv(1)
391 _EOF_;
392 };
393
394 doc-section = {
395   ds-type = 'EXAMPLES';
396   ds-format = 'texi';
397   ds-text   = <<-_EOF_
398 @subheading Connecting using PSK authentication
399 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. 
400 @example
401 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
402     --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
403     --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
404 Resolving 'localhost'...
405 Connecting to '127.0.0.1:5556'...
406 - PSK authentication.
407 - Version: TLS1.1
408 - Key Exchange: PSK
409 - Cipher: AES-128-CBC
410 - MAC: SHA1
411 - Compression: NULL
412 - Handshake was completed
413     
414 - Simple Client Mode:
415 @end example
416 By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake. 
417
418 @subheading Listing ciphersuites in a priority string
419 To list the ciphersuites in a priority string:
420 @example
421 $ ./gnutls-cli --priority SECURE192 -l
422 Cipher suites for SECURE192
423 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24   TLS1.2
424 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e   TLS1.2
425 TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30   TLS1.2
426 TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b   TLS1.2
427 TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a   TLS1.2
428 TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d   TLS1.2
429
430 Certificate types: CTYPE-X.509
431 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
432 Compression: COMP-NULL
433 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
434 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
435 @end example
436
437 @subheading Connecting using a PKCS #11 token
438 To connect to a server using a certificate and a private key present in a PKCS #11 token you 
439 need to substitute the PKCS 11 URLs in the x509certfile and x509keyfile parameters.
440
441 Those can be found using "p11tool --list-tokens" and then listing all the objects in the
442 needed token, and using the appropriate.
443 @example
444 $ p11tool --list-tokens
445
446 Token 0:
447         URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
448         Label: Test
449         Manufacturer: EnterSafe
450         Model: PKCS15
451         Serial: 1234
452
453 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
454
455 Object 0:
456         URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert
457         Type: X.509 Certificate
458         Label: client
459         ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
460
461 $ export MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert"
462 $ export MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=private"
463
464 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile MYCERT
465 @end example
466 Notice that the private key only differs from the certificate in the object-type.
467 _EOF_;
468 };