#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_cmd(SSL_CONF_CTX *ctx, const char *option, const char *value);
+ int SSL_CONF_cmd_value_type(SSL_CONF_CTX *ctx, const char *option);
=head1 DESCRIPTION
-The function SSL_CONF_cmd() performs configuration operation B<cmd> with
+The function SSL_CONF_cmd() performs configuration operation B<option> with
optional parameter B<value> on B<ctx>. Its purpose is to simplify application
configuration of B<SSL_CTX> or B<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 B<cmd> refers to.
+SSL_CONF_cmd_value_type() returns the type of value that B<option> refers to.
=head1 SUPPORTED COMMAND LINE COMMANDS
-Currently supported B<cmd> names for command lines (i.e. when the
-flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<cmd> names
+Currently supported B<option> names for command lines (i.e. when the
+flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<option> names
are case sensitive. Unless otherwise stated commands can be used by
both clients and servers and the B<value> parameter is not used. The default
prefix for command line commands is B<-> and that is reflected below.
=over 4
-=item B<-sigalgs>
+=item B<-bugs>
-This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
-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.
+Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
-The B<value> argument should be a colon separated list of signature algorithms
-in order of decreasing preference of the form B<algorithm+hash> or
-B<signature_scheme>. B<algorithm>
-is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
-OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
-Note: algorithm and hash names are case sensitive.
-B<signature_scheme> is one of the signature schemes defined in TLSv1.3,
-specified using the IETF name, e.g., B<ecdsa_secp256r1_sha256>, B<ed25519>,
-or B<rsa_pss_pss_sha256>.
+=item B<-no_comp>
-If this option is not set then all signature algorithms supported by the
-OpenSSL library are permissible.
+Disables support for SSL/TLS compression, same as setting
+B<SSL_OP_NO_COMPRESSION>.
+As of OpenSSL 1.1.0, compression is off by default.
-Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
-using B<RSA> as the B<algorithm> or by using one of the B<rsa_pkcs1_*>
-identifiers) are ignored in TLSv1.3 and will not be negotiated.
+=item B<-comp>
-=item B<-client_sigalgs>
+Enables support for SSL/TLS compression, same as clearing
+B<SSL_OP_NO_COMPRESSION>.
+This command was introduced in OpenSSL 1.1.0.
+As of OpenSSL 1.1.0, compression is off by default.
-This sets the supported signature algorithms associated with client
-authentication for TLSv1.2 and TLSv1.3.
-For servers the value is used in the
-B<signature_algorithms> field of a B<CertificateRequest> message.
-For clients it is
-used to determine which signature algorithm to use with the client certificate.
-If a server does not request a certificate this option has no effect.
+=item B<-no_ticket>
-The syntax of B<value> is identical to B<-sigalgs>. If not set then
-the value set for B<-sigalgs> will be used instead.
+Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
-=item B<-groups>
+=item B<-serverpref>
-This sets the supported groups. For clients, the groups are
-sent using the supported groups extension. For servers, it is used
-to determine which group to use. This setting affects groups used for
-signatures (in TLSv1.2 and earlier) and key exchange. The first group listed
-will also be used for the B<key_share> sent by a client in a TLSv1.3
-B<ClientHello>.
+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 B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
-The B<value> argument is a colon separated list of groups. The group can be
-either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
-applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
-(e.g B<prime256v1>). Group names are case sensitive. The list should be in
-order of preference with the most preferred group first.
+=item B<-legacyrenegotiation>
-Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
-B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
-B<ffdhe8192>.
+permits the use of unsafe legacy renegotiation. Equivalent to setting
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
-=item B<-curves>
+=item B<-no_renegotiation>
-This is a synonym for the "-groups" command.
+Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
+B<SSL_OP_NO_RENEGOTIATION>.
-=item B<-named_curve>
+=item B<-no_resumption_on_reneg>
-This sets the temporary curve used for ephemeral ECDH modes. Only used by
-servers
+set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers.
-The B<value> argument is a curve name or the special value B<auto> which
-picks an appropriate curve based on client and server preferences. The curve
-can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
-(e.g B<prime256v1>). Curve names are case sensitive.
+=item B<-legacy_server_connect>, B<-no_legacy_server_connect>
-=item B<-cipher>
+permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
+clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
+Set by default.
-Sets the TLSv1.2 and below ciphersuite list to B<value>. This list will be
-combined with any configured TLSv1.3 ciphersuites. Note: syntax checking
-of B<value> is currently not performed unless a B<SSL> or B<SSL_CTX> structure is
-associated with B<cctx>.
+=item B<-prioritize_chacha>
-=item B<-ciphersuites>
+Prioritize ChaCha ciphers when the client has a ChaCha20 cipher at the top of
+its preference list. This usually indicates a client without AES hardware
+acceleration (e.g. mobile) is in use. Equivalent to B<SSL_OP_PRIORITIZE_CHACHA>.
+Only used by servers. Requires B<-serverpref>.
-Sets the available ciphersuites for TLSv1.3 to value. This is a simple colon
-(":") separated list of TLSv1.3 ciphersuite names in order of preference. This
-list will be combined any configured TLSv1.2 and below ciphersuites.
-See L<openssl-ciphers(1)> for more information.
+=item B<-allow_no_dhe_kex>
+In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means
+that there will be no forward secrecy for the resumed session.
-=item B<-cert>
+=item B<-strict>
-Attempts to use the file B<value> as the certificate for the appropriate
-context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
-structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
-structure is set. This option is only supported if certificate operations
-are permitted.
+enables strict mode protocol handling. Equivalent to setting
+B<SSL_CERT_FLAG_TLS_STRICT>.
-=item B<-key>
+=item B<-sigalgs> I<algs>
-Attempts to use the file B<value> as the private key for the appropriate
-context. This option is only supported if certificate operations
-are permitted. Note: if no B<-key> option is set then a private key is
-not loaded unless the flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
+This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
+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 B<algs> argument should be a colon separated list of signature
+algorithms in order of decreasing preference of the form B<algorithm+hash>
+or B<signature_scheme>. B<algorithm> is one of B<RSA>, B<DSA> or B<ECDSA> and
+B<hash> is a supported algorithm OID short name such as B<SHA1>, B<SHA224>,
+B<SHA256>, B<SHA384> of B<SHA512>. Note: algorithm and hash names are case
+sensitive. B<signature_scheme> is one of the signature schemes defined in
+TLSv1.3, specified using the IETF name, e.g., B<ecdsa_secp256r1_sha256>,
+B<ed25519>, or B<rsa_pss_pss_sha256>.
-=item B<-dhparam>
+If this option is not set then all signature algorithms supported by the
+OpenSSL library are permissible.
-Attempts to use the file B<value> as the set of temporary DH parameters for
-the appropriate context. This option is only supported if certificate
-operations are permitted.
+Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
+using B<RSA> as the B<algorithm> or by using one of the B<rsa_pkcs1_*>
+identifiers) are ignored in TLSv1.3 and will not be negotiated.
-=item B<-record_padding>
+=item B<-client_sigalgs> I<algs>
-Attempts to pad TLSv1.3 records so that they are a multiple of B<value> in
-length on send. A B<value> of 0 or 1 turns off padding. Otherwise, the
-B<value> must be >1 or <=16384.
+This sets the supported signature algorithms associated with client
+authentication for TLSv1.2 and TLSv1.3. For servers the B<algs> is used
+in the B<signature_algorithms> field of a B<CertificateRequest> message.
+For clients it is used to determine which signature algorithm to use with
+the client certificate. If a server does not request a certificate this
+option has no effect.
-=item B<-no_renegotiation>
+The syntax of B<algs> is identical to B<-sigalgs>. If not set, then the
+value set for B<-sigalgs> will be used instead.
-Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
-B<SSL_OP_NO_RENEGOTIATION>.
+=item B<-groups> I<groups>
-=item B<-min_protocol>, B<-max_protocol>
+This sets the supported groups. For clients, the groups are sent using
+the supported groups extension. For servers, it is used to determine which
+group to use. This setting affects groups used for signatures (in TLSv1.2
+and earlier) and key exchange. The first group listed will also be used
+for the B<key_share> sent by a client in a TLSv1.3 B<ClientHello>.
-Sets the minimum and maximum supported protocol.
-Currently supported protocol values are B<SSLv3>, B<TLSv1>,
-B<TLSv1.1>, B<TLSv1.2>, B<TLSv1.3> for TLS and B<DTLSv1>, B<DTLSv1.2> for DTLS,
-and B<None> for no limit.
-If either bound is not specified then only the other bound applies,
-if specified.
-To restrict the supported protocol versions use these commands rather
-than the deprecated alternative commands below.
+The B<groups> argument is a colon separated list of groups. The group can
+be either the B<NIST> name (e.g. B<P-256>), some other commonly used name
+where applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
+(e.g B<prime256v1>). Group names are case sensitive. The list should be
+in order of preference with the most preferred group first.
-=item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
+Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
+B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
+B<ffdhe8192>.
-Disables protocol support for SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3 by
-setting the corresponding options B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>,
-B<SSL_OP_NO_TLSv1_1>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3>
-respectively. These options are deprecated, instead use B<-min_protocol> and
-B<-max_protocol>.
+=item B<-curves> I<groups>
-=item B<-bugs>
+This is a synonym for the B<-groups> command.
-Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
+=item B<-named_curve> I<curve>
-=item B<-comp>
+This sets the temporary curve used for ephemeral ECDH modes. Only used
+by servers.
-Enables support for SSL/TLS compression, same as clearing
-B<SSL_OP_NO_COMPRESSION>.
-This command was introduced in OpenSSL 1.1.0.
-As of OpenSSL 1.1.0, compression is off by default.
+The B<groups> argument is a curve name or the special value B<auto> which
+picks an appropriate curve based on client and server preferences. The
+curve can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
+(e.g B<prime256v1>). Curve names are case sensitive.
-=item B<-no_comp>
+=item B<-cipher> I<ciphers>
-Disables support for SSL/TLS compression, same as setting
-B<SSL_OP_NO_COMPRESSION>.
-As of OpenSSL 1.1.0, compression is off by default.
+Sets the TLSv1.2 and below ciphersuite list to B<ciphers>. This list will be
+combined with any configured TLSv1.3 ciphersuites. Note: syntax checking
+of B<ciphers> is currently not performed unless a B<SSL> or B<SSL_CTX>
+structure is associated with B<ctx>.
-=item B<-no_ticket>
+=item B<-ciphersuites> I<1.3ciphers>
-Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
+Sets the available ciphersuites for TLSv1.3 to value. This is a
+colon-separated list of TLSv1.3 ciphersuite names in order of preference. This
+list will be combined any configured TLSv1.2 and below ciphersuites.
+See L<openssl-ciphers(1)> for more information.
-=item B<-serverpref>
+=item B<-min_protocol> I<minprot>, B<-max_protocol> I<maxprot>
-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 B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
+Sets the minimum and maximum supported protocol. Currently supported
+protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<TLSv1.3>
+for TLS and B<DTLSv1>, B<DTLSv1.2> for DTLS, and B<None> for no limit.
+If either bound is not specified then only the other bound applies,
+if specified. To restrict the supported protocol versions use these
+commands rather than the deprecated alternative commands below.
-=item B<-prioritize_chacha>
+=item B<-record_padding> I<padding>
-Prioritize ChaCha ciphers when the client has a ChaCha20 cipher at the top of
-its preference list. This usually indicates a client without AES hardware
-acceleration (e.g. mobile) is in use. Equivalent to B<SSL_OP_PRIORITIZE_CHACHA>.
-Only used by servers. Requires B<-serverpref>.
+Attempts to pad TLSv1.3 records so that they are a multiple of B<padding>
+in length on send. A B<padding> of 0 or 1 turns off padding. Otherwise,
+the B<padding> must be >1 or <=16384.
-=item B<-no_resumption_on_reneg>
+=item B<-debug_broken_protocol>
-set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers.
+=item B<-no_middlebox>
-=item B<-legacyrenegotiation>
+=back
-permits the use of unsafe legacy renegotiation. Equivalent to setting
-B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
+=head2 Additional Options
-=item B<-legacy_server_connect>, B<-no_legacy_server_connect>
+The following options are accepted by SSL_CONF_cmd(), but are not
+processed by the OpenSSL commands.
-permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
-clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
-Set by default.
+=over 4
-=item B<-allow_no_dhe_kex>
+=item B<-cert> I<file>
-In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means
-that there will be no forward secrecy for the resumed session.
+Attempts to use B<file> as the certificate for the appropriate context. It
+currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
+structure is set or SSL_use_certificate_file() with filetype PEM if an
+B<SSL> structure is set. This option is only supported if certificate
+operations are permitted.
-=item B<-strict>
+=item B<-key> I<file>
-enables strict mode protocol handling. Equivalent to setting
-B<SSL_CERT_FLAG_TLS_STRICT>.
+Attempts to use B<file> as the private key for the appropriate context. This
+option is only supported if certificate operations are permitted. Note:
+if no B<-key> option is set then a private key is not loaded unless the
+flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
+
+=item B<-dhparam> I<file>
+
+Attempts to use B<file> as the set of temporary DH parameters for
+the appropriate context. This option is only supported if certificate
+operations are permitted.
+
+=item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
+
+Disables protocol support for SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3 by
+setting the corresponding options B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>,
+B<SSL_OP_NO_TLSv1_1>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3>
+respectively. These options are deprecated, use B<-min_protocol> and
+B<-max_protocol> instead.
=item B<-anti_replay>, B<-no_anti_replay>
=head1 SUPPORTED CONFIGURATION FILE COMMANDS
-Currently supported B<cmd> names for configuration files (i.e. when the
+Currently supported B<option> names for configuration files (i.e., when the
flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
-B<cmd> names are case insensitive so B<signaturealgorithms> is recognised
+B<option> names are case insensitive so B<signaturealgorithms> is recognised
as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
are also case insensitive.
-Note: the command prefix (if set) alters the recognised B<cmd> values.
+Note: the command prefix (if set) alters the recognised B<option> values.
=over 4
Sets the ciphersuite list for TLSv1.2 and below to B<value>. This list will be
combined with any configured TLSv1.3 ciphersuites. Note: syntax
checking of B<value> is currently not performed unless an B<SSL> or B<SSL_CTX>
-structure is associated with B<cctx>.
+structure is associated with B<ctx>.
=item B<Ciphersuites>
-Sets the available ciphersuites for TLSv1.3 to B<value>. This is a simple colon
-(":") separated list of TLSv1.3 ciphersuite names in order of preference. This
+Sets the available ciphersuites for TLSv1.3 to B<value>. This is a
+colon-separated list of TLSv1.3 ciphersuite names in order of preference. This
list will be combined any configured TLSv1.2 and below ciphersuites.
See L<openssl-ciphers(1)> for more information.
=item B<SSL_CONF_TYPE_UNKNOWN>
-The B<cmd> string is unrecognised, this return value can be use to flag
+The B<option> string is unrecognised, this return value can be use to flag
syntax errors.
=item B<SSL_CONF_TYPE_STRING>
ignored.
By checking the return code of SSL_CONF_cmd() it is possible to query if a
-given B<cmd> is recognised, this is useful if SSL_CONF_cmd() values are
+given B<option> is recognised, this is useful if SSL_CONF_cmd() values are
mixed with additional application specific operations.
For example an application might call SSL_CONF_cmd() and if it returns
Applications can also use SSL_CONF_cmd() to process command lines though the
utility function SSL_CONF_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 B<cmd> and the
+SSL_CONF_CTX_set1_prefix(), pass the current argument to B<option> and the
following argument to B<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_CONF_cmd(). If -2 is
-returned then B<cmd> is not recognised and application specific arguments
+returned then B<option> 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.
=head1 RETURN VALUES
-SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
-B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
+SSL_CONF_cmd() returns 1 if the value of B<option> is recognised and B<value> is
+B<NOT> used and 2 if both B<option> and B<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 B<cmd> is not recognised.
+A return value of -2 means B<option> is not recognised.
-A return value of -3 means B<cmd> is recognised and the command requires a
+A return value of -3 means B<option> is recognised and the command requires a
value but B<value> is NULL.
-A return code of 0 indicates that both B<cmd> and B<value> are valid but an
+A return code of 0 indicates that both B<option> and B<value> are valid but an
error occurred attempting to perform the operation: for example due to an
error in the syntax of B<value> in this case the error queue may provide
additional information.
projects / oweals / openssl.git / commitdiff