secure/lib/libcrypto/man/SSL_CONF_cmd.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CONF_CMD 3"
 132 .TH SSL_CONF_CMD 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 SSL_CONF_cmd_value_type, SSL_CONF_cmd \- send configuration command
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);
 145 \& int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd);
 146 .Ve
 147 .SH "DESCRIPTION"
 148 .IX Header "DESCRIPTION"
 149 The function \fISSL_CONF_cmd()\fR performs configuration operation \fBcmd\fR with
 150 optional parameter \fBvalue\fR on \fBctx\fR. Its purpose is to simplify application
 151 configuration of \fB\s-1SSL_CTX\s0\fR or \fB\s-1SSL\s0\fR structures by providing a common
 152 framework for command line options or configuration files.
 153 .PP
 154 \&\fISSL_CONF_cmd_value_type()\fR returns the type of value that \fBcmd\fR refers to.
 155 .SH "SUPPORTED COMMAND LINE COMMANDS"
 156 .IX Header "SUPPORTED COMMAND LINE COMMANDS"
 157 Currently supported \fBcmd\fR names for command lines (i.e. when the
 158 flag \fB\s-1SSL_CONF_CMDLINE\s0\fR is set) are listed below. Note: all \fBcmd\fR names
 159 are case sensitive. Unless otherwise stated commands can be used by
 160 both clients and servers and the \fBvalue\fR parameter is not used. The default
 161 prefix for command line commands is \fB\-\fR and that is reflected below.
 162 .IP "\fB\-sigalgs\fR" 4
 163 .IX Item "-sigalgs"
 164 This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
 165 For clients this
 166 value is used directly for the supported signature algorithms extension. For
 167 servers it is used to determine which signature algorithms to support.
 168 .Sp
 169 The \fBvalue\fR argument should be a colon separated list of signature algorithms
 170 in order of decreasing preference of the form \fBalgorithm+hash\fR or
 171 \&\fBsignature_scheme\fR. \fBalgorithm\fR
 172 is one of \fB\s-1RSA\s0\fR, \fB\s-1DSA\s0\fR or \fB\s-1ECDSA\s0\fR and \fBhash\fR is a supported algorithm
 173 \&\s-1OID\s0 short name such as \fB\s-1SHA1\s0\fR, \fB\s-1SHA224\s0\fR, \fB\s-1SHA256\s0\fR, \fB\s-1SHA384\s0\fR of \fB\s-1SHA512\s0\fR.
 174 Note: algorithm and hash names are case sensitive.
 175 \&\fBsignature_scheme\fR is one of the signature schemes defined in TLSv1.3,
 176 specified using the \s-1IETF\s0 name, e.g., \fBecdsa_secp256r1_sha256\fR, \fBed25519\fR,
 177 or \fBrsa_pss_pss_sha256\fR.
 178 .Sp
 179 If this option is not set then all signature algorithms supported by the
 180 OpenSSL library are permissible.
 181 .Sp
 182 Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
 183 using \fB\s-1RSA\s0\fR as the \fBalgorithm\fR or by using one of the \fBrsa_pkcs1_*\fR
 184 identifiers) are ignored in TLSv1.3 and will not be negotiated.
 185 .IP "\fB\-client_sigalgs\fR" 4
 186 .IX Item "-client_sigalgs"
 187 This sets the supported signature algorithms associated with client
 188 authentication for TLSv1.2 and TLSv1.3.
 189 For servers the value is used in the
 190 \&\fBsignature_algorithms\fR field of a \fBCertificateRequest\fR message.
 191 For clients it is
 192 used to determine which signature algorithm to use with the client certificate.
 193 If a server does not request a certificate this option has no effect.
 194 .Sp
 195 The syntax of \fBvalue\fR is identical to \fB\-sigalgs\fR. If not set then
 196 the value set for \fB\-sigalgs\fR will be used instead.
 197 .IP "\fB\-groups\fR" 4
 198 .IX Item "-groups"
 199 This sets the supported groups. For clients, the groups are
 200 sent using the supported groups extension. For servers, it is used
 201 to determine which group to use. This setting affects groups used for
 202 signatures (in TLSv1.2 and earlier) and key exchange. The first group listed
 203 will also be used for the \fBkey_share\fR sent by a client in a TLSv1.3
 204 \&\fBClientHello\fR.
 205 .Sp
 206 The \fBvalue\fR argument is a colon separated list of groups. The group can be
 207 either the \fB\s-1NIST\s0\fR name (e.g. \fBP\-256\fR), some other commonly used name where
 208 applicable (e.g. \fBX25519\fR) or an OpenSSL \s-1OID\s0 name (e.g \fBprime256v1\fR). Group
 209 names are case sensitive. The list should be in order of preference with the
 210 most preferred group first.
 211 .IP "\fB\-curves\fR" 4
 212 .IX Item "-curves"
 213 This is a synonym for the \*(L"\-groups\*(R" command.
 214 .IP "\fB\-named_curve\fR" 4
 215 .IX Item "-named_curve"
 216 This sets the temporary curve used for ephemeral \s-1ECDH\s0 modes. Only used by
 217 servers
 218 .Sp
 219 The \fBvalue\fR argument is a curve name or the special value \fBauto\fR which
 220 picks an appropriate curve based on client and server preferences. The curve
 221 can be either the \fB\s-1NIST\s0\fR name (e.g. \fBP\-256\fR) or an OpenSSL \s-1OID\s0 name
 222 (e.g \fBprime256v1\fR). Curve names are case sensitive.
 223 .IP "\fB\-cipher\fR" 4
 224 .IX Item "-cipher"
 225 Sets the TLSv1.2 and below ciphersuite list to \fBvalue\fR. This list will be
 226 combined with any configured TLSv1.3 ciphersuites. Note: syntax checking
 227 of \fBvalue\fR is currently not performed unless a \fB\s-1SSL\s0\fR or \fB\s-1SSL_CTX\s0\fR structure is
 228 associated with \fBcctx\fR.
 229 .IP "\fB\-ciphersuites\fR" 4
 230 .IX Item "-ciphersuites"
 231 Sets the available ciphersuites for TLSv1.3 to value. This is a simple colon
 232 (\*(L":\*(R") separated list of TLSv1.3 ciphersuite names in order of preference. This
 233 list will be combined any configured TLSv1.2 and below ciphersuites.
 234 See \fIciphers\fR\|(1) for more information.
 235 .IP "\fB\-cert\fR" 4
 236 .IX Item "-cert"
 237 Attempts to use the file \fBvalue\fR as the certificate for the appropriate
 238 context. It currently uses \fISSL_CTX_use_certificate_chain_file()\fR if an \fB\s-1SSL_CTX\s0\fR
 239 structure is set or \fISSL_use_certificate_file()\fR with filetype \s-1PEM\s0 if an \fB\s-1SSL\s0\fR
 240 structure is set. This option is only supported if certificate operations
 241 are permitted.
 242 .IP "\fB\-key\fR" 4
 243 .IX Item "-key"
 244 Attempts to use the file \fBvalue\fR as the private key for the appropriate
 245 context. This option is only supported if certificate operations
 246 are permitted. Note: if no \fB\-key\fR option is set then a private key is
 247 not loaded unless the flag \fB\s-1SSL_CONF_FLAG_REQUIRE_PRIVATE\s0\fR is set.
 248 .IP "\fB\-dhparam\fR" 4
 249 .IX Item "-dhparam"
 250 Attempts to use the file \fBvalue\fR as the set of temporary \s-1DH\s0 parameters for
 251 the appropriate context. This option is only supported if certificate
 252 operations are permitted.
 253 .IP "\fB\-record_padding\fR" 4
 254 .IX Item "-record_padding"
 255 Attempts to pad TLSv1.3 records so that they are a multiple of \fBvalue\fR in
 256 length on send. A \fBvalue\fR of 0 or 1 turns off padding. Otherwise, the
 257 \&\fBvalue\fR must be >1 or <=16384.
 258 .IP "\fB\-no_renegotiation\fR" 4
 259 .IX Item "-no_renegotiation"
 260 Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
 261 \&\fB\s-1SSL_OP_NO_RENEGOTIATION\s0\fR.
 262 .IP "\fB\-min_protocol\fR, \fB\-max_protocol\fR" 4
 263 .IX Item "-min_protocol, -max_protocol"
 264 Sets the minimum and maximum supported protocol.
 265 Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR,
 266 \&\fBTLSv1.1\fR, \fBTLSv1.2\fR, \fBTLSv1.3\fR for \s-1TLS\s0 and \fBDTLSv1\fR, \fBDTLSv1.2\fR for \s-1DTLS,\s0
 267 and \fBNone\fR for no limit.
 268 If either bound is not specified then only the other bound applies,
 269 if specified.
 270 To restrict the supported protocol versions use these commands rather
 271 than the deprecated alternative commands below.
 272 .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
 273 .IX Item "-no_ssl3, -no_tls1, -no_tls1_1, -no_tls1_2, -no_tls1_3"
 274 Disables protocol support for SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3 by
 275 setting the corresponding options \fBSSL_OP_NO_SSLv3\fR, \fBSSL_OP_NO_TLSv1\fR,
 276 \&\fBSSL_OP_NO_TLSv1_1\fR, \fBSSL_OP_NO_TLSv1_2\fR and \fBSSL_OP_NO_TLSv1_3\fR
 277 respectively. These options are deprecated, instead use \fB\-min_protocol\fR and
 278 \&\fB\-max_protocol\fR.
 279 .IP "\fB\-bugs\fR" 4
 280 .IX Item "-bugs"
 281 Various bug workarounds are set, same as setting \fB\s-1SSL_OP_ALL\s0\fR.
 282 .IP "\fB\-comp\fR" 4
 283 .IX Item "-comp"
 284 Enables support for \s-1SSL/TLS\s0 compression, same as clearing
 285 \&\fB\s-1SSL_OP_NO_COMPRESSION\s0\fR.
 286 This command was introduced in OpenSSL 1.1.0.
 287 As of OpenSSL 1.1.0, compression is off by default.
 288 .IP "\fB\-no_comp\fR" 4
 289 .IX Item "-no_comp"
 290 Disables support for \s-1SSL/TLS\s0 compression, same as setting
 291 \&\fB\s-1SSL_OP_NO_COMPRESSION\s0\fR.
 292 As of OpenSSL 1.1.0, compression is off by default.
 293 .IP "\fB\-no_ticket\fR" 4
 294 .IX Item "-no_ticket"
 295 Disables support for session tickets, same as setting \fB\s-1SSL_OP_NO_TICKET\s0\fR.
 296 .IP "\fB\-serverpref\fR" 4
 297 .IX Item "-serverpref"
 298 Use server and not client preference order when determining which cipher suite,
 299 signature algorithm or elliptic curve to use for an incoming connection.
 300 Equivalent to \fB\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0\fR. Only used by servers.
 301 .IP "\fB\-prioritize_chacha\fR" 4
 302 .IX Item "-prioritize_chacha"
 303 Prioritize ChaCha ciphers when the client has a ChaCha20 cipher at the top of
 304 its preference list. This usually indicates a client without \s-1AES\s0 hardware
 305 acceleration (e.g. mobile) is in use. Equivalent to \fB\s-1SSL_OP_PRIORITIZE_CHACHA\s0\fR.
 306 Only used by servers. Requires \fB\-serverpref\fR.
 307 .IP "\fB\-no_resumption_on_reneg\fR" 4
 308 .IX Item "-no_resumption_on_reneg"
 309 set \s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0 flag. Only used by servers.
 310 .IP "\fB\-legacyrenegotiation\fR" 4
 311 .IX Item "-legacyrenegotiation"
 312 permits the use of unsafe legacy renegotiation. Equivalent to setting
 313 \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR.
 314 .IP "\fB\-legacy_server_connect\fR, \fB\-no_legacy_server_connect\fR" 4
 315 .IX Item "-legacy_server_connect, -no_legacy_server_connect"
 316 permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
 317 clients only. Equivalent to setting or clearing \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR.
 318 Set by default.
 319 .IP "\fB\-allow_no_dhe_kex\fR" 4
 320 .IX Item "-allow_no_dhe_kex"
 321 In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on resumption. This means
 322 that there will be no forward secrecy for the resumed session.
 323 .IP "\fB\-strict\fR" 4
 324 .IX Item "-strict"
 325 enables strict mode protocol handling. Equivalent to setting
 326 \&\fB\s-1SSL_CERT_FLAG_TLS_STRICT\s0\fR.
 327 .IP "\fB\-anti_replay\fR, \fB\-no_anti_replay\fR" 4
 328 .IX Item "-anti_replay, -no_anti_replay"
 329 Switches replay protection, on or off respectively. With replay protection on,
 330 OpenSSL will automatically detect if a session ticket has been used more than
 331 once, TLSv1.3 has been negotiated, and early data is enabled on the server. A
 332 full handshake is forced if a session ticket is used a second or subsequent
 333 time. Anti-Replay is on by default unless overridden by a configuration file and
 334 is only used by servers. Anti-replay measures are required for compliance with
 335 the TLSv1.3 specification. Some applications may be able to mitigate the replay
 336 risks in other ways and in such cases the built-in OpenSSL functionality is not
 337 required. Switching off anti-replay is equivalent to \fB\s-1SSL_OP_NO_ANTI_REPLAY\s0\fR.
 338 .SH "SUPPORTED CONFIGURATION FILE COMMANDS"
 339 .IX Header "SUPPORTED CONFIGURATION FILE COMMANDS"
 340 Currently supported \fBcmd\fR names for configuration files (i.e. when the
 341 flag \fB\s-1SSL_CONF_FLAG_FILE\s0\fR is set) are listed below. All configuration file
 342 \&\fBcmd\fR names are case insensitive so \fBsignaturealgorithms\fR is recognised
 343 as well as \fBSignatureAlgorithms\fR. Unless otherwise stated the \fBvalue\fR names
 344 are also case insensitive.
 345 .PP
 346 Note: the command prefix (if set) alters the recognised \fBcmd\fR values.
 347 .IP "\fBCipherString\fR" 4
 348 .IX Item "CipherString"
 349 Sets the ciphersuite list for TLSv1.2 and below to \fBvalue\fR. This list will be
 350 combined with any configured TLSv1.3 ciphersuites. Note: syntax
 351 checking of \fBvalue\fR is currently not performed unless an \fB\s-1SSL\s0\fR or \fB\s-1SSL_CTX\s0\fR
 352 structure is associated with \fBcctx\fR.
 353 .IP "\fBCiphersuites\fR" 4
 354 .IX Item "Ciphersuites"
 355 Sets the available ciphersuites for TLSv1.3 to \fBvalue\fR. This is a simple colon
 356 (\*(L":\*(R") separated list of TLSv1.3 ciphersuite names in order of preference. This
 357 list will be combined any configured TLSv1.2 and below ciphersuites.
 358 See \fIciphers\fR\|(1) for more information.
 359 .IP "\fBCertificate\fR" 4
 360 .IX Item "Certificate"
 361 Attempts to use the file \fBvalue\fR as the certificate for the appropriate
 362 context. It currently uses \fISSL_CTX_use_certificate_chain_file()\fR if an \fB\s-1SSL_CTX\s0\fR
 363 structure is set or \fISSL_use_certificate_file()\fR with filetype \s-1PEM\s0 if an \fB\s-1SSL\s0\fR
 364 structure is set. This option is only supported if certificate operations
 365 are permitted.
 366 .IP "\fBPrivateKey\fR" 4
 367 .IX Item "PrivateKey"
 368 Attempts to use the file \fBvalue\fR as the private key for the appropriate
 369 context. This option is only supported if certificate operations
 370 are permitted. Note: if no \fBPrivateKey\fR option is set then a private key is
 371 not loaded unless the \fB\s-1SSL_CONF_FLAG_REQUIRE_PRIVATE\s0\fR is set.
 372 .IP "\fBChainCAFile\fR, \fBChainCAPath\fR, \fBVerifyCAFile\fR, \fBVerifyCAPath\fR" 4
 373 .IX Item "ChainCAFile, ChainCAPath, VerifyCAFile, VerifyCAPath"
 374 These options indicate a file or directory used for building certificate
 375 chains or verifying certificate chains. These options are only supported
 376 if certificate operations are permitted.
 377 .IP "\fBRequestCAFile\fR" 4
 378 .IX Item "RequestCAFile"
 379 This option indicates a file containing a set of certificates in \s-1PEM\s0 form.
 380 The subject names of the certificates are sent to the peer in the
 381 \&\fBcertificate_authorities\fR extension for \s-1TLS 1.3\s0 (in ClientHello or
 382 CertificateRequest) or in a certificate request for previous versions or
 383 \&\s-1TLS.\s0
 384 .IP "\fBServerInfoFile\fR" 4
 385 .IX Item "ServerInfoFile"
 386 Attempts to use the file \fBvalue\fR in the \*(L"serverinfo\*(R" extension using the
 387 function SSL_CTX_use_serverinfo_file.
 388 .IP "\fBDHParameters\fR" 4
 389 .IX Item "DHParameters"
 390 Attempts to use the file \fBvalue\fR as the set of temporary \s-1DH\s0 parameters for
 391 the appropriate context. This option is only supported if certificate
 392 operations are permitted.
 393 .IP "\fBRecordPadding\fR" 4
 394 .IX Item "RecordPadding"
 395 Attempts to pad TLSv1.3 records so that they are a multiple of \fBvalue\fR in
 396 length on send. A \fBvalue\fR of 0 or 1 turns off padding. Otherwise, the
 397 \&\fBvalue\fR must be >1 or <=16384.
 398 .IP "\fBNoRenegotiation\fR" 4
 399 .IX Item "NoRenegotiation"
 400 Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
 401 \&\fB\s-1SSL_OP_NO_RENEGOTIATION\s0\fR.
 402 .IP "\fBSignatureAlgorithms\fR" 4
 403 .IX Item "SignatureAlgorithms"
 404 This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
 405 For clients this
 406 value is used directly for the supported signature algorithms extension. For
 407 servers it is used to determine which signature algorithms to support.
 408 .Sp
 409 The \fBvalue\fR argument should be a colon separated list of signature algorithms
 410 in order of decreasing preference of the form \fBalgorithm+hash\fR or
 411 \&\fBsignature_scheme\fR. \fBalgorithm\fR
 412 is one of \fB\s-1RSA\s0\fR, \fB\s-1DSA\s0\fR or \fB\s-1ECDSA\s0\fR and \fBhash\fR is a supported algorithm
 413 \&\s-1OID\s0 short name such as \fB\s-1SHA1\s0\fR, \fB\s-1SHA224\s0\fR, \fB\s-1SHA256\s0\fR, \fB\s-1SHA384\s0\fR of \fB\s-1SHA512\s0\fR.
 414 Note: algorithm and hash names are case sensitive.
 415 \&\fBsignature_scheme\fR is one of the signature schemes defined in TLSv1.3,
 416 specified using the \s-1IETF\s0 name, e.g., \fBecdsa_secp256r1_sha256\fR, \fBed25519\fR,
 417 or \fBrsa_pss_pss_sha256\fR.
 418 .Sp
 419 If this option is not set then all signature algorithms supported by the
 420 OpenSSL library are permissible.
 421 .Sp
 422 Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
 423 using \fB\s-1RSA\s0\fR as the \fBalgorithm\fR or by using one of the \fBrsa_pkcs1_*\fR
 424 identifiers) are ignored in TLSv1.3 and will not be negotiated.
 425 .IP "\fBClientSignatureAlgorithms\fR" 4
 426 .IX Item "ClientSignatureAlgorithms"
 427 This sets the supported signature algorithms associated with client
 428 authentication for TLSv1.2 and TLSv1.3.
 429 For servers the value is used in the
 430 \&\fBsignature_algorithms\fR field of a \fBCertificateRequest\fR message.
 431 For clients it is
 432 used to determine which signature algorithm to use with the client certificate.
 433 If a server does not request a certificate this option has no effect.
 434 .Sp
 435 The syntax of \fBvalue\fR is identical to \fBSignatureAlgorithms\fR. If not set then
 436 the value set for \fBSignatureAlgorithms\fR will be used instead.
 437 .IP "\fBGroups\fR" 4
 438 .IX Item "Groups"
 439 This sets the supported groups. For clients, the groups are
 440 sent using the supported groups extension. For servers, it is used
 441 to determine which group to use. This setting affects groups used for
 442 signatures (in TLSv1.2 and earlier) and key exchange. The first group listed
 443 will also be used for the \fBkey_share\fR sent by a client in a TLSv1.3
 444 \&\fBClientHello\fR.
 445 .Sp
 446 The \fBvalue\fR argument is a colon separated list of groups. The group can be
 447 either the \fB\s-1NIST\s0\fR name (e.g. \fBP\-256\fR), some other commonly used name where
 448 applicable (e.g. \fBX25519\fR) or an OpenSSL \s-1OID\s0 name (e.g \fBprime256v1\fR). Group
 449 names are case sensitive. The list should be in order of preference with the
 450 most preferred group first.
 451 .IP "\fBCurves\fR" 4
 452 .IX Item "Curves"
 453 This is a synonym for the \*(L"Groups\*(R" command.
 454 .IP "\fBMinProtocol\fR" 4
 455 .IX Item "MinProtocol"
 456 This sets the minimum supported \s-1SSL, TLS\s0 or \s-1DTLS\s0 version.
 457 .Sp
 458 Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR,
 459 \&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR.
 460 The value \fBNone\fR will disable the limit.
 461 .IP "\fBMaxProtocol\fR" 4
 462 .IX Item "MaxProtocol"
 463 This sets the maximum supported \s-1SSL, TLS\s0 or \s-1DTLS\s0 version.
 464 .Sp
 465 Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR,
 466 \&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR.
 467 The value \fBNone\fR will disable the limit.
 468 .IP "\fBProtocol\fR" 4
 469 .IX Item "Protocol"
 470 This can be used to enable or disable certain versions of the \s-1SSL,
 471 TLS\s0 or \s-1DTLS\s0 protocol.
 472 .Sp
 473 The \fBvalue\fR argument is a comma separated list of supported protocols
 474 to enable or disable.
 475 If a protocol is preceded by \fB\-\fR that version is disabled.
 476 .Sp
 477 All protocol versions are enabled by default.
 478 You need to disable at least one protocol version for this setting have any
 479 effect.
 480 Only enabling some protocol versions does not disable the other protocol
 481 versions.
 482 .Sp
 483 Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR,
 484 \&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR.
 485 The special value \fB\s-1ALL\s0\fR refers to all supported versions.
 486 .Sp
 487 This can't enable protocols that are disabled using \fBMinProtocol\fR
 488 or \fBMaxProtocol\fR, but can disable protocols that are still allowed
 489 by them.
 490 .Sp
 491 The \fBProtocol\fR command is fragile and deprecated; do not use it.
 492 Use \fBMinProtocol\fR and \fBMaxProtocol\fR instead.
 493 If you do use \fBProtocol\fR, make sure that the resulting range of enabled
 494 protocols has no \*(L"holes\*(R", e.g. if \s-1TLS 1.0\s0 and \s-1TLS 1.2\s0 are both enabled, make
 495 sure to also leave \s-1TLS 1.1\s0 enabled.
 496 .IP "\fBOptions\fR" 4
 497 .IX Item "Options"
 498 The \fBvalue\fR argument is a comma separated list of various flags to set.
 499 If a flag string is preceded \fB\-\fR it is disabled.
 500 See the \fISSL_CTX_set_options\fR\|(3) function for more details of
 501 individual options.
 502 .Sp
 503 Each option is listed below. Where an operation is enabled by default
 504 the \fB\-flag\fR syntax is needed to disable it.
 505 .Sp
 506 \&\fBSessionTicket\fR: session ticket support, enabled by default. Inverse of
 507 \&\fB\s-1SSL_OP_NO_TICKET\s0\fR: that is \fB\-SessionTicket\fR is the same as setting
 508 \&\fB\s-1SSL_OP_NO_TICKET\s0\fR.
 509 .Sp
 510 \&\fBCompression\fR: \s-1SSL/TLS\s0 compression support, enabled by default. Inverse
 511 of \fB\s-1SSL_OP_NO_COMPRESSION\s0\fR.
 512 .Sp
 513 \&\fBEmptyFragments\fR: use empty fragments as a countermeasure against a
 514 \&\s-1SSL 3.0/TLS 1.0\s0 protocol vulnerability affecting \s-1CBC\s0 ciphers. It
 515 is set by default. Inverse of \fB\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0\fR.
 516 .Sp
 517 \&\fBBugs\fR: enable various bug workarounds. Same as \fB\s-1SSL_OP_ALL\s0\fR.
 518 .Sp
 519 \&\fBDHSingle\fR: enable single use \s-1DH\s0 keys, set by default. Inverse of
 520 \&\fB\s-1SSL_OP_DH_SINGLE\s0\fR. Only used by servers.
 521 .Sp
 522 \&\fBECDHSingle\fR: enable single use \s-1ECDH\s0 keys, set by default. Inverse of
 523 \&\fB\s-1SSL_OP_ECDH_SINGLE\s0\fR. Only used by servers.
 524 .Sp
 525 \&\fBServerPreference\fR: use server and not client preference order when
 526 determining which cipher suite, signature algorithm or elliptic curve
 527 to use for an incoming connection.  Equivalent to
 528 \&\fB\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0\fR. Only used by servers.
 529 .Sp
 530 \&\fBPrioritizeChaCha\fR: prioritizes ChaCha ciphers when the client has a
 531 ChaCha20 cipher at the top of its preference list. This usually indicates
 532 a mobile client is in use. Equivalent to \fB\s-1SSL_OP_PRIORITIZE_CHACHA\s0\fR.
 533 Only used by servers.
 534 .Sp
 535 \&\fBNoResumptionOnRenegotiation\fR: set
 536 \&\fB\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0\fR flag. Only used by servers.
 537 .Sp
 538 \&\fBUnsafeLegacyRenegotiation\fR: permits the use of unsafe legacy renegotiation.
 539 Equivalent to \fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR.
 540 .Sp
 541 \&\fBUnsafeLegacyServerConnect\fR: permits the use of unsafe legacy renegotiation
 542 for OpenSSL clients only. Equivalent to \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR.
 543 Set by default.
 544 .Sp
 545 \&\fBEncryptThenMac\fR: use encrypt-then-mac extension, enabled by
 546 default. Inverse of \fB\s-1SSL_OP_NO_ENCRYPT_THEN_MAC\s0\fR: that is,
 547 \&\fB\-EncryptThenMac\fR is the same as setting \fB\s-1SSL_OP_NO_ENCRYPT_THEN_MAC\s0\fR.
 548 .Sp
 549 \&\fBAllowNoDHEKEX\fR: In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on
 550 resumption. This means that there will be no forward secrecy for the resumed
 551 session. Equivalent to \fB\s-1SSL_OP_ALLOW_NO_DHE_KEX\s0\fR.
 552 .Sp
 553 \&\fBMiddleboxCompat\fR: If set then dummy Change Cipher Spec (\s-1CCS\s0) messages are sent
 554 in TLSv1.3. This has the effect of making TLSv1.3 look more like TLSv1.2 so that
 555 middleboxes that do not understand TLSv1.3 will not drop the connection. This
 556 option is set by default. A future version of OpenSSL may not set this by
 557 default. Equivalent to \fB\s-1SSL_OP_ENABLE_MIDDLEBOX_COMPAT\s0\fR.
 558 .Sp
 559 \&\fBAntiReplay\fR: If set then OpenSSL will automatically detect if a session ticket
 560 has been used more than once, TLSv1.3 has been negotiated, and early data is
 561 enabled on the server. A full handshake is forced if a session ticket is used a
 562 second or subsequent time. This option is set by default and is only used by
 563 servers. Anti-replay measures are required to comply with the TLSv1.3
 564 specification. Some applications may be able to mitigate the replay risks in
 565 other ways and in such cases the built-in OpenSSL functionality is not required.
 566 Disabling anti-replay is equivalent to setting \fB\s-1SSL_OP_NO_ANTI_REPLAY\s0\fR.
 567 .IP "\fBVerifyMode\fR" 4
 568 .IX Item "VerifyMode"
 569 The \fBvalue\fR argument is a comma separated list of flags to set.
 570 .Sp
 571 \&\fBPeer\fR enables peer verification: for clients only.
 572 .Sp
 573 \&\fBRequest\fR requests but does not require a certificate from the client.
 574 Servers only.
 575 .Sp
 576 \&\fBRequire\fR requests and requires a certificate from the client: an error
 577 occurs if the client does not present a certificate. Servers only.
 578 .Sp
 579 \&\fBOnce\fR requests a certificate from a client only on the initial connection:
 580 not when renegotiating. Servers only.
 581 .Sp
 582 \&\fBRequestPostHandshake\fR configures the connection to support requests but does
 583 not require a certificate from the client post-handshake. A certificate will
 584 not be requested during the initial handshake. The server application must
 585 provide a mechanism to request a certificate post-handshake. Servers only.
 586 TLSv1.3 only.
 587 .Sp
 588 \&\fBRequiresPostHandshake\fR configures the connection to support requests and
 589 requires a certificate from the client post-handshake: an error occurs if the
 590 client does not present a certificate. A certificate will not be requested
 591 during the initial handshake. The server application must provide a mechanism
 592 to request a certificate post-handshake. Servers only. TLSv1.3 only.
 593 .IP "\fBClientCAFile\fR, \fBClientCAPath\fR" 4
 594 .IX Item "ClientCAFile, ClientCAPath"
 595 A file or directory of certificates in \s-1PEM\s0 format whose names are used as the
 596 set of acceptable names for client CAs. Servers only. This option is only
 597 supported if certificate operations are permitted.
 598 .SH "SUPPORTED COMMAND TYPES"
 599 .IX Header "SUPPORTED COMMAND TYPES"
 600 The function \fISSL_CONF_cmd_value_type()\fR currently returns one of the following
 601 types:
 602 .IP "\fB\s-1SSL_CONF_TYPE_UNKNOWN\s0\fR" 4
 603 .IX Item "SSL_CONF_TYPE_UNKNOWN"
 604 The \fBcmd\fR string is unrecognised, this return value can be use to flag
 605 syntax errors.
 606 .IP "\fB\s-1SSL_CONF_TYPE_STRING\s0\fR" 4
 607 .IX Item "SSL_CONF_TYPE_STRING"
 608 The value is a string without any specific structure.
 609 .IP "\fB\s-1SSL_CONF_TYPE_FILE\s0\fR" 4
 610 .IX Item "SSL_CONF_TYPE_FILE"
 611 The value is a file name.
 612 .IP "\fB\s-1SSL_CONF_TYPE_DIR\s0\fR" 4
 613 .IX Item "SSL_CONF_TYPE_DIR"
 614 The value is a directory name.
 615 .IP "\fB\s-1SSL_CONF_TYPE_NONE\s0\fR" 4
 616 .IX Item "SSL_CONF_TYPE_NONE"
 617 The value string is not used e.g. a command line option which doesn't take an
 618 argument.
 619 .SH "NOTES"
 620 .IX Header "NOTES"
 621 The order of operations is significant. This can be used to set either defaults
 622 or values which cannot be overridden. For example if an application calls:
 623 .PP
 624 .Vb 2
 625 \& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3");
 626 \& SSL_CONF_cmd(ctx, userparam, uservalue);
 627 .Ve
 628 .PP
 629 it will disable SSLv3 support by default but the user can override it. If
 630 however the call sequence is:
 631 .PP
 632 .Vb 2
 633 \& SSL_CONF_cmd(ctx, userparam, uservalue);
 634 \& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3");
 635 .Ve
 636 .PP
 637 SSLv3 is \fBalways\fR disabled and attempt to override this by the user are
 638 ignored.
 639 .PP
 640 By checking the return code of \fISSL_CONF_cmd()\fR it is possible to query if a
 641 given \fBcmd\fR is recognised, this is useful if \fISSL_CONF_cmd()\fR values are
 642 mixed with additional application specific operations.
 643 .PP
 644 For example an application might call \fISSL_CONF_cmd()\fR and if it returns
 645 \&\-2 (unrecognised command) continue with processing of application specific
 646 commands.
 647 .PP
 648 Applications can also use \fISSL_CONF_cmd()\fR to process command lines though the
 649 utility function \fISSL_CONF_cmd_argv()\fR is normally used instead. One way
 650 to do this is to set the prefix to an appropriate value using
 651 \&\fISSL_CONF_CTX_set1_prefix()\fR, pass the current argument to \fBcmd\fR and the
 652 following argument to \fBvalue\fR (which may be \s-1NULL\s0).
 653 .PP
 654 In this case if the return value is positive then it is used to skip that
 655 number of arguments as they have been processed by \fISSL_CONF_cmd()\fR. If \-2 is
 656 returned then \fBcmd\fR is not recognised and application specific arguments
 657 can be checked instead. If \-3 is returned a required argument is missing
 658 and an error is indicated. If 0 is returned some other error occurred and
 659 this can be reported back to the user.
 660 .PP
 661 The function \fISSL_CONF_cmd_value_type()\fR can be used by applications to
 662 check for the existence of a command or to perform additional syntax
 663 checking or translation of the command value. For example if the return
 664 value is \fB\s-1SSL_CONF_TYPE_FILE\s0\fR an application could translate a relative
 665 pathname to an absolute pathname.
 666 .SH "EXAMPLES"
 667 .IX Header "EXAMPLES"
 668 Set supported signature algorithms:
 669 .PP
 670 .Vb 1
 671 \& SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
 672 .Ve
 673 .PP
 674 There are various ways to select the supported protocols.
 675 .PP
 676 This set the minimum protocol version to TLSv1, and so disables SSLv3.
 677 This is the recommended way to disable protocols.
 678 .PP
 679 .Vb 1
 680 \& SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1");
 681 .Ve
 682 .PP
 683 The following also disables SSLv3:
 684 .PP
 685 .Vb 1
 686 \& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3");
 687 .Ve
 688 .PP
 689 The following will first enable all protocols, and then disable
 690 SSLv3.
 691 If no protocol versions were disabled before this has the same effect as
 692 \&\*(L"\-SSLv3\*(R", but if some versions were disables this will re-enable them before
 693 disabling SSLv3.
 694 .PP
 695 .Vb 1
 696 \& SSL_CONF_cmd(ctx, "Protocol", "ALL,\-SSLv3");
 697 .Ve
 698 .PP
 699 Only enable TLSv1.2:
 700 .PP
 701 .Vb 2
 702 \& SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2");
 703 \& SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2");
 704 .Ve
 705 .PP
 706 This also only enables TLSv1.2:
 707 .PP
 708 .Vb 1
 709 \& SSL_CONF_cmd(ctx, "Protocol", "\-ALL,TLSv1.2");
 710 .Ve
 711 .PP
 712 Disable \s-1TLS\s0 session tickets:
 713 .PP
 714 .Vb 1
 715 \& SSL_CONF_cmd(ctx, "Options", "\-SessionTicket");
 716 .Ve
 717 .PP
 718 Enable compression:
 719 .PP
 720 .Vb 1
 721 \& SSL_CONF_cmd(ctx, "Options", "Compression");
 722 .Ve
 723 .PP
 724 Set supported curves to P\-256, P\-384:
 725 .PP
 726 .Vb 1
 727 \& SSL_CONF_cmd(ctx, "Curves", "P\-256:P\-384");
 728 .Ve
 729 .SH "RETURN VALUES"
 730 .IX Header "RETURN VALUES"
 731 \&\fISSL_CONF_cmd()\fR returns 1 if the value of \fBcmd\fR is recognised and \fBvalue\fR is
 732 \&\fB\s-1NOT\s0\fR used and 2 if both \fBcmd\fR and \fBvalue\fR are used. In other words it
 733 returns the number of arguments processed. This is useful when processing
 734 command lines.
 735 .PP
 736 A return value of \-2 means \fBcmd\fR is not recognised.
 737 .PP
 738 A return value of \-3 means \fBcmd\fR is recognised and the command requires a
 739 value but \fBvalue\fR is \s-1NULL.\s0
 740 .PP
 741 A return code of 0 indicates that both \fBcmd\fR and \fBvalue\fR are valid but an
 742 error occurred attempting to perform the operation: for example due to an
 743 error in the syntax of \fBvalue\fR in this case the error queue may provide
 744 additional information.
 745 .SH "SEE ALSO"
 746 .IX Header "SEE ALSO"
 747 \&\fISSL_CONF_CTX_new\fR\|(3),
 748 \&\fISSL_CONF_CTX_set_flags\fR\|(3),
 749 \&\fISSL_CONF_CTX_set1_prefix\fR\|(3),
 750 \&\fISSL_CONF_CTX_set_ssl_ctx\fR\|(3),
 751 \&\fISSL_CONF_cmd_argv\fR\|(3),
 752 \&\fISSL_CTX_set_options\fR\|(3)
 753 .SH "HISTORY"
 754 .IX Header "HISTORY"
 755 \&\fISSL_CONF_cmd()\fR was first added to OpenSSL 1.0.2
 756 .PP
 757 \&\fB\s-1SSL_OP_NO_SSL2\s0\fR doesn't have effect since 1.1.0, but the macro is retained
 758 for backwards compatibility.
 759 .PP
 760 \&\fB\s-1SSL_CONF_TYPE_NONE\s0\fR was first added to OpenSSL 1.1.0. In earlier versions of
 761 OpenSSL passing a command which didn't take an argument would return
 762 \&\fB\s-1SSL_CONF_TYPE_UNKNOWN\s0\fR.
 763 .PP
 764 \&\fBMinProtocol\fR and \fBMaxProtocol\fR where added in OpenSSL 1.1.0.
 765 .PP
 766 \&\fBAllowNoDHEKEX\fR and \fBPrioritizeChaCha\fR were added in OpenSSL 1.1.1.
 767 .SH "COPYRIGHT"
 768 .IX Header "COPYRIGHT"
 769 Copyright 2012\-2018 The OpenSSL Project Authors. All Rights Reserved.
 770 .PP
 771 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 772 this file except in compliance with the License.  You can obtain a copy
 773 in the file \s-1LICENSE\s0 in the source distribution or at
 774 <https://www.openssl.org/source/license.html>.