NAME¶
SSL_CONF_cmd - send configuration command
SYNOPSIS¶
#include <openssl/ssl.h>
int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);
int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd);
int SSL_CONF_finish(SSL_CONF_CTX *cctx);
DESCRIPTION¶
The function
SSL_CONF_cmd() performs configuration operation
cmd
with optional parameter
value on
ctx. Its purpose is to simplify
application configuration of
SSL_CTX or
SSL structures by
providing a common framework for command line options or configuration files.
SSL_CONF_cmd_value_type() returns the type of value that
cmd
refers to.
The function
SSL_CONF_finish() must be called after all configuration
operations have been completed. It is used to finalise any operations or to
process defaults.
SUPPORTED COMMAND LINE COMMANDS¶
Currently supported
cmd names for command lines (i.e. when the flag
SSL_CONF_CMDLINE is set) are listed below. Note: all
cmd names
are case sensitive. Unless otherwise stated commands can be used by both
clients and servers and the
value parameter is not used. The default
prefix for command line commands is
- and that is reflected below.
- -sigalgs
- This sets the supported signature algorithms for TLS v1.2. For clients
this value is used directly for the supported signature algorithms
extension. For servers it is used to determine which signature algorithms
to support.
The value argument should be a colon separated list of signature
algorithms in order of decreasing preference of the form
algorithm+hash. algorithm is one of RSA, DSA
or ECDSA and hash is a supported algorithm OID short name
such as SHA1, SHA224, SHA256, SHA384 of
SHA512. Note: algorithm and hash names are case sensitive.
If this option is not set then all signature algorithms supported by the
OpenSSL library are permissible.
- -client_sigalgs
- This sets the supported signature algorithms associated with client
authentication for TLS v1.2. For servers the value is used in the
supported signature algorithms field of a certificate request. For clients
it is used to determine which signature algorithm to with the client
certificate. If a server does not request a certificate this option has no
effect.
The syntax of value is identical to -sigalgs. If not set then
the value set for -sigalgs will be used instead.
- -curves
- This sets the supported elliptic curves. For clients the curves are sent
using the supported curves extension. For servers it is used to determine
which curve to use. This setting affects curves used for both signatures
and key exchange, if applicable.
The value argument is a colon separated list of curves. The curve can
be either the NIST name (e.g. P-256) or an OpenSSL OID name
(e.g prime256v1). Curve names are case sensitive.
- -named_curve
- This sets the temporary curve used for ephemeral ECDH modes. Only used by
servers
The value argument is a curve name or the special value auto
which picks an appropriate curve based on client and server preferences.
The curve can be either the NIST name (e.g. P-256) or an
OpenSSL OID name (e.g prime256v1). Curve names are case
sensitive.
- -cipher
- Sets the cipher suite list to value. Note: syntax checking of
value is currently not performed unless a SSL or
SSL_CTX structure is associated with cctx.
- -cert
- Attempts to use the file value as the certificate for the
appropriate context. It currently uses
SSL_CTX_use_certificate_chain_file() if an SSL_CTX structure
is set or SSL_use_certificate_file() with filetype PEM if an
SSL structure is set. This option is only supported if certificate
operations are permitted.
- -key
- Attempts to use the file value as the private key for the
appropriate context. This option is only supported if certificate
operations are permitted. Note: if no -key option is set then a
private key is not loaded: it does not currently use the -cert
file.
- -dhparam
- Attempts to use the file value as the set of temporary DH
parameters for the appropriate context. This option is only supported if
certificate operations are permitted.
- -no_ssl2, -no_ssl3, -no_tls1, -no_tls1_1,
-no_tls1_2
- Disables protocol support for SSLv2, SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2 by
setting the corresponding options SSL_OP_NO_SSLv2,
SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1
and SSL_OP_NO_TLSv1_2 respectively.
- -bugs
- Various bug workarounds are set, same as setting SSL_OP_ALL.
- -no_comp
- Disables support for SSL/TLS compression, same as setting
SSL_OP_NO_COMPRESS.
- -no_ticket
- Disables support for session tickets, same as setting
SSL_OP_NO_TICKET.
- -serverpref
- Use server and not client preference order when determining which cipher
suite, signature algorithm or elliptic curve to use for an incoming
connection. Equivalent to SSL_OP_CIPHER_SERVER_PREFERENCE. Only
used by servers.
- -no_resumption_on_reneg
- set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by
servers.
- -legacyrenegotiation
- permits the use of unsafe legacy renegotiation. Equivalent to setting
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION.
- -legacy_server_connect, -no_legacy_server_connect
- permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
clients only. Equivalent to setting or clearing
SSL_OP_LEGACY_SERVER_CONNECT. Set by default.
- -strict
- enables strict mode protocol handling. Equivalent to setting
SSL_CERT_FLAG_TLS_STRICT.
- -debug_broken_protocol
- disables various checks and permits several kinds of broken protocol
behaviour for testing purposes: it should NEVER be used in anything
other than a test environment. Only supported if OpenSSL is configured
with -DOPENSSL_SSL_DEBUG_BROKEN_PROTOCOL.
SUPPORTED CONFIGURATION FILE COMMANDS¶
Currently supported
cmd names for configuration files (i.e. when the flag
SSL_CONF_FLAG_FILE is set) are listed below. All configuration file
cmd names and are case insensitive so
signaturealgorithms is
recognised as well as
SignatureAlgorithms. Unless otherwise stated the
value names are also case insensitive.
Note: the command prefix (if set) alters the recognised
cmd values.
- CipherString
- Sets the cipher suite list to value. Note: syntax checking of
value is currently not performed unless an SSL or
SSL_CTX structure is associated with cctx.
- Certificate
- Attempts to use the file value as the certificate for the
appropriate context. It currently uses
SSL_CTX_use_certificate_chain_file() if an SSL_CTX structure
is set or SSL_use_certificate_file() with filetype PEM if an
SSL structure is set. This option is only supported if certificate
operations are permitted.
- PrivateKey
- Attempts to use the file value as the private key for the
appropriate context. This option is only supported if certificate
operations are permitted. Note: if no -key option is set then a
private key is not loaded: it does not currently use the
Certificate file.
- ServerInfoFile
- Attempts to use the file value in the "serverinfo"
extension using the function SSL_CTX_use_serverinfo_file.
- DHParameters
- Attempts to use the file value as the set of temporary DH
parameters for the appropriate context. This option is only supported if
certificate operations are permitted.
- SignatureAlgorithms
- This sets the supported signature algorithms for TLS v1.2. For clients
this value is used directly for the supported signature algorithms
extension. For servers it is used to determine which signature algorithms
to support.
The value argument should be a colon separated list of signature
algorithms in order of decreasing preference of the form
algorithm+hash. algorithm is one of RSA, DSA
or ECDSA and hash is a supported algorithm OID short name
such as SHA1, SHA224, SHA256, SHA384 of
SHA512. Note: algorithm and hash names are case sensitive.
If this option is not set then all signature algorithms supported by the
OpenSSL library are permissible.
- ClientSignatureAlgorithms
- This sets the supported signature algorithms associated with client
authentication for TLS v1.2. For servers the value is used in the
supported signature algorithms field of a certificate request. For clients
it is used to determine which signature algorithm to with the client
certificate.
The syntax of value is identical to SignatureAlgorithms. If
not set then the value set for SignatureAlgorithms will be used
instead.
- Curves
- This sets the supported elliptic curves. For clients the curves are sent
using the supported curves extension. For servers it is used to determine
which curve to use. This setting affects curves used for both signatures
and key exchange, if applicable.
The value argument is a colon separated list of curves. The curve can
be either the NIST name (e.g. P-256) or an OpenSSL OID name
(e.g prime256v1). Curve names are case sensitive.
- ECDHParameters
- This sets the temporary curve used for ephemeral ECDH modes. Only used by
servers
The value argument is a curve name or the special value
Automatic which picks an appropriate curve based on client and
server preferences. The curve can be either the NIST name (e.g.
P-256) or an OpenSSL OID name (e.g prime256v1). Curve names
are case sensitive.
- Protocol
- The supported versions of the SSL or TLS protocol.
The value argument is a comma separated list of supported protocols
to enable or disable. If an protocol is preceded by - that version
is disabled. Currently supported protocol values are SSLv2,
SSLv3, TLSv1, TLSv1.1 and TLSv1.2. All
protocol versions other than SSLv2 are enabled by default. To avoid
inadvertent enabling of SSLv2, when SSLv2 is disabled, it is not
possible to enable it via the Protocol command.
- Options
- The value argument is a comma separated list of various flags to
set. If a flag string is preceded - it is disabled. See the
SSL_CTX_set_options function for more details of individual
options.
Each option is listed below. Where an operation is enabled by default the
-flag syntax is needed to disable it.
SessionTicket: session ticket support, enabled by default. Inverse
of SSL_OP_NO_TICKET: that is -SessionTicket is the same as
setting SSL_OP_NO_TICKET.
Compression: SSL/TLS compression support, enabled by default.
Inverse of SSL_OP_NO_COMPRESSION.
EmptyFragments: use empty fragments as a countermeasure against a
SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It is set by
default. Inverse of SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS.
Bugs: enable various bug workarounds. Same as SSL_OP_ALL.
DHSingle: enable single use DH keys, set by default. Inverse of
SSL_OP_DH_SINGLE. Only used by servers.
ECDHSingle enable single use ECDH keys, set by default. Inverse of
SSL_OP_ECDH_SINGLE. Only used by servers.
ServerPreference use server and not client preference order when
determining which cipher suite, signature algorithm or elliptic curve to
use for an incoming connection. Equivalent to
SSL_OP_CIPHER_SERVER_PREFERENCE. Only used by servers.
NoResumptionOnRenegotiation set
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by
servers.
UnsafeLegacyRenegotiation permits the use of unsafe legacy
renegotiation. Equivalent to
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION.
UnsafeLegacyServerConnect permits the use of unsafe legacy
renegotiation for OpenSSL clients only. Equivalent to
SSL_OP_LEGACY_SERVER_CONNECT. Set by default.
SUPPORTED COMMAND TYPES¶
The function
SSL_CONF_cmd_value_type() currently returns one of the
following types:
- SSL_CONF_TYPE_UNKNOWN
- The cmd string is unrecognised, this return value can be use to
flag syntax errors.
- SSL_CONF_TYPE_STRING
- The value is a string without any specific structure.
- SSL_CONF_TYPE_FILE
- The value is a file name.
- SSL_CONF_TYPE_DIR
- The value is a directory name.
NOTES¶
The order of operations is significant. This can be used to set either defaults
or values which cannot be overridden. For example if an application calls:
SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
SSL_CONF_cmd(ctx, userparam, uservalue);
it will disable SSLv3 support by default but the user can override it. If
however the call sequence is:
SSL_CONF_cmd(ctx, userparam, uservalue);
SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
then SSLv3 is
always disabled and attempt to override this by the user
are ignored.
By checking the return code of
SSL_CTX_cmd() it is possible to query if a
given
cmd is recognised, this is useful is
SSL_CTX_cmd() values
are mixed with additional application specific operations.
For example an application might call
SSL_CTX_cmd() and if it returns -2
(unrecognised command) continue with processing of application specific
commands.
Applications can also use
SSL_CTX_cmd() to process command lines though
the utility function
SSL_CTX_cmd_argv() is normally used instead. One
way to do this is to set the prefix to an appropriate value using
SSL_CONF_CTX_set1_prefix(), pass the current argument to
cmd and
the following argument to
value (which may be NULL).
In this case if the return value is positive then it is used to skip that number
of arguments as they have been processed by
SSL_CTX_cmd(). If -2 is
returned then
cmd is not recognised and application specific arguments
can be checked instead. If -3 is returned a required argument is missing and
an error is indicated. If 0 is returned some other error occurred and this can
be reported back to the user.
The function
SSL_CONF_cmd_value_type() can be used by applications to
check for the existence of a command or to perform additional syntax checking
or translation of the command value. For example if the return value is
SSL_CONF_TYPE_FILE an application could translate a relative pathname
to an absolute pathname.
EXAMPLES¶
Set supported signature algorithms:
SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
Enable all protocols except SSLv3 and SSLv2:
SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2");
Only enable TLSv1.2:
SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
Disable TLS session tickets:
SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
Set supported curves to P-256, P-384:
SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
Set automatic support for any elliptic curve for key exchange:
SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic");
RETURN VALUES¶
SSL_CONF_cmd() returns 1 if the value of
cmd is recognised and
value is
NOT used and 2 if both
cmd and
value are
used. In other words it returns the number of arguments processed. This is
useful when processing command lines.
A return value of -2 means
cmd is not recognised.
A return value of -3 means
cmd is recognised and the command requires a
value but
value is NULL.
A return code of 0 indicates that both
cmd and
value are valid but
an error occurred attempting to perform the operation: for example due to an
error in the syntax of
value in this case the error queue may provide
additional information.
SSL_CONF_finish() returns 1 for success and 0 for failure.
SEE ALSO¶
SSL_CONF_CTX_new(3),
SSL_CONF_CTX_set_flags(3),
SSL_CONF_CTX_set1_prefix(3),
SSL_CONF_CTX_set_ssl_ctx(3),
SSL_CONF_cmd_argv(3)
HISTORY¶
SSL_CONF_cmd() was first added to OpenSSL 1.0.2