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