| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "SSL_CONF_CMD 3SSL" |
| 58 |
.TH SSL_CONF_CMD 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
SSL_CONF_cmd_value_type, |
| 65 |
SSL_CONF_cmd \- send configuration command |
| 66 |
.SH SYNOPSIS |
| 67 |
.IX Header "SYNOPSIS" |
| 68 |
.Vb 1 |
| 69 |
\& #include <openssl/ssl.h> |
| 70 |
\& |
| 71 |
\& int SSL_CONF_cmd(SSL_CONF_CTX *ctx, const char *option, const char *value); |
| 72 |
\& int SSL_CONF_cmd_value_type(SSL_CONF_CTX *ctx, const char *option); |
| 73 |
.Ve |
| 74 |
.SH DESCRIPTION |
| 75 |
.IX Header "DESCRIPTION" |
| 76 |
The function \fBSSL_CONF_cmd()\fR performs configuration operation \fBoption\fR with |
| 77 |
optional parameter \fBvalue\fR on \fBctx\fR. Its purpose is to simplify application |
| 78 |
configuration of \fBSSL_CTX\fR or \fBSSL\fR structures by providing a common |
| 79 |
framework for command line options or configuration files. |
| 80 |
.PP |
| 81 |
\&\fBSSL_CONF_cmd_value_type()\fR returns the type of value that \fBoption\fR refers to. |
| 82 |
.SH "SUPPORTED COMMAND LINE COMMANDS" |
| 83 |
.IX Header "SUPPORTED COMMAND LINE COMMANDS" |
| 84 |
Currently supported \fBoption\fR names for command lines (i.e. when the |
| 85 |
flag \fBSSL_CONF_FLAG_CMDLINE\fR is set) are listed below. Note: all \fBoption\fR |
| 86 |
names are case sensitive. Unless otherwise stated commands can be used by |
| 87 |
both clients and servers and the \fBvalue\fR parameter is not used. The default |
| 88 |
prefix for command line commands is \fB\-\fR and that is reflected below. |
| 89 |
.IP \fB\-bugs\fR 4 |
| 90 |
.IX Item "-bugs" |
| 91 |
Various bug workarounds are set, same as setting \fBSSL_OP_ALL\fR. |
| 92 |
.IP \fB\-no_comp\fR 4 |
| 93 |
.IX Item "-no_comp" |
| 94 |
Disables support for SSL/TLS compression, same as setting |
| 95 |
\&\fBSSL_OP_NO_COMPRESSION\fR. |
| 96 |
As of OpenSSL 1.1.0, compression is off by default. |
| 97 |
.IP \fB\-comp\fR 4 |
| 98 |
.IX Item "-comp" |
| 99 |
Enables support for SSL/TLS compression, same as clearing |
| 100 |
\&\fBSSL_OP_NO_COMPRESSION\fR. |
| 101 |
This command was introduced in OpenSSL 1.1.0. |
| 102 |
As of OpenSSL 1.1.0, compression is off by default. TLS compression can only be |
| 103 |
used in security level 1 or lower. From OpenSSL 3.2.0 and above the default |
| 104 |
security level is 2, so this option will have no effect without also changing |
| 105 |
the security level. See \fBSSL_CTX_set_security_level\fR\|(3). |
| 106 |
.IP \fB\-no_ticket\fR 4 |
| 107 |
.IX Item "-no_ticket" |
| 108 |
Disables support for session tickets, same as setting \fBSSL_OP_NO_TICKET\fR. |
| 109 |
.IP \fB\-serverpref\fR 4 |
| 110 |
.IX Item "-serverpref" |
| 111 |
Use server and not client preference order when determining which cipher suite, |
| 112 |
signature algorithm or elliptic curve (TLS 1.2) or group (TLS 1.3) to use for |
| 113 |
an incoming connection. |
| 114 |
Equivalent to \fBSSL_OP_SERVER_PREFERENCE\fR. Only used by servers. |
| 115 |
.IP \fB\-client_renegotiation\fR 4 |
| 116 |
.IX Item "-client_renegotiation" |
| 117 |
Allows servers to accept client-initiated renegotiation. Equivalent to |
| 118 |
setting \fBSSL_OP_ALLOW_CLIENT_RENEGOTIATION\fR. |
| 119 |
Only used by servers. |
| 120 |
.IP \fB\-legacy_renegotiation\fR 4 |
| 121 |
.IX Item "-legacy_renegotiation" |
| 122 |
Permits the use of unsafe legacy renegotiation. Equivalent to setting |
| 123 |
\&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR. |
| 124 |
.IP \fB\-no_renegotiation\fR 4 |
| 125 |
.IX Item "-no_renegotiation" |
| 126 |
Disables all attempts at renegotiation in (D)TLSv1.2 and earlier, same as setting |
| 127 |
\&\fBSSL_OP_NO_RENEGOTIATION\fR. |
| 128 |
.IP \fB\-no_resumption_on_reneg\fR 4 |
| 129 |
.IX Item "-no_resumption_on_reneg" |
| 130 |
Sets \fBSSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\fR. Only used by servers. |
| 131 |
.IP "\fB\-legacy_server_connect\fR, \fB\-no_legacy_server_connect\fR" 4 |
| 132 |
.IX Item "-legacy_server_connect, -no_legacy_server_connect" |
| 133 |
Permits or prohibits the use of unsafe legacy renegotiation for OpenSSL |
| 134 |
clients only. Equivalent to setting or clearing \fBSSL_OP_LEGACY_SERVER_CONNECT\fR. |
| 135 |
.IP \fB\-prioritize_chacha\fR 4 |
| 136 |
.IX Item "-prioritize_chacha" |
| 137 |
Prioritize ChaCha ciphers when the client has a ChaCha20 cipher at the top of |
| 138 |
its preference list. This usually indicates a client without AES hardware |
| 139 |
acceleration (e.g. mobile) is in use. Equivalent to \fBSSL_OP_PRIORITIZE_CHACHA\fR. |
| 140 |
Only used by servers. Requires \fB\-serverpref\fR. |
| 141 |
.IP \fB\-allow_no_dhe_kex\fR 4 |
| 142 |
.IX Item "-allow_no_dhe_kex" |
| 143 |
In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on resumption. This means |
| 144 |
that there will be no forward secrecy for the resumed session. |
| 145 |
.IP \fB\-prefer_no_dhe_kex\fR 4 |
| 146 |
.IX Item "-prefer_no_dhe_kex" |
| 147 |
In TLSv1.3, on resumption let the server prefer a non\-(ec)dhe based key |
| 148 |
exchange mode over an (ec)dhe based one. Requires \fB\-allow_no_dhe_kex\fR. |
| 149 |
Equivalent to \fBSSL_OP_PREFER_NO_DHE_KEX\fR. Only used by servers. |
| 150 |
.IP \fB\-strict\fR 4 |
| 151 |
.IX Item "-strict" |
| 152 |
Enables strict mode protocol handling. Equivalent to setting |
| 153 |
\&\fBSSL_CERT_FLAG_TLS_STRICT\fR. |
| 154 |
.IP "\fB\-sigalgs\fR \fIalgs\fR" 4 |
| 155 |
.IX Item "-sigalgs algs" |
| 156 |
This sets the supported signature algorithms for TLSv1.2 and TLSv1.3. |
| 157 |
For clients this value is used directly for the supported signature |
| 158 |
algorithms extension. For servers it is used to determine which signature |
| 159 |
algorithms to support. |
| 160 |
.Sp |
| 161 |
The \fBalgs\fR argument should be a colon separated list of signature |
| 162 |
algorithms in order of decreasing preference of the form \fBalgorithm+hash\fR |
| 163 |
or \fBsignature_scheme\fR. For the default providers shipped with OpenSSL, |
| 164 |
\&\fBalgorithm\fR is one of \fBRSA\fR, \fBDSA\fR or \fBECDSA\fR and |
| 165 |
\&\fBhash\fR is a supported algorithm OID short name such as \fBSHA1\fR, \fBSHA224\fR, |
| 166 |
\&\fBSHA256\fR, \fBSHA384\fR or \fBSHA512\fR. |
| 167 |
\&\fBsignature_scheme\fR is one of the signature schemes defined |
| 168 |
in TLSv1.3, specified using the IETF name, e.g., \fBecdsa_secp256r1_sha256\fR, |
| 169 |
\&\fBed25519\fR, or \fBrsa_pss_pss_sha256\fR. Additional providers may make available |
| 170 |
further algorithms via the TLS-SIGALG capability. |
| 171 |
Signature scheme names and public key algorithm names (but not the hash names) |
| 172 |
in the \fBalgorithm+hash\fR form are case-insensitive. |
| 173 |
See \fBprovider\-base\fR\|(7). |
| 174 |
.Sp |
| 175 |
If this option is not set then all signature algorithms supported by all |
| 176 |
activated providers are permissible. |
| 177 |
.Sp |
| 178 |
Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by |
| 179 |
using \fBRSA\fR as the \fBalgorithm\fR or by using one of the \fBrsa_pkcs1_*\fR |
| 180 |
identifiers) are ignored in TLSv1.3 and will not be negotiated. |
| 181 |
.IP "\fB\-client_sigalgs\fR \fIalgs\fR" 4 |
| 182 |
.IX Item "-client_sigalgs algs" |
| 183 |
This sets the supported signature algorithms associated with client |
| 184 |
authentication for TLSv1.2 and TLSv1.3. For servers the \fBalgs\fR is used |
| 185 |
in the \fBsignature_algorithms\fR field of a \fBCertificateRequest\fR message. |
| 186 |
For clients it is used to determine which signature algorithm to use with |
| 187 |
the client certificate. If a server does not request a certificate this |
| 188 |
option has no effect. |
| 189 |
.Sp |
| 190 |
The syntax of \fBalgs\fR is identical to \fB\-sigalgs\fR. If not set, then the |
| 191 |
value set for \fB\-sigalgs\fR will be used instead. |
| 192 |
.IP "\fB\-groups\fR \fIgroups\fR" 4 |
| 193 |
.IX Item "-groups groups" |
| 194 |
This sets the supported groups. For clients, the groups are sent using |
| 195 |
the supported groups extension. For servers, it is used to determine which |
| 196 |
group to use. This setting affects groups used for signatures (in TLSv1.2 |
| 197 |
and earlier) and key exchange. |
| 198 |
.Sp |
| 199 |
In its simplest form the \fIgroups\fR argument is a colon separated list of |
| 200 |
groups. The preferred names are those listed in the IANA |
| 201 |
TLS Supported Groups <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8> |
| 202 |
registry. |
| 203 |
.Sp |
| 204 |
For some groups, OpenSSL supports additional aliases. |
| 205 |
Such an alias could be a \fBNIST\fR name (e.g. \fBP\-256\fR), an OpenSSL OID name |
| 206 |
(e.g. \fBprime256v1\fR), or some other commonly used name. |
| 207 |
Group names are case-insensitive in OpenSSL 3.5 and later. |
| 208 |
The list should be in order of preference with the most preferred group first. |
| 209 |
.Sp |
| 210 |
The first group listed will also be used for the \fBkey_share\fR sent by a client |
| 211 |
in a TLSv1.3 \fBClientHello\fR. |
| 212 |
.Sp |
| 213 |
The commands below list the IANA names for TLS 1.2 and TLS 1.3, |
| 214 |
respectively: |
| 215 |
.Sp |
| 216 |
.Vb 2 |
| 217 |
\& $ openssl list \-tls1_2 \-tls\-groups |
| 218 |
\& $ openssl list \-tls1_3 \-tls\-groups |
| 219 |
.Ve |
| 220 |
.Sp |
| 221 |
The recommended groups for TLS 1.3 are presently documented in the default |
| 222 |
TLS group list in the OpenSSL code base. Starting with OpenSSL 3.5, the |
| 223 |
hybrid algorithm \fBX25519MLKEM768\fR is first in this default list. |
| 224 |
It mitigates against threats from future quantum computers while |
| 225 |
still providing state-of-the-art classical key exchange protection. |
| 226 |
.Sp |
| 227 |
Further details regarding post-quantum algorithm considerations are documented |
| 228 |
in the HISTORY section below. |
| 229 |
.Sp |
| 230 |
An enriched alternative syntax, that enables clients to send multiple keyshares |
| 231 |
and allows servers to prioritise some groups over others, is described in |
| 232 |
\&\fBSSL_CTX_set1_groups_list\fR\|(3). |
| 233 |
Since TLS 1.2 has neither keyshares nor a hello retry mechanism, with TLS 1.2 |
| 234 |
the enriched syntax is ultimately equivalent to just a simple ordered list of |
| 235 |
groups, as with the simple form above. |
| 236 |
.IP "\fB\-curves\fR \fIgroups\fR" 4 |
| 237 |
.IX Item "-curves groups" |
| 238 |
This is a synonym for the \fB\-groups\fR command. |
| 239 |
.IP "\fB\-named_curve\fR \fIcurve\fR" 4 |
| 240 |
.IX Item "-named_curve curve" |
| 241 |
This sets the temporary curve used for ephemeral ECDH modes. |
| 242 |
This is only applicable in TLS 1.0 and 1.1, and should not be used with later |
| 243 |
protocol versions. |
| 244 |
.Sp |
| 245 |
The \fIcurve\fR argument is a curve name or the special value \fBauto\fR which |
| 246 |
picks an appropriate curve based on client and server preferences. The |
| 247 |
curve can be either the \fBNIST\fR name (e.g. \fBP\-256\fR) or an OpenSSL OID name |
| 248 |
(e.g. \fBprime256v1\fR). |
| 249 |
Even with TLS 1.0 and 1.1, the default value of \f(CW\*(C`auto\*(C'\fR is strongly recommended |
| 250 |
over choosing a specific curve. |
| 251 |
Curve names are case-insensitive in OpenSSL 3.5 and later. |
| 252 |
.IP \fB\-tx_cert_comp\fR 4 |
| 253 |
.IX Item "-tx_cert_comp" |
| 254 |
Enables support for sending TLSv1.3 compressed certificates. |
| 255 |
.IP \fB\-no_tx_cert_comp\fR 4 |
| 256 |
.IX Item "-no_tx_cert_comp" |
| 257 |
Disables support for sending TLSv1.3 compressed certificates. |
| 258 |
.IP \fB\-rx_cert_comp\fR 4 |
| 259 |
.IX Item "-rx_cert_comp" |
| 260 |
Enables support for receiving TLSv1.3 compressed certificates. |
| 261 |
.IP \fB\-no_rx_cert_comp\fR 4 |
| 262 |
.IX Item "-no_rx_cert_comp" |
| 263 |
Disables support for receiving TLSv1.3 compressed certificates. |
| 264 |
.IP \fB\-comp\fR 4 |
| 265 |
.IX Item "-comp" |
| 266 |
.PD 0 |
| 267 |
.IP "\fB\-cipher\fR \fIciphers\fR" 4 |
| 268 |
.IX Item "-cipher ciphers" |
| 269 |
.PD |
| 270 |
Sets the TLSv1.2 and below ciphersuite list to \fBciphers\fR. This list will be |
| 271 |
combined with any configured TLSv1.3 ciphersuites. Note: syntax checking |
| 272 |
of \fBciphers\fR is currently not performed unless a \fBSSL\fR or \fBSSL_CTX\fR |
| 273 |
structure is associated with \fBctx\fR. |
| 274 |
.IP "\fB\-ciphersuites\fR \fI1.3ciphers\fR" 4 |
| 275 |
.IX Item "-ciphersuites 1.3ciphers" |
| 276 |
Sets the available ciphersuites for TLSv1.3 to value. This is a |
| 277 |
colon-separated list of TLSv1.3 ciphersuite names in order of preference. This |
| 278 |
list will be combined any configured TLSv1.2 and below ciphersuites. |
| 279 |
See \fBopenssl\-ciphers\fR\|(1) for more information. |
| 280 |
.IP "\fB\-min_protocol\fR \fIminprot\fR, \fB\-max_protocol\fR \fImaxprot\fR" 4 |
| 281 |
.IX Item "-min_protocol minprot, -max_protocol maxprot" |
| 282 |
Sets the minimum and maximum supported protocol. |
| 283 |
Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR, |
| 284 |
\&\fBTLSv1.2\fR, \fBTLSv1.3\fR for TLS; \fBDTLSv1\fR, \fBDTLSv1.2\fR for DTLS, and \fBNone\fR |
| 285 |
for no limit. |
| 286 |
If either the lower or upper bound is not specified then only the other bound |
| 287 |
applies, if specified. |
| 288 |
If your application supports both TLS and DTLS you can specify any of these |
| 289 |
options twice, once with a bound for TLS and again with an appropriate bound |
| 290 |
for DTLS. |
| 291 |
To restrict the supported protocol versions use these commands rather than the |
| 292 |
deprecated alternative commands below. |
| 293 |
.IP "\fB\-record_padding\fR \fIpadding\fR" 4 |
| 294 |
.IX Item "-record_padding padding" |
| 295 |
Controls use of TLSv1.3 record layer padding. \fBpadding\fR is a string of the |
| 296 |
form "number[,number]" where the (required) first number is the padding block |
| 297 |
size (in octets) for application data, and the optional second number is the |
| 298 |
padding block size for handshake and alert messages. If the optional second |
| 299 |
number is omitted, the same padding will be applied to all messages. |
| 300 |
.Sp |
| 301 |
Padding attempts to pad TLSv1.3 records so that they are a multiple of the set |
| 302 |
length on send. A value of 0 or 1 turns off padding as relevant. Otherwise, the |
| 303 |
values must be >1 or <=16384. |
| 304 |
.IP \fB\-debug_broken_protocol\fR 4 |
| 305 |
.IX Item "-debug_broken_protocol" |
| 306 |
Ignored. |
| 307 |
.IP \fB\-no_middlebox\fR 4 |
| 308 |
.IX Item "-no_middlebox" |
| 309 |
Turn off "middlebox compatibility", as described below. |
| 310 |
.SS "Additional Options" |
| 311 |
.IX Subsection "Additional Options" |
| 312 |
The following options are accepted by \fBSSL_CONF_cmd()\fR, but are not |
| 313 |
processed by the OpenSSL commands. |
| 314 |
.IP "\fB\-cert\fR \fIfile\fR" 4 |
| 315 |
.IX Item "-cert file" |
| 316 |
Attempts to use \fBfile\fR as the certificate for the appropriate context. It |
| 317 |
currently uses \fBSSL_CTX_use_certificate_chain_file()\fR if an \fBSSL_CTX\fR |
| 318 |
structure is set or \fBSSL_use_certificate_file()\fR with filetype PEM if an |
| 319 |
\&\fBSSL\fR structure is set. This option is only supported if certificate |
| 320 |
operations are permitted. |
| 321 |
.IP "\fB\-key\fR \fIfile\fR" 4 |
| 322 |
.IX Item "-key file" |
| 323 |
Attempts to use \fBfile\fR as the private key for the appropriate context. This |
| 324 |
option is only supported if certificate operations are permitted. Note: |
| 325 |
if no \fB\-key\fR option is set then a private key is not loaded unless the |
| 326 |
flag \fBSSL_CONF_FLAG_REQUIRE_PRIVATE\fR is set. |
| 327 |
.IP "\fB\-dhparam\fR \fIfile\fR" 4 |
| 328 |
.IX Item "-dhparam file" |
| 329 |
Attempts to use \fBfile\fR as the set of temporary DH parameters for |
| 330 |
the appropriate context. This option is only supported if certificate |
| 331 |
operations are permitted. |
| 332 |
.IP "\fB\-no_ssl3\fR, \fB\-no_tls1\fR, \fB\-no_tls1_1\fR, \fB\-no_tls1_2\fR, \fB\-no_tls1_3\fR" 4 |
| 333 |
.IX Item "-no_ssl3, -no_tls1, -no_tls1_1, -no_tls1_2, -no_tls1_3" |
| 334 |
Disables protocol support for SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3 by |
| 335 |
setting the corresponding options \fBSSL_OP_NO_SSLv3\fR, \fBSSL_OP_NO_TLSv1\fR, |
| 336 |
\&\fBSSL_OP_NO_TLSv1_1\fR, \fBSSL_OP_NO_TLSv1_2\fR and \fBSSL_OP_NO_TLSv1_3\fR |
| 337 |
respectively. These options are deprecated, use \fB\-min_protocol\fR and |
| 338 |
\&\fB\-max_protocol\fR instead. |
| 339 |
.IP "\fB\-anti_replay\fR, \fB\-no_anti_replay\fR" 4 |
| 340 |
.IX Item "-anti_replay, -no_anti_replay" |
| 341 |
Switches replay protection, on or off respectively. With replay protection on, |
| 342 |
OpenSSL will automatically detect if a session ticket has been used more than |
| 343 |
once, TLSv1.3 has been negotiated, and early data is enabled on the server. A |
| 344 |
full handshake is forced if a session ticket is used a second or subsequent |
| 345 |
time. Anti-Replay is on by default unless overridden by a configuration file and |
| 346 |
is only used by servers. Anti-replay measures are required for compliance with |
| 347 |
the TLSv1.3 specification. Some applications may be able to mitigate the replay |
| 348 |
risks in other ways and in such cases the built-in OpenSSL functionality is not |
| 349 |
required. Switching off anti-replay is equivalent to \fBSSL_OP_NO_ANTI_REPLAY\fR. |
| 350 |
.SH "SUPPORTED CONFIGURATION FILE COMMANDS" |
| 351 |
.IX Header "SUPPORTED CONFIGURATION FILE COMMANDS" |
| 352 |
Currently supported \fBoption\fR names for configuration files (i.e., when the |
| 353 |
flag \fBSSL_CONF_FLAG_FILE\fR is set) are listed below. All configuration file |
| 354 |
\&\fBoption\fR names are case insensitive so \fBsignaturealgorithms\fR is recognised |
| 355 |
as well as \fBSignatureAlgorithms\fR. Unless otherwise stated the \fBvalue\fR names |
| 356 |
are also case insensitive. |
| 357 |
.PP |
| 358 |
Note: the command prefix (if set) alters the recognised \fBoption\fR values. |
| 359 |
.IP \fBCipherString\fR 4 |
| 360 |
.IX Item "CipherString" |
| 361 |
Sets the ciphersuite list for TLSv1.2 and below to \fBvalue\fR. This list will be |
| 362 |
combined with any configured TLSv1.3 ciphersuites. Note: syntax |
| 363 |
checking of \fBvalue\fR is currently not performed unless an \fBSSL\fR or \fBSSL_CTX\fR |
| 364 |
structure is associated with \fBctx\fR. |
| 365 |
.IP \fBCiphersuites\fR 4 |
| 366 |
.IX Item "Ciphersuites" |
| 367 |
Sets the available ciphersuites for TLSv1.3 to \fBvalue\fR. This is a |
| 368 |
colon-separated list of TLSv1.3 ciphersuite names in order of preference. This |
| 369 |
list will be combined any configured TLSv1.2 and below ciphersuites. |
| 370 |
See \fBopenssl\-ciphers\fR\|(1) for more information. |
| 371 |
.IP \fBCertificate\fR 4 |
| 372 |
.IX Item "Certificate" |
| 373 |
Attempts to use the file \fBvalue\fR as the certificate for the appropriate |
| 374 |
context. It currently uses \fBSSL_CTX_use_certificate_chain_file()\fR if an \fBSSL_CTX\fR |
| 375 |
structure is set or \fBSSL_use_certificate_file()\fR with filetype PEM if an \fBSSL\fR |
| 376 |
structure is set. This option is only supported if certificate operations |
| 377 |
are permitted. |
| 378 |
.IP \fBPrivateKey\fR 4 |
| 379 |
.IX Item "PrivateKey" |
| 380 |
Attempts to use the file \fBvalue\fR as the private key for the appropriate |
| 381 |
context. This option is only supported if certificate operations |
| 382 |
are permitted. Note: if no \fBPrivateKey\fR option is set then a private key is |
| 383 |
not loaded unless the \fBSSL_CONF_FLAG_REQUIRE_PRIVATE\fR is set. |
| 384 |
.IP "\fBChainCAFile\fR, \fBChainCAPath\fR, \fBVerifyCAFile\fR, \fBVerifyCAPath\fR" 4 |
| 385 |
.IX Item "ChainCAFile, ChainCAPath, VerifyCAFile, VerifyCAPath" |
| 386 |
These options indicate a file or directory used for building certificate |
| 387 |
chains or verifying certificate chains. These options are only supported |
| 388 |
if certificate operations are permitted. |
| 389 |
.IP \fBRequestCAFile\fR 4 |
| 390 |
.IX Item "RequestCAFile" |
| 391 |
This option indicates a file containing a set of certificates in PEM form. |
| 392 |
The subject names of the certificates are sent to the peer in the |
| 393 |
\&\fBcertificate_authorities\fR extension for TLS 1.3 (in ClientHello or |
| 394 |
CertificateRequest) or in a certificate request for previous versions or |
| 395 |
TLS. |
| 396 |
.IP \fBServerInfoFile\fR 4 |
| 397 |
.IX Item "ServerInfoFile" |
| 398 |
Attempts to use the file \fBvalue\fR in the "serverinfo" extension using the |
| 399 |
function SSL_CTX_use_serverinfo_file. |
| 400 |
.IP \fBDHParameters\fR 4 |
| 401 |
.IX Item "DHParameters" |
| 402 |
Attempts to use the file \fBvalue\fR as the set of temporary DH parameters for |
| 403 |
the appropriate context. This option is only supported if certificate |
| 404 |
operations are permitted. |
| 405 |
.IP \fBRecordPadding\fR 4 |
| 406 |
.IX Item "RecordPadding" |
| 407 |
Controls use of TLSv1.3 record layer padding. \fBvalue\fR is a string of the form |
| 408 |
"number[,number]" where the (required) first number is the padding block size |
| 409 |
(in octets) for application data, and the optional second number is the padding |
| 410 |
block size for handshake and alert messages. If the optional second number is |
| 411 |
omitted, the same padding will be applied to all messages. |
| 412 |
.Sp |
| 413 |
Padding attempts to pad TLSv1.3 records so that they are a multiple of the set |
| 414 |
length on send. A value of 0 or 1 turns off padding as relevant. Otherwise, the |
| 415 |
values must be >1 or <=16384. |
| 416 |
.Sp |
| 417 |
Note that, for QUIC objects, padding is always performed at the |
| 418 |
packet level, and so cannot be done at the record level. Given that, when the |
| 419 |
config file is created, there is no knowledge of what kind of SSL objects are |
| 420 |
being created, this option is silently ignored for QUIC objects. |
| 421 |
.IP \fBSignatureAlgorithms\fR 4 |
| 422 |
.IX Item "SignatureAlgorithms" |
| 423 |
This sets the supported signature algorithms for TLSv1.2 and TLSv1.3. |
| 424 |
For clients this |
| 425 |
value is used directly for the supported signature algorithms extension. For |
| 426 |
servers it is used to determine which signature algorithms to support. |
| 427 |
.Sp |
| 428 |
The \fBvalue\fR argument should be a colon separated list of signature algorithms |
| 429 |
in order of decreasing preference of the form \fBalgorithm+hash\fR or |
| 430 |
\&\fBsignature_scheme\fR. For the default providers shipped with OpenSSL, |
| 431 |
\&\fBalgorithm\fR is one of \fBRSA\fR, \fBDSA\fR or \fBECDSA\fR and \fBhash\fR is a supported |
| 432 |
algorithm OID short name such as \fBSHA1\fR, \fBSHA224\fR, \fBSHA256\fR, \fBSHA384\fR |
| 433 |
or \fBSHA512\fR. |
| 434 |
\&\fBsignature_scheme\fR is one of the signature schemes defined in TLSv1.3, |
| 435 |
specified using the IANA name, e.g., \fBecdsa_secp256r1_sha256\fR, \fBed25519\fR, |
| 436 |
or \fBrsa_pss_pss_sha256\fR. |
| 437 |
Signature scheme names and public key algorithm names (but not the hash names) |
| 438 |
in the \fBalgorithm+hash\fR form are case-insensitive. |
| 439 |
Additional providers may make available further signature schemes via the |
| 440 |
TLS_SIGALG capability. See "CAPABILITIES" in \fBprovider\-base\fR\|(7). |
| 441 |
.Sp |
| 442 |
If this option is not set then all signature algorithms supported by all |
| 443 |
activated providers are permissible. |
| 444 |
.Sp |
| 445 |
Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by |
| 446 |
using \fBRSA\fR as the \fBalgorithm\fR or by using one of the \fBrsa_pkcs1_*\fR |
| 447 |
identifiers) are ignored in TLSv1.3 and will not be negotiated. |
| 448 |
.IP \fBClientSignatureAlgorithms\fR 4 |
| 449 |
.IX Item "ClientSignatureAlgorithms" |
| 450 |
This sets the supported signature algorithms associated with client |
| 451 |
authentication for TLSv1.2 and TLSv1.3. |
| 452 |
For servers the value is used in the |
| 453 |
\&\fBsignature_algorithms\fR field of a \fBCertificateRequest\fR message. |
| 454 |
For clients it is |
| 455 |
used to determine which signature algorithm to use with the client certificate. |
| 456 |
If a server does not request a certificate this option has no effect. |
| 457 |
.Sp |
| 458 |
The syntax of \fBvalue\fR is identical to \fBSignatureAlgorithms\fR. If not set then |
| 459 |
the value set for \fBSignatureAlgorithms\fR will be used instead. |
| 460 |
.IP \fBGroups\fR 4 |
| 461 |
.IX Item "Groups" |
| 462 |
This sets the supported groups. For clients, the groups are |
| 463 |
sent using the supported groups extension. For servers, it is used |
| 464 |
to determine which group to use. This setting affects groups used for |
| 465 |
signatures (in TLSv1.2 and earlier) and key exchange. The first group listed |
| 466 |
will also be used for the \fBkey_share\fR sent by a client in a TLSv1.3 |
| 467 |
\&\fBClientHello\fR. |
| 468 |
.Sp |
| 469 |
The \fBgroups\fR argument is a colon separated list of groups. The preferred |
| 470 |
names are those listed in the IANA |
| 471 |
TLS Supported Groups <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8> |
| 472 |
registry. |
| 473 |
For some groups, OpenSSL supports additional aliases. |
| 474 |
Such an alias could be a \fBNIST\fR name (e.g. \fBP\-256\fR), an OpenSSL OID name |
| 475 |
(e.g. \fBprime256v1\fR), or some other commonly used name. |
| 476 |
Group names are case-insensitive in OpenSSL 3.5 and later. |
| 477 |
The list should be in order of preference with the most preferred group first. |
| 478 |
.Sp |
| 479 |
The commands below list the available groups for TLS 1.2 and TLS 1.3, |
| 480 |
respectively: |
| 481 |
.Sp |
| 482 |
.Vb 2 |
| 483 |
\& $ openssl list \-tls1_2 \-tls\-groups |
| 484 |
\& $ openssl list \-tls1_3 \-tls\-groups |
| 485 |
.Ve |
| 486 |
.Sp |
| 487 |
An enriched alternative syntax, that enables clients to send multiple keyshares |
| 488 |
and allows servers to prioritise some groups over others, is described in |
| 489 |
\&\fBSSL_CTX_set1_groups_list\fR\|(3). |
| 490 |
Since TLS 1.2 has neither keyshares nor a hello retry mechanism, with TLS 1.2 |
| 491 |
the enriched syntax is ultimately equivalent to just a simple ordered list of |
| 492 |
groups, as with the simple form above. |
| 493 |
.IP \fBCurves\fR 4 |
| 494 |
.IX Item "Curves" |
| 495 |
This is a synonym for the "Groups" command. |
| 496 |
.IP \fBMinProtocol\fR 4 |
| 497 |
.IX Item "MinProtocol" |
| 498 |
This sets the minimum supported SSL, TLS or DTLS version. |
| 499 |
.Sp |
| 500 |
Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR, |
| 501 |
\&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR. |
| 502 |
The SSL and TLS bounds apply only to TLS-based contexts, while the DTLS bounds |
| 503 |
apply only to DTLS-based contexts. |
| 504 |
The command can be repeated with one instance setting a TLS bound, and the |
| 505 |
other setting a DTLS bound. |
| 506 |
The value \fBNone\fR applies to both types of contexts and disables the limits. |
| 507 |
.IP \fBMaxProtocol\fR 4 |
| 508 |
.IX Item "MaxProtocol" |
| 509 |
This sets the maximum supported SSL, TLS or DTLS version. |
| 510 |
.Sp |
| 511 |
Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR, |
| 512 |
\&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR. |
| 513 |
The SSL and TLS bounds apply only to TLS-based contexts, while the DTLS bounds |
| 514 |
apply only to DTLS-based contexts. |
| 515 |
The command can be repeated with one instance setting a TLS bound, and the |
| 516 |
other setting a DTLS bound. |
| 517 |
The value \fBNone\fR applies to both types of contexts and disables the limits. |
| 518 |
.IP \fBProtocol\fR 4 |
| 519 |
.IX Item "Protocol" |
| 520 |
This can be used to enable or disable certain versions of the SSL, |
| 521 |
TLS or DTLS protocol. |
| 522 |
.Sp |
| 523 |
The \fBvalue\fR argument is a comma separated list of supported protocols |
| 524 |
to enable or disable. |
| 525 |
If a protocol is preceded by \fB\-\fR that version is disabled. |
| 526 |
.Sp |
| 527 |
All protocol versions are enabled by default. |
| 528 |
You need to disable at least one protocol version for this setting have any |
| 529 |
effect. |
| 530 |
Only enabling some protocol versions does not disable the other protocol |
| 531 |
versions. |
| 532 |
.Sp |
| 533 |
Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR, |
| 534 |
\&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR. |
| 535 |
The special value \fBALL\fR refers to all supported versions. |
| 536 |
.Sp |
| 537 |
This can't enable protocols that are disabled using \fBMinProtocol\fR |
| 538 |
or \fBMaxProtocol\fR, but can disable protocols that are still allowed |
| 539 |
by them. |
| 540 |
.Sp |
| 541 |
The \fBProtocol\fR command is fragile and deprecated; do not use it. |
| 542 |
Use \fBMinProtocol\fR and \fBMaxProtocol\fR instead. |
| 543 |
If you do use \fBProtocol\fR, make sure that the resulting range of enabled |
| 544 |
protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make |
| 545 |
sure to also leave TLS 1.1 enabled. |
| 546 |
.IP \fBOptions\fR 4 |
| 547 |
.IX Item "Options" |
| 548 |
The \fBvalue\fR argument is a comma separated list of various flags to set. |
| 549 |
If a flag string is preceded \fB\-\fR it is disabled. |
| 550 |
See the \fBSSL_CTX_set_options\fR\|(3) function for more details of |
| 551 |
individual options. |
| 552 |
.Sp |
| 553 |
Each option is listed below. Where an operation is enabled by default |
| 554 |
the \fB\-flag\fR syntax is needed to disable it. |
| 555 |
.Sp |
| 556 |
\&\fBSessionTicket\fR: session ticket support, enabled by default. Inverse of |
| 557 |
\&\fBSSL_OP_NO_TICKET\fR: that is \fB\-SessionTicket\fR is the same as setting |
| 558 |
\&\fBSSL_OP_NO_TICKET\fR. |
| 559 |
.Sp |
| 560 |
\&\fBCompression\fR: SSL/TLS compression support, disabled by default. Inverse |
| 561 |
of \fBSSL_OP_NO_COMPRESSION\fR. |
| 562 |
.Sp |
| 563 |
\&\fBEmptyFragments\fR: use empty fragments as a countermeasure against a |
| 564 |
SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It |
| 565 |
is set by default. Inverse of \fBSSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\fR. |
| 566 |
.Sp |
| 567 |
\&\fBBugs\fR: enable various bug workarounds. Same as \fBSSL_OP_ALL\fR. |
| 568 |
.Sp |
| 569 |
\&\fBDHSingle\fR: enable single use DH keys, set by default. Inverse of |
| 570 |
\&\fBSSL_OP_DH_SINGLE\fR. Only used by servers. |
| 571 |
.Sp |
| 572 |
\&\fBECDHSingle\fR: enable single use ECDH keys, set by default. Inverse of |
| 573 |
\&\fBSSL_OP_ECDH_SINGLE\fR. Only used by servers. |
| 574 |
.Sp |
| 575 |
\&\fBServerPreference\fR: use server and not client preference order when |
| 576 |
determining which cipher suite, signature algorithm or elliptic curve |
| 577 |
(TLS 1.2) or group (TLS 1.3) to use for an incoming connection. |
| 578 |
Equivalent to \fBSSL_OP_SERVER_PREFERENCE\fR. Only used by servers. |
| 579 |
.Sp |
| 580 |
\&\fBPrioritizeChaCha\fR: prioritizes ChaCha ciphers when the client has a |
| 581 |
ChaCha20 cipher at the top of its preference list. This usually indicates |
| 582 |
a mobile client is in use. Equivalent to \fBSSL_OP_PRIORITIZE_CHACHA\fR. |
| 583 |
Only used by servers. |
| 584 |
.Sp |
| 585 |
\&\fBNoResumptionOnRenegotiation\fR: set |
| 586 |
\&\fBSSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\fR flag. Only used by servers. |
| 587 |
.Sp |
| 588 |
\&\fBNoRenegotiation\fR: disables all attempts at renegotiation in TLSv1.2 and |
| 589 |
earlier, same as setting \fBSSL_OP_NO_RENEGOTIATION\fR. |
| 590 |
.Sp |
| 591 |
\&\fBUnsafeLegacyRenegotiation\fR: permits the use of unsafe legacy renegotiation. |
| 592 |
Equivalent to \fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR. |
| 593 |
.Sp |
| 594 |
\&\fBUnsafeLegacyServerConnect\fR: permits the use of unsafe legacy renegotiation |
| 595 |
for OpenSSL clients only. Equivalent to \fBSSL_OP_LEGACY_SERVER_CONNECT\fR. |
| 596 |
.Sp |
| 597 |
\&\fBEncryptThenMac\fR: use encrypt-then-mac extension, enabled by |
| 598 |
default. Inverse of \fBSSL_OP_NO_ENCRYPT_THEN_MAC\fR: that is, |
| 599 |
\&\fB\-EncryptThenMac\fR is the same as setting \fBSSL_OP_NO_ENCRYPT_THEN_MAC\fR. |
| 600 |
.Sp |
| 601 |
\&\fBAllowNoDHEKEX\fR: In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on |
| 602 |
resumption. This means that there will be no forward secrecy for the resumed |
| 603 |
session. Equivalent to \fBSSL_OP_ALLOW_NO_DHE_KEX\fR. |
| 604 |
.Sp |
| 605 |
\&\fBPreferNoDHEKEX\fR: In TLSv1.3, on resumption let the server prefer a |
| 606 |
non\-(ec)dhe based key exchange mode over an (ec)dhe based one. Requires |
| 607 |
\&\fBAllowNoDHEKEX\fR. Equivalent to \fBSSL_OP_PREFER_NO_DHE_KEX\fR. Only used by |
| 608 |
servers. |
| 609 |
.Sp |
| 610 |
\&\fBMiddleboxCompat\fR: If set then dummy Change Cipher Spec (CCS) messages are sent |
| 611 |
in TLSv1.3. This has the effect of making TLSv1.3 look more like TLSv1.2 so that |
| 612 |
middleboxes that do not understand TLSv1.3 will not drop the connection. This |
| 613 |
option is set by default. A future version of OpenSSL may not set this by |
| 614 |
default. Equivalent to \fBSSL_OP_ENABLE_MIDDLEBOX_COMPAT\fR. |
| 615 |
.Sp |
| 616 |
\&\fBAntiReplay\fR: If set then OpenSSL will automatically detect if a session ticket |
| 617 |
has been used more than once, TLSv1.3 has been negotiated, and early data is |
| 618 |
enabled on the server. A full handshake is forced if a session ticket is used a |
| 619 |
second or subsequent time. This option is set by default and is only used by |
| 620 |
servers. Anti-replay measures are required to comply with the TLSv1.3 |
| 621 |
specification. Some applications may be able to mitigate the replay risks in |
| 622 |
other ways and in such cases the built-in OpenSSL functionality is not required. |
| 623 |
Disabling anti-replay is equivalent to setting \fBSSL_OP_NO_ANTI_REPLAY\fR. |
| 624 |
.Sp |
| 625 |
\&\fBExtendedMasterSecret\fR: use extended master secret extension, enabled by |
| 626 |
default. Inverse of \fBSSL_OP_NO_EXTENDED_MASTER_SECRET\fR: that is, |
| 627 |
\&\fB\-ExtendedMasterSecret\fR is the same as setting \fBSSL_OP_NO_EXTENDED_MASTER_SECRET\fR. |
| 628 |
.Sp |
| 629 |
\&\fBCANames\fR: use CA names extension, enabled by |
| 630 |
default. Inverse of \fBSSL_OP_DISABLE_TLSEXT_CA_NAMES\fR: that is, |
| 631 |
\&\fB\-CANames\fR is the same as setting \fBSSL_OP_DISABLE_TLSEXT_CA_NAMES\fR. |
| 632 |
.Sp |
| 633 |
\&\fBKTLS\fR: Enables kernel TLS if support has been compiled in, and it is supported |
| 634 |
by the negotiated ciphersuites and extensions. Equivalent to |
| 635 |
\&\fBSSL_OP_ENABLE_KTLS\fR. |
| 636 |
.Sp |
| 637 |
\&\fBStrictCertCheck\fR: Enable strict certificate checking. Equivalent to |
| 638 |
setting \fBSSL_CERT_FLAG_TLS_STRICT\fR with \fBSSL_CTX_set_cert_flags()\fR. |
| 639 |
.Sp |
| 640 |
\&\fBTxCertificateCompression\fR: support sending compressed certificates, enabled by |
| 641 |
default. Inverse of \fBSSL_OP_NO_TX_CERTIFICATE_COMPRESSION\fR: that is, |
| 642 |
\&\fB\-TxCertificateCompression\fR is the same as setting \fBSSL_OP_NO_TX_CERTIFICATE_COMPRESSION\fR. |
| 643 |
.Sp |
| 644 |
\&\fBRxCertificateCompression\fR: support receiving compressed certificates, enabled by |
| 645 |
default. Inverse of \fBSSL_OP_NO_RX_CERTIFICATE_COMPRESSION\fR: that is, |
| 646 |
\&\fB\-RxCertificateCompression\fR is the same as setting \fBSSL_OP_NO_RX_CERTIFICATE_COMPRESSION\fR. |
| 647 |
.Sp |
| 648 |
\&\fBKTLSTxZerocopySendfile\fR: use the zerocopy TX mode of \fBsendfile()\fR, which gives |
| 649 |
a performance boost when used with KTLS hardware offload. Note that invalid TLS |
| 650 |
records might be transmitted if the file is changed while being sent. This |
| 651 |
option has no effect if \fBKTLS\fR is not enabled. Equivalent to |
| 652 |
\&\fBSSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE\fR. This option only applies to Linux. |
| 653 |
KTLS sendfile on FreeBSD doesn't offer an option to disable zerocopy and |
| 654 |
always runs in this mode. |
| 655 |
.Sp |
| 656 |
\&\fBIgnoreUnexpectedEOF\fR: Equivalent to \fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR. |
| 657 |
You should only enable this option if the protocol running over TLS can detect |
| 658 |
a truncation attack itself, and that the application is checking for that |
| 659 |
truncation attack. |
| 660 |
.IP \fBVerifyMode\fR 4 |
| 661 |
.IX Item "VerifyMode" |
| 662 |
The \fBvalue\fR argument is a comma separated list of flags to set. |
| 663 |
.Sp |
| 664 |
\&\fBPeer\fR enables peer verification: for clients only. |
| 665 |
.Sp |
| 666 |
\&\fBRequest\fR requests but does not require a certificate from the client. |
| 667 |
Servers only. |
| 668 |
.Sp |
| 669 |
\&\fBRequire\fR requests and requires a certificate from the client: an error |
| 670 |
occurs if the client does not present a certificate. Servers only. |
| 671 |
.Sp |
| 672 |
\&\fBOnce\fR requests a certificate from a client only on the initial connection: |
| 673 |
not when renegotiating. Servers only. |
| 674 |
.Sp |
| 675 |
\&\fBRequestPostHandshake\fR configures the connection to support requests but does |
| 676 |
not require a certificate from the client post-handshake. A certificate will |
| 677 |
not be requested during the initial handshake. The server application must |
| 678 |
provide a mechanism to request a certificate post-handshake. Servers only. |
| 679 |
TLSv1.3 only. |
| 680 |
.Sp |
| 681 |
\&\fBRequiresPostHandshake\fR configures the connection to support requests and |
| 682 |
requires a certificate from the client post-handshake: an error occurs if the |
| 683 |
client does not present a certificate. A certificate will not be requested |
| 684 |
during the initial handshake. The server application must provide a mechanism |
| 685 |
to request a certificate post-handshake. Servers only. TLSv1.3 only. |
| 686 |
.IP "\fBClientCAFile\fR, \fBClientCAPath\fR" 4 |
| 687 |
.IX Item "ClientCAFile, ClientCAPath" |
| 688 |
A file or directory of certificates in PEM format whose names are used as the |
| 689 |
set of acceptable names for client CAs. Servers only. This option is only |
| 690 |
supported if certificate operations are permitted. |
| 691 |
.SH "SUPPORTED COMMAND TYPES" |
| 692 |
.IX Header "SUPPORTED COMMAND TYPES" |
| 693 |
The function \fBSSL_CONF_cmd_value_type()\fR currently returns one of the following |
| 694 |
types: |
| 695 |
.IP \fBSSL_CONF_TYPE_UNKNOWN\fR 4 |
| 696 |
.IX Item "SSL_CONF_TYPE_UNKNOWN" |
| 697 |
The \fBoption\fR string is unrecognised, this return value can be use to flag |
| 698 |
syntax errors. |
| 699 |
.IP \fBSSL_CONF_TYPE_STRING\fR 4 |
| 700 |
.IX Item "SSL_CONF_TYPE_STRING" |
| 701 |
The value is a string without any specific structure. |
| 702 |
.IP \fBSSL_CONF_TYPE_FILE\fR 4 |
| 703 |
.IX Item "SSL_CONF_TYPE_FILE" |
| 704 |
The value is a filename. |
| 705 |
.IP \fBSSL_CONF_TYPE_DIR\fR 4 |
| 706 |
.IX Item "SSL_CONF_TYPE_DIR" |
| 707 |
The value is a directory name. |
| 708 |
.IP \fBSSL_CONF_TYPE_NONE\fR 4 |
| 709 |
.IX Item "SSL_CONF_TYPE_NONE" |
| 710 |
The value string is not used e.g. a command line option which doesn't take an |
| 711 |
argument. |
| 712 |
.SH NOTES |
| 713 |
.IX Header "NOTES" |
| 714 |
The order of operations is significant. This can be used to set either defaults |
| 715 |
or values which cannot be overridden. For example if an application calls: |
| 716 |
.PP |
| 717 |
.Vb 2 |
| 718 |
\& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3"); |
| 719 |
\& SSL_CONF_cmd(ctx, userparam, uservalue); |
| 720 |
.Ve |
| 721 |
.PP |
| 722 |
it will disable SSLv3 support by default but the user can override it. If |
| 723 |
however the call sequence is: |
| 724 |
.PP |
| 725 |
.Vb 2 |
| 726 |
\& SSL_CONF_cmd(ctx, userparam, uservalue); |
| 727 |
\& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3"); |
| 728 |
.Ve |
| 729 |
.PP |
| 730 |
SSLv3 is \fBalways\fR disabled and attempt to override this by the user are |
| 731 |
ignored. |
| 732 |
.PP |
| 733 |
By checking the return code of \fBSSL_CONF_cmd()\fR it is possible to query if a |
| 734 |
given \fBoption\fR is recognised, this is useful if \fBSSL_CONF_cmd()\fR values are |
| 735 |
mixed with additional application specific operations. |
| 736 |
.PP |
| 737 |
For example an application might call \fBSSL_CONF_cmd()\fR and if it returns |
| 738 |
\&\-2 (unrecognised command) continue with processing of application specific |
| 739 |
commands. |
| 740 |
.PP |
| 741 |
Applications can also use \fBSSL_CONF_cmd()\fR to process command lines though the |
| 742 |
utility function \fBSSL_CONF_cmd_argv()\fR is normally used instead. One way |
| 743 |
to do this is to set the prefix to an appropriate value using |
| 744 |
\&\fBSSL_CONF_CTX_set1_prefix()\fR, pass the current argument to \fBoption\fR and the |
| 745 |
following argument to \fBvalue\fR (which may be NULL). |
| 746 |
.PP |
| 747 |
In this case if the return value is positive then it is used to skip that |
| 748 |
number of arguments as they have been processed by \fBSSL_CONF_cmd()\fR. If \-2 is |
| 749 |
returned then \fBoption\fR is not recognised and application specific arguments |
| 750 |
can be checked instead. If \-3 is returned a required argument is missing |
| 751 |
and an error is indicated. If 0 is returned some other error occurred and |
| 752 |
this can be reported back to the user. |
| 753 |
.PP |
| 754 |
The function \fBSSL_CONF_cmd_value_type()\fR can be used by applications to |
| 755 |
check for the existence of a command or to perform additional syntax |
| 756 |
checking or translation of the command value. For example if the return |
| 757 |
value is \fBSSL_CONF_TYPE_FILE\fR an application could translate a relative |
| 758 |
pathname to an absolute pathname. |
| 759 |
.SH "RETURN VALUES" |
| 760 |
.IX Header "RETURN VALUES" |
| 761 |
\&\fBSSL_CONF_cmd()\fR returns 1 if the value of \fBoption\fR is recognised and \fBvalue\fR is |
| 762 |
\&\fBNOT\fR used and 2 if both \fBoption\fR and \fBvalue\fR are used. In other words it |
| 763 |
returns the number of arguments processed. This is useful when processing |
| 764 |
command lines. |
| 765 |
.PP |
| 766 |
A return value of \-2 means \fBoption\fR is not recognised. |
| 767 |
.PP |
| 768 |
A return value of \-3 means \fBoption\fR is recognised and the command requires a |
| 769 |
value but \fBvalue\fR is NULL. |
| 770 |
.PP |
| 771 |
A return code of 0 indicates that both \fBoption\fR and \fBvalue\fR are valid but an |
| 772 |
error occurred attempting to perform the operation: for example due to an |
| 773 |
error in the syntax of \fBvalue\fR in this case the error queue may provide |
| 774 |
additional information. |
| 775 |
.SH EXAMPLES |
| 776 |
.IX Header "EXAMPLES" |
| 777 |
Set supported signature algorithms: |
| 778 |
.PP |
| 779 |
.Vb 1 |
| 780 |
\& SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256"); |
| 781 |
.Ve |
| 782 |
.PP |
| 783 |
There are various ways to select the supported protocols. |
| 784 |
.PP |
| 785 |
This set the minimum protocol version to TLSv1, and so disables SSLv3. |
| 786 |
This is the recommended way to disable protocols. |
| 787 |
.PP |
| 788 |
.Vb 1 |
| 789 |
\& SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1"); |
| 790 |
.Ve |
| 791 |
.PP |
| 792 |
The following also disables SSLv3: |
| 793 |
.PP |
| 794 |
.Vb 1 |
| 795 |
\& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3"); |
| 796 |
.Ve |
| 797 |
.PP |
| 798 |
The following will first enable all protocols, and then disable |
| 799 |
SSLv3. |
| 800 |
If no protocol versions were disabled before this has the same effect as |
| 801 |
"\-SSLv3", but if some versions were disables this will re-enable them before |
| 802 |
disabling SSLv3. |
| 803 |
.PP |
| 804 |
.Vb 1 |
| 805 |
\& SSL_CONF_cmd(ctx, "Protocol", "ALL,\-SSLv3"); |
| 806 |
.Ve |
| 807 |
.PP |
| 808 |
Only enable TLSv1.2: |
| 809 |
.PP |
| 810 |
.Vb 2 |
| 811 |
\& SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2"); |
| 812 |
\& SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2"); |
| 813 |
.Ve |
| 814 |
.PP |
| 815 |
This also only enables TLSv1.2: |
| 816 |
.PP |
| 817 |
.Vb 1 |
| 818 |
\& SSL_CONF_cmd(ctx, "Protocol", "\-ALL,TLSv1.2"); |
| 819 |
.Ve |
| 820 |
.PP |
| 821 |
Disable TLS session tickets: |
| 822 |
.PP |
| 823 |
.Vb 1 |
| 824 |
\& SSL_CONF_cmd(ctx, "Options", "\-SessionTicket"); |
| 825 |
.Ve |
| 826 |
.PP |
| 827 |
Enable compression: |
| 828 |
.PP |
| 829 |
.Vb 1 |
| 830 |
\& SSL_CONF_cmd(ctx, "Options", "Compression"); |
| 831 |
.Ve |
| 832 |
.PP |
| 833 |
Set supported curves to P\-256, P\-384: |
| 834 |
.PP |
| 835 |
.Vb 1 |
| 836 |
\& SSL_CONF_cmd(ctx, "Curves", "P\-256:P\-384"); |
| 837 |
.Ve |
| 838 |
.SH "SEE ALSO" |
| 839 |
.IX Header "SEE ALSO" |
| 840 |
\&\fBssl\fR\|(7), |
| 841 |
\&\fBSSL_CONF_CTX_new\fR\|(3), |
| 842 |
\&\fBSSL_CONF_CTX_set_flags\fR\|(3), |
| 843 |
\&\fBSSL_CONF_CTX_set1_prefix\fR\|(3), |
| 844 |
\&\fBSSL_CONF_CTX_set_ssl_ctx\fR\|(3), |
| 845 |
\&\fBSSL_CONF_cmd_argv\fR\|(3), |
| 846 |
\&\fBSSL_CTX_set_options\fR\|(3) |
| 847 |
.SH HISTORY |
| 848 |
.IX Header "HISTORY" |
| 849 |
The \fBSSL_CONF_cmd()\fR function was added in OpenSSL 1.0.2. |
| 850 |
.PP |
| 851 |
The \fBSSL_OP_NO_SSL2\fR option doesn't have effect since 1.1.0, but the macro |
| 852 |
is retained for backwards compatibility. |
| 853 |
.PP |
| 854 |
The \fBSSL_CONF_TYPE_NONE\fR was added in OpenSSL 1.1.0. In earlier versions of |
| 855 |
OpenSSL passing a command which didn't take an argument would return |
| 856 |
\&\fBSSL_CONF_TYPE_UNKNOWN\fR. |
| 857 |
.PP |
| 858 |
\&\fBMinProtocol\fR and \fBMaxProtocol\fR where added in OpenSSL 1.1.0. |
| 859 |
.PP |
| 860 |
\&\fBAllowNoDHEKEX\fR and \fBPrioritizeChaCha\fR were added in OpenSSL 1.1.1. |
| 861 |
.PP |
| 862 |
The \fBUnsafeLegacyServerConnect\fR option is no longer set by default from |
| 863 |
OpenSSL 3.0. |
| 864 |
.PP |
| 865 |
The \fBTxCertificateCompression\fR and \fBRxCertificateCompression\fR options were |
| 866 |
added in OpenSSL 3.2. |
| 867 |
.PP |
| 868 |
\&\fBPreferNoDHEKEX\fR was added in OpenSSL 3.3. |
| 869 |
.PP |
| 870 |
OpenSSL 3.5 introduces support for post-quantum (PQ) TLS key exchange via the |
| 871 |
\&\fBMLKEM512\fR, \fBMLKEM768\fR and \fBMLKEM1024\fR TLS groups. |
| 872 |
These are based on the underlying \fBML\-KEM\-512\fR, \fBML\-KEM\-768\fR and |
| 873 |
\&\fBML\-KEM\-1024\fR algorithms from FIPS 203. |
| 874 |
.PP |
| 875 |
OpenSSL 3.5 also introduces support for three \fBhybrid\fR ECDH PQ key exchange |
| 876 |
TLS groups: \fBX25519MLKEM768\fR, \fBSecP256r1MLKEM768\fR and |
| 877 |
\&\fBSecP384r1MLKEM1024\fR. |
| 878 |
They offer CPU performance comparable to the associated ECDH group, though at |
| 879 |
the cost of significantly larger key exchange messages. |
| 880 |
The third group, \fBSecP384r1MLKEM1024\fR is substantially more CPU-intensive, |
| 881 |
largely as a result of the high CPU cost of ECDH for the underlying \fBP\-384\fR |
| 882 |
group. |
| 883 |
Also its key exchange messages at close to 1700 bytes are larger than the |
| 884 |
roughly 1200 bytes for the first two groups. |
| 885 |
.PP |
| 886 |
As of OpenSSL 3.5 key exchange group names are case-insensitive. |
| 887 |
.SH COPYRIGHT |
| 888 |
.IX Header "COPYRIGHT" |
| 889 |
Copyright 2012\-2026 The OpenSSL Project Authors. All Rights Reserved. |
| 890 |
.PP |
| 891 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 892 |
this file except in compliance with the License. You can obtain a copy |
| 893 |
in the file LICENSE in the source distribution or at |
| 894 |
<https://www.openssl.org/source/license.html>. |