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