_gnutls_strdatum_to_buf() will account for NULL input.

[gnutls.git] / src / cli-args.def

AutoGen Definitions options;
prog-name     = gnutls-cli;
prog-title    = "GnuTLS client";
prog-desc     = "Simple client program to set up a TLS connection.";
short-usage   = "Usage: gnutls-cli [options] hostname\ngnutls-cli --help for usage instructions.\n";
explain       = "";
detail        = "Simple client program to set up a TLS connection to some other computer. 
It sets up a TLS connection and forwards data from the standard input to the secured socket and vice versa.";
reorder-args;
argument = "[hostname]";

#define  VERBOSE_OPT 1
#include args-std.def

flag = {
    name      = tofu;
    descrip   = "Enable trust on first use authentication";
    disabled;
    disable   = "no";
    doc       = "This option will, in addition to certificate authentication, perform authentication based on previously seen public keys, a model similar to SSH authentication.";
};

flag = {
    name      = dane;
    descrip   = "Enable DANE certificate verification (DNSSEC)";
    disabled;
    disable   = "no";
    doc       = "This option will, in addition to certificate authentication using 
the trusted CAs, verify the server certificates using on the DANE information
available via DNSSEC.";
};

flag = {
    name      = local-dns;
    descrip   = "Use the local DNS server for DNSSEC resolving.";
    disabled;
    disable   = "no";
    doc       = "This option will use the local DNS server for DNSSEC.
This is disabled by default due to many servers not allowing DNSSEC.";
};

flag = {
    name      = ca-verification;
    descrip   = "Disable CA certificate verification";
    enabled;
    disable   = "no";
    doc       = "This option will disable CA certificate verification. It is to be used with the --dane or --tofu options.";
};

flag = {
    name      = ocsp;
    descrip   = "Enable OCSP certificate verification";
    disabled;
    disable   = "no";
    doc       = "This option will enable verification of the peer's certificate using ocsp";
};

flag = {
    name      = resume;
    value     = r;
    descrip   = "Establish a session and resume";
    doc       = "Connect, establish a session, reconnect and resume.";
};

flag = {
    name      = heartbeat;
    value     = b;
    descrip   = "Activate heartbeat support";
    doc      = "";
};

flag = {
    name      = rehandshake;
    value     = e;
    descrip   = "Establish a session and rehandshake";
    doc       = "Connect, establish a session and rehandshake immediately.";
};

flag = {
    name      = noticket;
    descrip   = "Don't accept session tickets";
    doc      = "";
};

flag = {
    name      = starttls;
    value     = s;
    descrip   = "Connect, establish a plain session and start TLS.";
    doc       = "The TLS session will be initiated when EOF or a SIGALRM is received.";
};

flag = {
    name      = udp;
    value     = u;
    descrip   = "Use DTLS (datagram TLS) over UDP";
    doc      = "";
};

flag = {
    name      = mtu;
    arg-type  = number;
    arg-range = "0->17000";
    descrip   = "Set MTU for datagram TLS";
    doc      = "";
};

flag = {
    name      = srtp_profiles;
    arg-type  = string;
    descrip   = "Offer SRTP profiles";
    doc       = "";
};

flag = {
    name      = crlf;
    descrip   = "Send CR LF instead of LF";
    doc      = "";
};

flag = {
    name      = x509fmtder;
    descrip   = "Use DER format for certificates to read from";
    doc      = "";
};

flag = {
    name      = fingerprint;
    value     = f;
    descrip   = "Send the openpgp fingerprint, instead of the key";
    doc      = "";
};

flag = {
    name      = disable-extensions;
    descrip   = "Disable all the TLS extensions";
    doc      = "This option disables all TLS extensions. Deprecated option. Use the priority string.";
};

flag = {
    name      = print-cert;
    descrip   = "Print peer's certificate in PEM format";
    doc      = "";
};

flag = {
    name      = recordsize;
    arg-type  = number;
    arg-range = "0->4096";
    descrip   = "The maximum record size to advertize";
    doc      = "";
};

flag = {
    name      = dh-bits;
    arg-type  = number;
    descrip   = "The minimum number of bits allowed for DH";
    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.";
};

