747 lines
39 KiB
HTML
Executable File
747 lines
39 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>SSL_CONF_cmd</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#supported_command_line_commands">SUPPORTED COMMAND LINE COMMANDS</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#additional_options">Additional Options</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#supported_configuration_file_commands">SUPPORTED CONFIGURATION FILE COMMANDS</a></li>
|
|
<li><a href="#supported_command_types">SUPPORTED COMMAND TYPES</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>SSL_CONF_cmd_value_type,
|
|
SSL_CONF_cmd - send configuration command</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/ssl.h></pre>
|
|
<pre>
|
|
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);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>The function <code>SSL_CONF_cmd()</code> performs configuration operation <strong>option</strong> with
|
|
optional parameter <strong>value</strong> on <strong>ctx</strong>. Its purpose is to simplify application
|
|
configuration of <strong>SSL_CTX</strong> or <strong>SSL</strong> structures by providing a common
|
|
framework for command line options or configuration files.</p>
|
|
<p><code>SSL_CONF_cmd_value_type()</code> returns the type of value that <strong>option</strong> refers to.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="supported_command_line_commands">SUPPORTED COMMAND LINE COMMANDS</a></h1>
|
|
<p>Currently supported <strong>option</strong> names for command lines (i.e. when the
|
|
flag <strong>SSL_CONF_CMDLINE</strong> is set) are listed below. Note: all <strong>option</strong> names
|
|
are case sensitive. Unless otherwise stated commands can be used by
|
|
both clients and servers and the <strong>value</strong> parameter is not used. The default
|
|
prefix for command line commands is <strong>-</strong> and that is reflected below.</p>
|
|
<dl>
|
|
<dt><strong><a name="bugs" class="item"><strong>-bugs</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Various bug workarounds are set, same as setting <strong>SSL_OP_ALL</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="no_comp" class="item"><strong>-no_comp</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Disables support for SSL/TLS compression, same as setting
|
|
<strong>SSL_OP_NO_COMPRESSION</strong>.
|
|
As of OpenSSL 1.1.0, compression is off by default.</p>
|
|
</dd>
|
|
<dt><strong><a name="comp" class="item"><strong>-comp</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Enables support for SSL/TLS compression, same as clearing
|
|
<strong>SSL_OP_NO_COMPRESSION</strong>.
|
|
This command was introduced in OpenSSL 1.1.0.
|
|
As of OpenSSL 1.1.0, compression is off by default.</p>
|
|
</dd>
|
|
<dt><strong><a name="no_ticket" class="item"><strong>-no_ticket</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Disables support for session tickets, same as setting <strong>SSL_OP_NO_TICKET</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="serverpref" class="item"><strong>-serverpref</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <strong>SSL_OP_CIPHER_SERVER_PREFERENCE</strong>. Only used by servers.</p>
|
|
</dd>
|
|
<dt><strong><a name="legacyrenegotiation" class="item"><strong>-legacyrenegotiation</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>permits the use of unsafe legacy renegotiation. Equivalent to setting
|
|
<strong>SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="no_renegotiation" class="item"><strong>-no_renegotiation</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
|
|
<strong>SSL_OP_NO_RENEGOTIATION</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="no_resumption_on_reneg" class="item"><strong>-no_resumption_on_reneg</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers.</p>
|
|
</dd>
|
|
<dt><strong><a name="legacy_server_connect_no_legacy_server_connect" class="item"><strong>-legacy_server_connect</strong>, <strong>-no_legacy_server_connect</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
|
|
clients only. Equivalent to setting or clearing <strong>SSL_OP_LEGACY_SERVER_CONNECT</strong>.
|
|
Set by default.</p>
|
|
</dd>
|
|
<dt><strong><a name="prioritize_chacha" class="item"><strong>-prioritize_chacha</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <strong>SSL_OP_PRIORITIZE_CHACHA</strong>.
|
|
Only used by servers. Requires <strong>-serverpref</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="allow_no_dhe_kex" class="item"><strong>-allow_no_dhe_kex</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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.</p>
|
|
</dd>
|
|
<dt><strong><a name="strict" class="item"><strong>-strict</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>enables strict mode protocol handling. Equivalent to setting
|
|
<strong>SSL_CERT_FLAG_TLS_STRICT</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="sigalgs_algs" class="item"><strong>-sigalgs</strong> <em>algs</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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.</p>
|
|
<p>The <strong>algs</strong> argument should be a colon separated list of signature
|
|
algorithms in order of decreasing preference of the form <strong>algorithm+hash</strong>
|
|
or <strong>signature_scheme</strong>. <strong>algorithm</strong> is one of <strong>RSA</strong>, <strong>DSA</strong> or <strong>ECDSA</strong> and
|
|
<strong>hash</strong> is a supported algorithm OID short name such as <strong>SHA1</strong>, <strong>SHA224</strong>,
|
|
<strong>SHA256</strong>, <strong>SHA384</strong> of <strong>SHA512</strong>. Note: algorithm and hash names are case
|
|
sensitive. <strong>signature_scheme</strong> is one of the signature schemes defined in
|
|
TLSv1.3, specified using the IETF name, e.g., <strong>ecdsa_secp256r1_sha256</strong>,
|
|
<strong>ed25519</strong>, or <strong>rsa_pss_pss_sha256</strong>.</p>
|
|
<p>If this option is not set then all signature algorithms supported by the
|
|
OpenSSL library are permissible.</p>
|
|
<p>Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
|
|
using <strong>RSA</strong> as the <strong>algorithm</strong> or by using one of the <strong>rsa_pkcs1_*</strong>
|
|
identifiers) are ignored in TLSv1.3 and will not be negotiated.</p>
|
|
</dd>
|
|
<dt><strong><a name="client_sigalgs_algs" class="item"><strong>-client_sigalgs</strong> <em>algs</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the supported signature algorithms associated with client
|
|
authentication for TLSv1.2 and TLSv1.3. For servers the <strong>algs</strong> is used
|
|
in the <strong>signature_algorithms</strong> field of a <strong>CertificateRequest</strong> 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.</p>
|
|
<p>The syntax of <strong>algs</strong> is identical to <strong>-sigalgs</strong>. If not set, then the
|
|
value set for <strong>-sigalgs</strong> will be used instead.</p>
|
|
</dd>
|
|
<dt><strong><a name="groups_groups" class="item"><strong>-groups</strong> <em>groups</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <strong>key_share</strong> sent by a client in a TLSv1.3 <strong>ClientHello</strong>.</p>
|
|
<p>The <strong>groups</strong> argument is a colon separated list of groups. The group can
|
|
be either the <strong>NIST</strong> name (e.g. <strong>P-256</strong>), some other commonly used name
|
|
where applicable (e.g. <strong>X25519</strong>, <strong>ffdhe2048</strong>) or an OpenSSL OID name
|
|
(e.g <strong>prime256v1</strong>). Group names are case sensitive. The list should be
|
|
in order of preference with the most preferred group first.</p>
|
|
<p>Currently supported groups for <strong>TLSv1.3</strong> are <strong>P-256</strong>, <strong>P-384</strong>, <strong>P-521</strong>,
|
|
<strong>X25519</strong>, <strong>X448</strong>, <strong>ffdhe2048</strong>, <strong>ffdhe3072</strong>, <strong>ffdhe4096</strong>, <strong>ffdhe6144</strong>,
|
|
<strong>ffdhe8192</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="curves_groups" class="item"><strong>-curves</strong> <em>groups</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This is a synonym for the <strong>-groups</strong> command.</p>
|
|
</dd>
|
|
<dt><strong><a name="named_curve_curve" class="item"><strong>-named_curve</strong> <em>curve</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the temporary curve used for ephemeral ECDH modes. Only used
|
|
by servers.</p>
|
|
<p>The <strong>groups</strong> argument is a curve name or the special value <strong>auto</strong> which
|
|
picks an appropriate curve based on client and server preferences. The
|
|
curve can be either the <strong>NIST</strong> name (e.g. <strong>P-256</strong>) or an OpenSSL OID name
|
|
(e.g <strong>prime256v1</strong>). Curve names are case sensitive.</p>
|
|
</dd>
|
|
<dt><strong><a name="cipher_ciphers" class="item"><strong>-cipher</strong> <em>ciphers</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Sets the TLSv1.2 and below ciphersuite list to <strong>ciphers</strong>. This list will be
|
|
combined with any configured TLSv1.3 ciphersuites. Note: syntax checking
|
|
of <strong>ciphers</strong> is currently not performed unless a <strong>SSL</strong> or <strong>SSL_CTX</strong>
|
|
structure is associated with <strong>ctx</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="ciphersuites_1_3ciphers" class="item"><strong>-ciphersuites</strong> <em>1.3ciphers</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <em>openssl-ciphers(1)</em> for more information.</p>
|
|
</dd>
|
|
<dt><strong><a name="min_protocol_minprot_max_protocol_maxprot" class="item"><strong>-min_protocol</strong> <em>minprot</em>, <strong>-max_protocol</strong> <em>maxprot</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Sets the minimum and maximum supported protocol. Currently supported
|
|
protocol values are <strong>SSLv3</strong>, <strong>TLSv1</strong>, <strong>TLSv1.1</strong>, <strong>TLSv1.2</strong>, <strong>TLSv1.3</strong>
|
|
for TLS and <strong>DTLSv1</strong>, <strong>DTLSv1.2</strong> for DTLS, and <strong>None</strong> 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.</p>
|
|
</dd>
|
|
<dt><strong><a name="record_padding_padding" class="item"><strong>-record_padding</strong> <em>padding</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to pad TLSv1.3 records so that they are a multiple of <strong>padding</strong>
|
|
in length on send. A <strong>padding</strong> of 0 or 1 turns off padding. Otherwise,
|
|
the <strong>padding</strong> must be >1 or <=16384.</p>
|
|
</dd>
|
|
<dt><strong><a name="debug_broken_protocol" class="item"><strong>-debug_broken_protocol</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Ignored.</p>
|
|
</dd>
|
|
<dt><strong><a name="no_middlebox" class="item"><strong>-no_middlebox</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Turn off "middlebox compatibility", as described below.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="additional_options">Additional Options</a></h2>
|
|
<p>The following options are accepted by <code>SSL_CONF_cmd()</code>, but are not
|
|
processed by the OpenSSL commands.</p>
|
|
<dl>
|
|
<dt><strong><a name="cert_file" class="item"><strong>-cert</strong> <em>file</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to use <strong>file</strong> as the certificate for the appropriate context. It
|
|
currently uses <code>SSL_CTX_use_certificate_chain_file()</code> if an <strong>SSL_CTX</strong>
|
|
structure is set or <code>SSL_use_certificate_file()</code> with filetype PEM if an
|
|
<strong>SSL</strong> structure is set. This option is only supported if certificate
|
|
operations are permitted.</p>
|
|
</dd>
|
|
<dt><strong><a name="key_file" class="item"><strong>-key</strong> <em>file</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to use <strong>file</strong> as the private key for the appropriate context. This
|
|
option is only supported if certificate operations are permitted. Note:
|
|
if no <strong>-key</strong> option is set then a private key is not loaded unless the
|
|
flag <strong>SSL_CONF_FLAG_REQUIRE_PRIVATE</strong> is set.</p>
|
|
</dd>
|
|
<dt><strong><a name="dhparam_file" class="item"><strong>-dhparam</strong> <em>file</em></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to use <strong>file</strong> as the set of temporary DH parameters for
|
|
the appropriate context. This option is only supported if certificate
|
|
operations are permitted.</p>
|
|
</dd>
|
|
<dt><strong><a name="no_ssl3_no_tls1_no_tls1_1_no_tls1_2_no_tls1_3" class="item"><strong>-no_ssl3</strong>, <strong>-no_tls1</strong>, <strong>-no_tls1_1</strong>, <strong>-no_tls1_2</strong>, <strong>-no_tls1_3</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Disables protocol support for SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3 by
|
|
setting the corresponding options <strong>SSL_OP_NO_SSLv3</strong>, <strong>SSL_OP_NO_TLSv1</strong>,
|
|
<strong>SSL_OP_NO_TLSv1_1</strong>, <strong>SSL_OP_NO_TLSv1_2</strong> and <strong>SSL_OP_NO_TLSv1_3</strong>
|
|
respectively. These options are deprecated, use <strong>-min_protocol</strong> and
|
|
<strong>-max_protocol</strong> instead.</p>
|
|
</dd>
|
|
<dt><strong><a name="anti_replay_no_anti_replay" class="item"><strong>-anti_replay</strong>, <strong>-no_anti_replay</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Switches replay protection, on or off respectively. With replay protection on,
|
|
OpenSSL will automatically detect if a session ticket has been used more than
|
|
once, TLSv1.3 has been negotiated, and early data is enabled on the server. A
|
|
full handshake is forced if a session ticket is used a second or subsequent
|
|
time. Anti-Replay is on by default unless overridden by a configuration file and
|
|
is only used by servers. Anti-replay measures are required for compliance with
|
|
the TLSv1.3 specification. Some applications may be able to mitigate the replay
|
|
risks in other ways and in such cases the built-in OpenSSL functionality is not
|
|
required. Switching off anti-replay is equivalent to <strong>SSL_OP_NO_ANTI_REPLAY</strong>.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="supported_configuration_file_commands">SUPPORTED CONFIGURATION FILE COMMANDS</a></h1>
|
|
<p>Currently supported <strong>option</strong> names for configuration files (i.e., when the
|
|
flag <strong>SSL_CONF_FLAG_FILE</strong> is set) are listed below. All configuration file
|
|
<strong>option</strong> names are case insensitive so <strong>signaturealgorithms</strong> is recognised
|
|
as well as <strong>SignatureAlgorithms</strong>. Unless otherwise stated the <strong>value</strong> names
|
|
are also case insensitive.</p>
|
|
<p>Note: the command prefix (if set) alters the recognised <strong>option</strong> values.</p>
|
|
<dl>
|
|
<dt><strong><a name="cipherstring" class="item"><strong>CipherString</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Sets the ciphersuite list for TLSv1.2 and below to <strong>value</strong>. This list will be
|
|
combined with any configured TLSv1.3 ciphersuites. Note: syntax
|
|
checking of <strong>value</strong> is currently not performed unless an <strong>SSL</strong> or <strong>SSL_CTX</strong>
|
|
structure is associated with <strong>ctx</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="ciphersuites" class="item"><strong>Ciphersuites</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Sets the available ciphersuites for TLSv1.3 to <strong>value</strong>. 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 <em>openssl-ciphers(1)</em> for more information.</p>
|
|
</dd>
|
|
<dt><strong><a name="certificate" class="item"><strong>Certificate</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to use the file <strong>value</strong> as the certificate for the appropriate
|
|
context. It currently uses <code>SSL_CTX_use_certificate_chain_file()</code> if an <strong>SSL_CTX</strong>
|
|
structure is set or <code>SSL_use_certificate_file()</code> with filetype PEM if an <strong>SSL</strong>
|
|
structure is set. This option is only supported if certificate operations
|
|
are permitted.</p>
|
|
</dd>
|
|
<dt><strong><a name="privatekey" class="item"><strong>PrivateKey</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to use the file <strong>value</strong> as the private key for the appropriate
|
|
context. This option is only supported if certificate operations
|
|
are permitted. Note: if no <strong>PrivateKey</strong> option is set then a private key is
|
|
not loaded unless the <strong>SSL_CONF_FLAG_REQUIRE_PRIVATE</strong> is set.</p>
|
|
</dd>
|
|
<dt><strong><a name="chaincafile_chaincapath_verifycafile_verifycapath" class="item"><strong>ChainCAFile</strong>, <strong>ChainCAPath</strong>, <strong>VerifyCAFile</strong>, <strong>VerifyCAPath</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>These options indicate a file or directory used for building certificate
|
|
chains or verifying certificate chains. These options are only supported
|
|
if certificate operations are permitted.</p>
|
|
</dd>
|
|
<dt><strong><a name="requestcafile" class="item"><strong>RequestCAFile</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This option indicates a file containing a set of certificates in PEM form.
|
|
The subject names of the certificates are sent to the peer in the
|
|
<strong>certificate_authorities</strong> extension for TLS 1.3 (in ClientHello or
|
|
CertificateRequest) or in a certificate request for previous versions or
|
|
TLS.</p>
|
|
</dd>
|
|
<dt><strong><a name="serverinfofile" class="item"><strong>ServerInfoFile</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to use the file <strong>value</strong> in the "serverinfo" extension using the
|
|
function SSL_CTX_use_serverinfo_file.</p>
|
|
</dd>
|
|
<dt><strong><a name="dhparameters" class="item"><strong>DHParameters</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to use the file <strong>value</strong> as the set of temporary DH parameters for
|
|
the appropriate context. This option is only supported if certificate
|
|
operations are permitted.</p>
|
|
</dd>
|
|
<dt><strong><a name="recordpadding" class="item"><strong>RecordPadding</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Attempts to pad TLSv1.3 records so that they are a multiple of <strong>value</strong> in
|
|
length on send. A <strong>value</strong> of 0 or 1 turns off padding. Otherwise, the
|
|
<strong>value</strong> must be >1 or <=16384.</p>
|
|
</dd>
|
|
<dt><strong><a name="signaturealgorithms" class="item"><strong>SignatureAlgorithms</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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.</p>
|
|
<p>The <strong>value</strong> argument should be a colon separated list of signature algorithms
|
|
in order of decreasing preference of the form <strong>algorithm+hash</strong> or
|
|
<strong>signature_scheme</strong>. <strong>algorithm</strong>
|
|
is one of <strong>RSA</strong>, <strong>DSA</strong> or <strong>ECDSA</strong> and <strong>hash</strong> is a supported algorithm
|
|
OID short name such as <strong>SHA1</strong>, <strong>SHA224</strong>, <strong>SHA256</strong>, <strong>SHA384</strong> of <strong>SHA512</strong>.
|
|
Note: algorithm and hash names are case sensitive.
|
|
<strong>signature_scheme</strong> is one of the signature schemes defined in TLSv1.3,
|
|
specified using the IETF name, e.g., <strong>ecdsa_secp256r1_sha256</strong>, <strong>ed25519</strong>,
|
|
or <strong>rsa_pss_pss_sha256</strong>.</p>
|
|
<p>If this option is not set then all signature algorithms supported by the
|
|
OpenSSL library are permissible.</p>
|
|
<p>Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
|
|
using <strong>RSA</strong> as the <strong>algorithm</strong> or by using one of the <strong>rsa_pkcs1_*</strong>
|
|
identifiers) are ignored in TLSv1.3 and will not be negotiated.</p>
|
|
</dd>
|
|
<dt><strong><a name="clientsignaturealgorithms" class="item"><strong>ClientSignatureAlgorithms</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the supported signature algorithms associated with client
|
|
authentication for TLSv1.2 and TLSv1.3.
|
|
For servers the value is used in the
|
|
<strong>signature_algorithms</strong> field of a <strong>CertificateRequest</strong> 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.</p>
|
|
<p>The syntax of <strong>value</strong> is identical to <strong>SignatureAlgorithms</strong>. If not set then
|
|
the value set for <strong>SignatureAlgorithms</strong> will be used instead.</p>
|
|
</dd>
|
|
<dt><strong><a name="groups" class="item"><strong>Groups</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <strong>key_share</strong> sent by a client in a TLSv1.3
|
|
<strong>ClientHello</strong>.</p>
|
|
<p>The <strong>value</strong> argument is a colon separated list of groups. The group can be
|
|
either the <strong>NIST</strong> name (e.g. <strong>P-256</strong>), some other commonly used name where
|
|
applicable (e.g. <strong>X25519</strong>, <strong>ffdhe2048</strong>) or an OpenSSL OID name
|
|
(e.g <strong>prime256v1</strong>). Group names are case sensitive. The list should be in
|
|
order of preference with the most preferred group first.</p>
|
|
<p>Currently supported groups for <strong>TLSv1.3</strong> are <strong>P-256</strong>, <strong>P-384</strong>, <strong>P-521</strong>,
|
|
<strong>X25519</strong>, <strong>X448</strong>, <strong>ffdhe2048</strong>, <strong>ffdhe3072</strong>, <strong>ffdhe4096</strong>, <strong>ffdhe6144</strong>,
|
|
<strong>ffdhe8192</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="curves" class="item"><strong>Curves</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This is a synonym for the "Groups" command.</p>
|
|
</dd>
|
|
<dt><strong><a name="minprotocol" class="item"><strong>MinProtocol</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the minimum supported SSL, TLS or DTLS version.</p>
|
|
<p>Currently supported protocol values are <strong>SSLv3</strong>, <strong>TLSv1</strong>, <strong>TLSv1.1</strong>,
|
|
<strong>TLSv1.2</strong>, <strong>TLSv1.3</strong>, <strong>DTLSv1</strong> and <strong>DTLSv1.2</strong>.
|
|
The value <strong>None</strong> will disable the limit.</p>
|
|
</dd>
|
|
<dt><strong><a name="maxprotocol" class="item"><strong>MaxProtocol</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the maximum supported SSL, TLS or DTLS version.</p>
|
|
<p>Currently supported protocol values are <strong>SSLv3</strong>, <strong>TLSv1</strong>, <strong>TLSv1.1</strong>,
|
|
<strong>TLSv1.2</strong>, <strong>TLSv1.3</strong>, <strong>DTLSv1</strong> and <strong>DTLSv1.2</strong>.
|
|
The value <strong>None</strong> will disable the limit.</p>
|
|
</dd>
|
|
<dt><strong><a name="protocol" class="item"><strong>Protocol</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This can be used to enable or disable certain versions of the SSL,
|
|
TLS or DTLS protocol.</p>
|
|
<p>The <strong>value</strong> argument is a comma separated list of supported protocols
|
|
to enable or disable.
|
|
If a protocol is preceded by <strong>-</strong> that version is disabled.</p>
|
|
<p>All protocol versions are enabled by default.
|
|
You need to disable at least one protocol version for this setting have any
|
|
effect.
|
|
Only enabling some protocol versions does not disable the other protocol
|
|
versions.</p>
|
|
<p>Currently supported protocol values are <strong>SSLv3</strong>, <strong>TLSv1</strong>, <strong>TLSv1.1</strong>,
|
|
<strong>TLSv1.2</strong>, <strong>TLSv1.3</strong>, <strong>DTLSv1</strong> and <strong>DTLSv1.2</strong>.
|
|
The special value <strong>ALL</strong> refers to all supported versions.</p>
|
|
<p>This can't enable protocols that are disabled using <strong>MinProtocol</strong>
|
|
or <strong>MaxProtocol</strong>, but can disable protocols that are still allowed
|
|
by them.</p>
|
|
<p>The <strong>Protocol</strong> command is fragile and deprecated; do not use it.
|
|
Use <strong>MinProtocol</strong> and <strong>MaxProtocol</strong> instead.
|
|
If you do use <strong>Protocol</strong>, make sure that the resulting range of enabled
|
|
protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make
|
|
sure to also leave TLS 1.1 enabled.</p>
|
|
</dd>
|
|
<dt><strong><a name="options" class="item"><strong>Options</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The <strong>value</strong> argument is a comma separated list of various flags to set.
|
|
If a flag string is preceded <strong>-</strong> it is disabled.
|
|
See the <em>SSL_CTX_set_options(3)</em> function for more details of
|
|
individual options.</p>
|
|
<p>Each option is listed below. Where an operation is enabled by default
|
|
the <strong>-flag</strong> syntax is needed to disable it.</p>
|
|
<p><strong>SessionTicket</strong>: session ticket support, enabled by default. Inverse of
|
|
<strong>SSL_OP_NO_TICKET</strong>: that is <strong>-SessionTicket</strong> is the same as setting
|
|
<strong>SSL_OP_NO_TICKET</strong>.</p>
|
|
<p><strong>Compression</strong>: SSL/TLS compression support, enabled by default. Inverse
|
|
of <strong>SSL_OP_NO_COMPRESSION</strong>.</p>
|
|
<p><strong>EmptyFragments</strong>: 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 <strong>SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS</strong>.</p>
|
|
<p><strong>Bugs</strong>: enable various bug workarounds. Same as <strong>SSL_OP_ALL</strong>.</p>
|
|
<p><strong>DHSingle</strong>: enable single use DH keys, set by default. Inverse of
|
|
<strong>SSL_OP_DH_SINGLE</strong>. Only used by servers.</p>
|
|
<p><strong>ECDHSingle</strong>: enable single use ECDH keys, set by default. Inverse of
|
|
<strong>SSL_OP_ECDH_SINGLE</strong>. Only used by servers.</p>
|
|
<p><strong>ServerPreference</strong>: 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
|
|
<strong>SSL_OP_CIPHER_SERVER_PREFERENCE</strong>. Only used by servers.</p>
|
|
<p><strong>PrioritizeChaCha</strong>: prioritizes ChaCha ciphers when the client has a
|
|
ChaCha20 cipher at the top of its preference list. This usually indicates
|
|
a mobile client is in use. Equivalent to <strong>SSL_OP_PRIORITIZE_CHACHA</strong>.
|
|
Only used by servers.</p>
|
|
<p><strong>NoResumptionOnRenegotiation</strong>: set
|
|
<strong>SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION</strong> flag. Only used by servers.</p>
|
|
<p><strong>NoRenegotiation</strong>: disables all attempts at renegotiation in TLSv1.2 and
|
|
earlier, same as setting <strong>SSL_OP_NO_RENEGOTIATION</strong>.</p>
|
|
<p><strong>UnsafeLegacyRenegotiation</strong>: permits the use of unsafe legacy renegotiation.
|
|
Equivalent to <strong>SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION</strong>.</p>
|
|
<p><strong>UnsafeLegacyServerConnect</strong>: permits the use of unsafe legacy renegotiation
|
|
for OpenSSL clients only. Equivalent to <strong>SSL_OP_LEGACY_SERVER_CONNECT</strong>.
|
|
Set by default.</p>
|
|
<p><strong>EncryptThenMac</strong>: use encrypt-then-mac extension, enabled by
|
|
default. Inverse of <strong>SSL_OP_NO_ENCRYPT_THEN_MAC</strong>: that is,
|
|
<strong>-EncryptThenMac</strong> is the same as setting <strong>SSL_OP_NO_ENCRYPT_THEN_MAC</strong>.</p>
|
|
<p><strong>AllowNoDHEKEX</strong>: 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. Equivalent to <strong>SSL_OP_ALLOW_NO_DHE_KEX</strong>.</p>
|
|
<p><strong>MiddleboxCompat</strong>: If set then dummy Change Cipher Spec (CCS) messages are sent
|
|
in TLSv1.3. This has the effect of making TLSv1.3 look more like TLSv1.2 so that
|
|
middleboxes that do not understand TLSv1.3 will not drop the connection. This
|
|
option is set by default. A future version of OpenSSL may not set this by
|
|
default. Equivalent to <strong>SSL_OP_ENABLE_MIDDLEBOX_COMPAT</strong>.</p>
|
|
<p><strong>AntiReplay</strong>: If set then OpenSSL will automatically detect if a session ticket
|
|
has been used more than once, TLSv1.3 has been negotiated, and early data is
|
|
enabled on the server. A full handshake is forced if a session ticket is used a
|
|
second or subsequent time. This option is set by default and is only used by
|
|
servers. Anti-replay measures are required to comply with the TLSv1.3
|
|
specification. Some applications may be able to mitigate the replay risks in
|
|
other ways and in such cases the built-in OpenSSL functionality is not required.
|
|
Disabling anti-replay is equivalent to setting <strong>SSL_OP_NO_ANTI_REPLAY</strong>.</p>
|
|
<p><strong>ExtendedMasterSecret</strong>: use extended master secret extension, enabled by
|
|
default. Inverse of <strong>SSL_OP_NO_EXTENDED_MASTER_SECRET</strong>: that is,
|
|
<strong>-ExtendedMasterSecret</strong> is the same as setting <strong>SSL_OP_NO_EXTENDED_MASTER_SECRET</strong>.</p>
|
|
</dd>
|
|
<dt><strong><a name="verifymode" class="item"><strong>VerifyMode</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The <strong>value</strong> argument is a comma separated list of flags to set.</p>
|
|
<p><strong>Peer</strong> enables peer verification: for clients only.</p>
|
|
<p><strong>Request</strong> requests but does not require a certificate from the client.
|
|
Servers only.</p>
|
|
<p><strong>Require</strong> requests and requires a certificate from the client: an error
|
|
occurs if the client does not present a certificate. Servers only.</p>
|
|
<p><strong>Once</strong> requests a certificate from a client only on the initial connection:
|
|
not when renegotiating. Servers only.</p>
|
|
<p><strong>RequestPostHandshake</strong> configures the connection to support requests but does
|
|
not require a certificate from the client post-handshake. A certificate will
|
|
not be requested during the initial handshake. The server application must
|
|
provide a mechanism to request a certificate post-handshake. Servers only.
|
|
TLSv1.3 only.</p>
|
|
<p><strong>RequiresPostHandshake</strong> configures the connection to support requests and
|
|
requires a certificate from the client post-handshake: an error occurs if the
|
|
client does not present a certificate. A certificate will not be requested
|
|
during the initial handshake. The server application must provide a mechanism
|
|
to request a certificate post-handshake. Servers only. TLSv1.3 only.</p>
|
|
</dd>
|
|
<dt><strong><a name="clientcafile_clientcapath" class="item"><strong>ClientCAFile</strong>, <strong>ClientCAPath</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>A file or directory of certificates in PEM format whose names are used as the
|
|
set of acceptable names for client CAs. Servers only. This option is only
|
|
supported if certificate operations are permitted.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="supported_command_types">SUPPORTED COMMAND TYPES</a></h1>
|
|
<p>The function <code>SSL_CONF_cmd_value_type()</code> currently returns one of the following
|
|
types:</p>
|
|
<dl>
|
|
<dt><strong><a name="ssl_conf_type_unknown" class="item"><strong>SSL_CONF_TYPE_UNKNOWN</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The <strong>option</strong> string is unrecognised, this return value can be use to flag
|
|
syntax errors.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_conf_type_string" class="item"><strong>SSL_CONF_TYPE_STRING</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The value is a string without any specific structure.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_conf_type_file" class="item"><strong>SSL_CONF_TYPE_FILE</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The value is a filename.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_conf_type_dir" class="item"><strong>SSL_CONF_TYPE_DIR</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The value is a directory name.</p>
|
|
</dd>
|
|
<dt><strong><a name="ssl_conf_type_none" class="item"><strong>SSL_CONF_TYPE_NONE</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The value string is not used e.g. a command line option which doesn't take an
|
|
argument.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>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:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
|
|
SSL_CONF_cmd(ctx, userparam, uservalue);</pre>
|
|
<p>it will disable SSLv3 support by default but the user can override it. If
|
|
however the call sequence is:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, userparam, uservalue);
|
|
SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");</pre>
|
|
<p>SSLv3 is <strong>always</strong> disabled and attempt to override this by the user are
|
|
ignored.</p>
|
|
<p>By checking the return code of <code>SSL_CONF_cmd()</code> it is possible to query if a
|
|
given <strong>option</strong> is recognised, this is useful if <code>SSL_CONF_cmd()</code> values are
|
|
mixed with additional application specific operations.</p>
|
|
<p>For example an application might call <code>SSL_CONF_cmd()</code> and if it returns
|
|
-2 (unrecognised command) continue with processing of application specific
|
|
commands.</p>
|
|
<p>Applications can also use <code>SSL_CONF_cmd()</code> to process command lines though the
|
|
utility function <code>SSL_CONF_cmd_argv()</code> 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 <strong>option</strong> and the
|
|
following argument to <strong>value</strong> (which may be NULL).</p>
|
|
<p>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 <code>SSL_CONF_cmd()</code>. If -2 is
|
|
returned then <strong>option</strong> 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.</p>
|
|
<p>The function <code>SSL_CONF_cmd_value_type()</code> 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 <strong>SSL_CONF_TYPE_FILE</strong> an application could translate a relative
|
|
pathname to an absolute pathname.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>SSL_CONF_cmd()</code> returns 1 if the value of <strong>option</strong> is recognised and <strong>value</strong> is
|
|
<strong>NOT</strong> used and 2 if both <strong>option</strong> and <strong>value</strong> are used. In other words it
|
|
returns the number of arguments processed. This is useful when processing
|
|
command lines.</p>
|
|
<p>A return value of -2 means <strong>option</strong> is not recognised.</p>
|
|
<p>A return value of -3 means <strong>option</strong> is recognised and the command requires a
|
|
value but <strong>value</strong> is NULL.</p>
|
|
<p>A return code of 0 indicates that both <strong>option</strong> and <strong>value</strong> are valid but an
|
|
error occurred attempting to perform the operation: for example due to an
|
|
error in the syntax of <strong>value</strong> in this case the error queue may provide
|
|
additional information.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>Set supported signature algorithms:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");</pre>
|
|
<p>There are various ways to select the supported protocols.</p>
|
|
<p>This set the minimum protocol version to TLSv1, and so disables SSLv3.
|
|
This is the recommended way to disable protocols.</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1");</pre>
|
|
<p>The following also disables SSLv3:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");</pre>
|
|
<p>The following will first enable all protocols, and then disable
|
|
SSLv3.
|
|
If no protocol versions were disabled before this has the same effect as
|
|
"-SSLv3", but if some versions were disables this will re-enable them before
|
|
disabling SSLv3.</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3");</pre>
|
|
<p>Only enable TLSv1.2:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2");
|
|
SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2");</pre>
|
|
<p>This also only enables TLSv1.2:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");</pre>
|
|
<p>Disable TLS session tickets:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "Options", "-SessionTicket");</pre>
|
|
<p>Enable compression:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "Options", "Compression");</pre>
|
|
<p>Set supported curves to P-256, P-384:</p>
|
|
<pre>
|
|
SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ssl(7)</em>,
|
|
<em>SSL_CONF_CTX_new(3)</em>,
|
|
<em>SSL_CONF_CTX_set_flags(3)</em>,
|
|
<em>SSL_CONF_CTX_set1_prefix(3)</em>,
|
|
<em>SSL_CONF_CTX_set_ssl_ctx(3)</em>,
|
|
<em>SSL_CONF_cmd_argv(3)</em>,
|
|
<em>SSL_CTX_set_options(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>The <code>SSL_CONF_cmd()</code> function was added in OpenSSL 1.0.2.</p>
|
|
<p>The <strong>SSL_OP_NO_SSL2</strong> option doesn't have effect since 1.1.0, but the macro
|
|
is retained for backwards compatibility.</p>
|
|
<p>The <strong>SSL_CONF_TYPE_NONE</strong> was added in OpenSSL 1.1.0. In earlier versions of
|
|
OpenSSL passing a command which didn't take an argument would return
|
|
<strong>SSL_CONF_TYPE_UNKNOWN</strong>.</p>
|
|
<p><strong>MinProtocol</strong> and <strong>MaxProtocol</strong> where added in OpenSSL 1.1.0.</p>
|
|
<p><strong>AllowNoDHEKEX</strong> and <strong>PrioritizeChaCha</strong> were added in OpenSSL 1.1.1.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2012-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|