flag = {
    name      = priority;
    arg-type  = string;
    descrip   = "Priorities string";
    doc      = "TLS algorithms and protocols to enable. You can
use predefined sets of ciphersuites such as PERFORMANCE,
NORMAL, SECURE128, SECURE256.

Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
information on allowed keywords";
};

flag = {
    name      = x509cafile;
    arg-type  = string;
    descrip   = "Certificate file or PKCS #11 URL to use";
    doc      = "";
};

flag = {
    name      = x509crlfile;
    arg-type  = file;
    file-exists = yes;
    descrip   = "CRL file to use";
    doc      = "";
};

flag = {
    name      = pgpkeyfile;
    arg-type  = file;
    file-exists = yes;
    descrip   = "PGP Key file to use";
    doc      = "";
};

flag = {
    name      = pgpkeyring;
    arg-type  = file;
    file-exists = yes;
    descrip   = "PGP Key ring file to use";
    doc      = "";
};

flag = {
    name      = pgpcertfile;
    arg-type  = file;
    file-exists = yes;
    descrip   = "PGP Public Key (certificate) file to use";
    doc      = "";
};

flag = {
    name      = x509keyfile;
    arg-type  = string;
    descrip   = "X.509 key file or PKCS #11 URL to use";
    doc      = "";
};

flag = {
    name      = x509certfile;
    arg-type  = string;
    descrip   = "X.509 Certificate file or PKCS #11 URL to use";
    doc      = "";
};

flag = {
    name      = pgpsubkey;
    arg-type  = string;
    descrip   = "PGP subkey to use (hex or auto)";
    doc      = "";
};

flag = {
    name      = srpusername;
    arg-type  = string;
    descrip   = "SRP username to use";
    doc      = "";
};

flag = {
    name      = srppasswd;
    arg-type  = string;
    descrip   = "SRP password to use";
    doc      = "";
};

flag = {
    name      = pskusername;
    arg-type  = string;
    descrip   = "PSK username to use";
    doc      = "";
};

flag = {
    name      = pskkey;
    arg-type  = string;
    descrip   = "PSK key (in hex) to use";
    doc      = "";
};

flag = {
    name      = port;
    value     = p;
    arg-type  = string;
    descrip   = "The port or service to connect to";
    doc      = "";
};

flag = {
    name      = insecure;
    descrip   = "Don't abort program if server certificate can't be validated";
    doc      = "";
};

flag = {
    name      = benchmark-ciphers;
    descrip   = "Benchmark individual ciphers";
    doc      = "";
};

flag = {
    name      = benchmark-soft-ciphers;
    descrip   = "Benchmark individual software ciphers (no hw acceleration)";
    doc      = "";
};

flag = {
    name      = benchmark-tls-kx;
    descrip   = "Benchmark TLS key exchange methods";
    doc      = "";
};

flag = {
    name      = benchmark-tls-ciphers;
    descrip   = "Benchmark TLS ciphers";
    doc      = "";
};

flag = {
    name      = list;
    value     = l;
    descrip   = "Print a list of the supported algorithms and modes";
    doc      = "Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.";
};



doc-section = {
  ds-type   = 'SEE ALSO'; // or anything else
  ds-format = 'texi';      // or texi or mdoc format
  ds-text   = <<-_EOF_
gnutls-cli-debug(1), gnutls-serv(1)
_EOF_;
};

doc-section = {
  ds-type = 'EXAMPLES';
  ds-format = 'texi';
  ds-text   = <<-_EOF_
@subheading Connecting using PSK authentication
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. 
@example
$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
    --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
    --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
Resolving 'localhost'...
Connecting to '127.0.0.1:5556'...
- PSK authentication.
- Version: TLS1.1
- Key Exchange: PSK
- Cipher: AES-128-CBC
- MAC: SHA1
- Compression: NULL
- Handshake was completed
    
- Simple Client Mode:
@end example
By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake. 

@subheading Listing ciphersuites in a priority string
To list the ciphersuites in a priority string:
@example
$ ./gnutls-cli --priority SECURE192 -l
Cipher suites for SECURE192
TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24   TLS1.2
TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e   TLS1.2
TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30   TLS1.2
TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b   TLS1.2
TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a   TLS1.2
TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d   TLS1.2

Certificate types: CTYPE-X.509
Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
Compression: COMP-NULL
Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
@end example
_EOF_;
};