doc/man3/SSL_CONF_cmd.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CONF_cmd_value_type,
   6 SSL_CONF_cmd - send configuration command
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/ssl.h>
  11
  12  int SSL_CONF_cmd(SSL_CONF_CTX *ctx, const char *option, const char *value);
  13  int SSL_CONF_cmd_value_type(SSL_CONF_CTX *ctx, const char *option);
  14
  15 =head1 DESCRIPTION
  16
  17 The function SSL_CONF_cmd() performs configuration operation B<option> with
  18 optional parameter B<value> on B<ctx>. Its purpose is to simplify application
  19 configuration of B<SSL_CTX> or B<SSL> structures by providing a common
  20 framework for command line options or configuration files.
  21
  22 SSL_CONF_cmd_value_type() returns the type of value that B<option> refers to.
  23
  24 =head1 SUPPORTED COMMAND LINE COMMANDS
  25
  26 Currently supported B<option> names for command lines (i.e. when the
  27 flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<option> names
  28 are case sensitive. Unless otherwise stated commands can be used by
  29 both clients and servers and the B<value> parameter is not used. The default
  30 prefix for command line commands is B<-> and that is reflected below.
  31
  32 =over 4
  33
  34 =item B<-bugs>
  35
  36 Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
  37
  38 =item B<-no_comp>
  39
  40 Disables support for SSL/TLS compression, same as setting
  41 B<SSL_OP_NO_COMPRESSION>.
  42 As of OpenSSL 1.1.0, compression is off by default.
  43
  44 =item B<-comp>
  45
  46 Enables support for SSL/TLS compression, same as clearing
  47 B<SSL_OP_NO_COMPRESSION>.
  48 This command was introduced in OpenSSL 1.1.0.
  49 As of OpenSSL 1.1.0, compression is off by default.
  50
  51 =item B<-no_ticket>
  52
  53 Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
  54
  55 =item B<-serverpref>
  56
  57 Use server and not client preference order when determining which cipher suite,
  58 signature algorithm or elliptic curve to use for an incoming connection.
  59 Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
  60
  61 =item B<-legacyrenegotiation>
  62
  63 permits the use of unsafe legacy renegotiation. Equivalent to setting
  64 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
  65
  66 =item B<-no_renegotiation>
  67
  68 Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
  69 B<SSL_OP_NO_RENEGOTIATION>.
  70
  71 =item B<-no_resumption_on_reneg>
  72
  73 set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers.
  74
  75 =item B<-legacy_server_connect>, B<-no_legacy_server_connect>
  76
  77 permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
  78 clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
  79 Set by default.
  80
  81 =item B<-prioritize_chacha>
  82
  83 Prioritize ChaCha ciphers when the client has a ChaCha20 cipher at the top of
  84 its preference list. This usually indicates a client without AES hardware
  85 acceleration (e.g. mobile) is in use. Equivalent to B<SSL_OP_PRIORITIZE_CHACHA>.
  86 Only used by servers. Requires B<-serverpref>.
  87
  88 =item B<-allow_no_dhe_kex>
  89
  90 In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means
  91 that there will be no forward secrecy for the resumed session.
  92
  93 =item B<-strict>
  94
  95 enables strict mode protocol handling. Equivalent to setting
  96 B<SSL_CERT_FLAG_TLS_STRICT>.
  97
  98 =item B<-sigalgs> I<algs>
  99
 100 This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
 101 For clients this value is used directly for the supported signature
 102 algorithms extension. For servers it is used to determine which signature
 103 algorithms to support.
 104
 105 The B<algs> argument should be a colon separated list of signature
 106 algorithms in order of decreasing preference of the form B<algorithm+hash>
 107 or B<signature_scheme>. B<algorithm> is one of B<RSA>, B<DSA> or B<ECDSA> and
 108 B<hash> is a supported algorithm OID short name such as B<SHA1>, B<SHA224>,
 109 B<SHA256>, B<SHA384> of B<SHA512>.  Note: algorithm and hash names are case
 110 sensitive.  B<signature_scheme> is one of the signature schemes defined in
 111 TLSv1.3, specified using the IETF name, e.g., B<ecdsa_secp256r1_sha256>,
 112 B<ed25519>, or B<rsa_pss_pss_sha256>.
 113
 114 If this option is not set then all signature algorithms supported by the
 115 OpenSSL library are permissible.
 116
 117 Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
 118 using B<RSA> as the B<algorithm> or by using one of the B<rsa_pkcs1_*>
 119 identifiers) are ignored in TLSv1.3 and will not be negotiated.
 120
 121 =item B<-client_sigalgs> I<algs>
 122
 123 This sets the supported signature algorithms associated with client
 124 authentication for TLSv1.2 and TLSv1.3.  For servers the B<algs> is used
 125 in the B<signature_algorithms> field of a B<CertificateRequest> message.
 126 For clients it is used to determine which signature algorithm to use with
 127 the client certificate.  If a server does not request a certificate this
 128 option has no effect.
 129
 130 The syntax of B<algs> is identical to B<-sigalgs>. If not set, then the
 131 value set for B<-sigalgs> will be used instead.
 132
 133 =item B<-groups> I<groups>
 134
 135 This sets the supported groups. For clients, the groups are sent using
 136 the supported groups extension. For servers, it is used to determine which
 137 group to use. This setting affects groups used for signatures (in TLSv1.2
 138 and earlier) and key exchange. The first group listed will also be used
 139 for the B<key_share> sent by a client in a TLSv1.3 B<ClientHello>.
 140
 141 The B<groups> argument is a colon separated list of groups. The group can
 142 be either the B<NIST> name (e.g. B<P-256>), some other commonly used name
 143 where applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
 144 (e.g. B<prime256v1>). Group names are case sensitive. The list should be
 145 in order of preference with the most preferred group first.
 146
 147 Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
 148 B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
 149 B<ffdhe8192>.
 150
 151 =item B<-curves> I<groups>
 152
 153 This is a synonym for the B<-groups> command.
 154
 155 =item B<-named_curve> I<curve>
 156
 157 This sets the temporary curve used for ephemeral ECDH modes. Only used
 158 by servers.
 159
 160 The B<groups> argument is a curve name or the special value B<auto> which
 161 picks an appropriate curve based on client and server preferences. The
 162 curve can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
 163 (e.g. B<prime256v1>). Curve names are case sensitive.
 164
 165 =item B<-cipher> I<ciphers>
 166
 167 Sets the TLSv1.2 and below ciphersuite list to B<ciphers>. This list will be
 168 combined with any configured TLSv1.3 ciphersuites. Note: syntax checking
 169 of B<ciphers> is currently not performed unless a B<SSL> or B<SSL_CTX>
 170 structure is associated with B<ctx>.
 171
 172 =item B<-ciphersuites> I<1.3ciphers>
 173
 174 Sets the available ciphersuites for TLSv1.3 to value. This is a
 175 colon-separated list of TLSv1.3 ciphersuite names in order of preference. This
 176 list will be combined any configured TLSv1.2 and below ciphersuites.
 177 See L<openssl-ciphers(1)> for more information.
 178
 179 =item B<-min_protocol> I<minprot>, B<-max_protocol> I<maxprot>
 180
 181 Sets the minimum and maximum supported protocol.
 182 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
 183 B<TLSv1.2>, B<TLSv1.3> for TLS; B<DTLSv1>, B<DTLSv1.2> for DTLS, and B<None>
 184 for no limit.
 185 If either the lower or upper bound is not specified then only the other bound
 186 applies, if specified.
 187 If your application supports both TLS and DTLS you can specify any of these
 188 options twice, once with a bound for TLS and again with an appropriate bound
 189 for DTLS.
 190 To restrict the supported protocol versions use these commands rather than the
 191 deprecated alternative commands below.
 192
 193 =item B<-record_padding> I<padding>
 194
 195 Attempts to pad TLSv1.3 records so that they are a multiple of B<padding>
 196 in length on send. A B<padding> of 0 or 1 turns off padding. Otherwise,
 197 the B<padding> must be >1 or <=16384.
 198
 199 =item B<-debug_broken_protocol>
 200
 201 Ignored.
 202
 203 =item B<-no_middlebox>
 204
 205 Turn off "middlebox compatibility", as described below.
 206
 207 =back
 208
 209 =head2 Additional Options
 210
 211 The following options are accepted by SSL_CONF_cmd(), but are not
 212 processed by the OpenSSL commands.
 213
 214 =over 4
 215
 216 =item B<-cert> I<file>
 217
 218 Attempts to use B<file> as the certificate for the appropriate context. It
 219 currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
 220 structure is set or SSL_use_certificate_file() with filetype PEM if an
 221 B<SSL> structure is set. This option is only supported if certificate
 222 operations are permitted.
 223
 224 =item B<-key> I<file>
 225
 226 Attempts to use B<file> as the private key for the appropriate context. This
 227 option is only supported if certificate operations are permitted. Note:
 228 if no B<-key> option is set then a private key is not loaded unless the
 229 flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
 230
 231 =item B<-dhparam> I<file>
 232
 233 Attempts to use B<file> as the set of temporary DH parameters for
 234 the appropriate context. This option is only supported if certificate
 235 operations are permitted.
 236
 237 =item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
 238
 239 Disables protocol support for SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3 by
 240 setting the corresponding options B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>,
 241 B<SSL_OP_NO_TLSv1_1>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3>
 242 respectively. These options are deprecated, use B<-min_protocol> and
 243 B<-max_protocol> instead.
 244
 245 =item B<-anti_replay>, B<-no_anti_replay>
 246
 247 Switches replay protection, on or off respectively. With replay protection on,
 248 OpenSSL will automatically detect if a session ticket has been used more than
 249 once, TLSv1.3 has been negotiated, and early data is enabled on the server. A
 250 full handshake is forced if a session ticket is used a second or subsequent
 251 time. Anti-Replay is on by default unless overridden by a configuration file and
 252 is only used by servers. Anti-replay measures are required for compliance with
 253 the TLSv1.3 specification. Some applications may be able to mitigate the replay
 254 risks in other ways and in such cases the built-in OpenSSL functionality is not
 255 required. Switching off anti-replay is equivalent to B<SSL_OP_NO_ANTI_REPLAY>.
 256
 257 =back
 258
 259 =head1 SUPPORTED CONFIGURATION FILE COMMANDS
 260
 261 Currently supported B<option> names for configuration files (i.e., when the
 262 flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
 263 B<option> names are case insensitive so B<signaturealgorithms> is recognised
 264 as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
 265 are also case insensitive.
 266
 267 Note: the command prefix (if set) alters the recognised B<option> values.
 268
 269 =over 4
 270
 271 =item B<CipherString>
 272
 273 Sets the ciphersuite list for TLSv1.2 and below to B<value>. This list will be
 274 combined with any configured TLSv1.3 ciphersuites. Note: syntax
 275 checking of B<value> is currently not performed unless an B<SSL> or B<SSL_CTX>
 276 structure is associated with B<ctx>.
 277
 278 =item B<Ciphersuites>
 279
 280 Sets the available ciphersuites for TLSv1.3 to B<value>. This is a
 281 colon-separated list of TLSv1.3 ciphersuite names in order of preference. This
 282 list will be combined any configured TLSv1.2 and below ciphersuites.
 283 See L<openssl-ciphers(1)> for more information.
 284
 285 =item B<Certificate>
 286
 287 Attempts to use the file B<value> as the certificate for the appropriate
 288 context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
 289 structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
 290 structure is set. This option is only supported if certificate operations
 291 are permitted.
 292
 293 =item B<PrivateKey>
 294
 295 Attempts to use the file B<value> as the private key for the appropriate
 296 context. This option is only supported if certificate operations
 297 are permitted. Note: if no B<PrivateKey> option is set then a private key is
 298 not loaded unless the B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
 299
 300 =item B<ChainCAFile>, B<ChainCAPath>, B<VerifyCAFile>, B<VerifyCAPath>
 301
 302 These options indicate a file or directory used for building certificate
 303 chains or verifying certificate chains. These options are only supported
 304 if certificate operations are permitted.
 305
 306 =item B<RequestCAFile>
 307
 308 This option indicates a file containing a set of certificates in PEM form.
 309 The subject names of the certificates are sent to the peer in the
 310 B<certificate_authorities> extension for TLS 1.3 (in ClientHello or
 311 CertificateRequest) or in a certificate request for previous versions or
 312 TLS.
 313
 314 =item B<ServerInfoFile>
 315
 316 Attempts to use the file B<value> in the "serverinfo" extension using the
 317 function SSL_CTX_use_serverinfo_file.
 318
 319 =item B<DHParameters>
 320
 321 Attempts to use the file B<value> as the set of temporary DH parameters for
 322 the appropriate context. This option is only supported if certificate
 323 operations are permitted.
 324
 325 =item B<RecordPadding>
 326
 327 Attempts to pad TLSv1.3 records so that they are a multiple of B<value> in
 328 length on send. A B<value> of 0 or 1 turns off padding. Otherwise, the
 329 B<value> must be >1 or <=16384.
 330
 331 =item B<SignatureAlgorithms>
 332
 333 This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
 334 For clients this
 335 value is used directly for the supported signature algorithms extension. For
 336 servers it is used to determine which signature algorithms to support.
 337
 338 The B<value> argument should be a colon separated list of signature algorithms
 339 in order of decreasing preference of the form B<algorithm+hash> or
 340 B<signature_scheme>. B<algorithm>
 341 is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
 342 OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
 343 Note: algorithm and hash names are case sensitive.
 344 B<signature_scheme> is one of the signature schemes defined in TLSv1.3,
 345 specified using the IETF name, e.g., B<ecdsa_secp256r1_sha256>, B<ed25519>,
 346 or B<rsa_pss_pss_sha256>.
 347
 348 If this option is not set then all signature algorithms supported by the
 349 OpenSSL library are permissible.
 350
 351 Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by
 352 using B<RSA> as the B<algorithm> or by using one of the B<rsa_pkcs1_*>
 353 identifiers) are ignored in TLSv1.3 and will not be negotiated.
 354
 355 =item B<ClientSignatureAlgorithms>
 356
 357 This sets the supported signature algorithms associated with client
 358 authentication for TLSv1.2 and TLSv1.3.
 359 For servers the value is used in the
 360 B<signature_algorithms> field of a B<CertificateRequest> message.
 361 For clients it is
 362 used to determine which signature algorithm to use with the client certificate.
 363 If a server does not request a certificate this option has no effect.
 364
 365 The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
 366 the value set for B<SignatureAlgorithms> will be used instead.
 367
 368 =item B<Groups>
 369
 370 This sets the supported groups. For clients, the groups are
 371 sent using the supported groups extension. For servers, it is used
 372 to determine which group to use. This setting affects groups used for
 373 signatures (in TLSv1.2 and earlier) and key exchange. The first group listed
 374 will also be used for the B<key_share> sent by a client in a TLSv1.3
 375 B<ClientHello>.
 376
 377 The B<value> argument is a colon separated list of groups. The group can be
 378 either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
 379 applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
 380 (e.g. B<prime256v1>). Group names are case sensitive. The list should be in
 381 order of preference with the most preferred group first.
 382
 383 Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
 384 B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
 385 B<ffdhe8192>.
 386
 387 =item B<Curves>
 388
 389 This is a synonym for the "Groups" command.
 390
 391 =item B<MinProtocol>
 392
 393 This sets the minimum supported SSL, TLS or DTLS version.
 394
 395 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
 396 B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
 397 The SSL and TLS bounds apply only to TLS-based contexts, while the DTLS bounds
 398 apply only to DTLS-based contexts.
 399 The command can be repeated with one instance setting a TLS bound, and the
 400 other setting a DTLS bound.
 401 The value B<None> applies to both types of contexts and disables the limits.
 402
 403 =item B<MaxProtocol>
 404
 405 This sets the maximum supported SSL, TLS or DTLS version.
 406
 407 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
 408 B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
 409 The SSL and TLS bounds apply only to TLS-based contexts, while the DTLS bounds
 410 apply only to DTLS-based contexts.
 411 The command can be repeated with one instance setting a TLS bound, and the
 412 other setting a DTLS bound.
 413 The value B<None> applies to both types of contexts and disables the limits.
 414
 415 =item B<Protocol>
 416
 417 This can be used to enable or disable certain versions of the SSL,
 418 TLS or DTLS protocol.
 419
 420 The B<value> argument is a comma separated list of supported protocols
 421 to enable or disable.
 422 If a protocol is preceded by B<-> that version is disabled.
 423
 424 All protocol versions are enabled by default.
 425 You need to disable at least one protocol version for this setting have any
 426 effect.
 427 Only enabling some protocol versions does not disable the other protocol
 428 versions.
 429
 430 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
 431 B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
 432 The special value B<ALL> refers to all supported versions.
 433
 434 This can't enable protocols that are disabled using B<MinProtocol>
 435 or B<MaxProtocol>, but can disable protocols that are still allowed
 436 by them.
 437
 438 The B<Protocol> command is fragile and deprecated; do not use it.
 439 Use B<MinProtocol> and B<MaxProtocol> instead.
 440 If you do use B<Protocol>, make sure that the resulting range of enabled
 441 protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make
 442 sure to also leave TLS 1.1 enabled.
 443
 444 =item B<Options>
 445
 446 The B<value> argument is a comma separated list of various flags to set.
 447 If a flag string is preceded B<-> it is disabled.
 448 See the L<SSL_CTX_set_options(3)> function for more details of
 449 individual options.
 450
 451 Each option is listed below. Where an operation is enabled by default
 452 the B<-flag> syntax is needed to disable it.
 453
 454 B<SessionTicket>: session ticket support, enabled by default. Inverse of
 455 B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting
 456 B<SSL_OP_NO_TICKET>.
 457
 458 B<Compression>: SSL/TLS compression support, enabled by default. Inverse
 459 of B<SSL_OP_NO_COMPRESSION>.
 460
 461 B<EmptyFragments>: use empty fragments as a countermeasure against a
 462 SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It
 463 is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>.
 464
 465 B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>.
 466
 467 B<DHSingle>: enable single use DH keys, set by default. Inverse of
 468 B<SSL_OP_DH_SINGLE>. Only used by servers.
 469
 470 B<ECDHSingle>: enable single use ECDH keys, set by default. Inverse of
 471 B<SSL_OP_ECDH_SINGLE>. Only used by servers.
 472
 473 B<ServerPreference>: use server and not client preference order when
 474 determining which cipher suite, signature algorithm or elliptic curve
 475 to use for an incoming connection.  Equivalent to
 476 B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
 477
 478 B<PrioritizeChaCha>: prioritizes ChaCha ciphers when the client has a
 479 ChaCha20 cipher at the top of its preference list. This usually indicates
 480 a mobile client is in use. Equivalent to B<SSL_OP_PRIORITIZE_CHACHA>.
 481 Only used by servers.
 482
 483 B<NoResumptionOnRenegotiation>: set
 484 B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers.
 485
 486 B<NoRenegotiation>: disables all attempts at renegotiation in TLSv1.2 and
 487 earlier, same as setting B<SSL_OP_NO_RENEGOTIATION>.
 488
 489 B<UnsafeLegacyRenegotiation>: permits the use of unsafe legacy renegotiation.
 490 Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
 491
 492 B<UnsafeLegacyServerConnect>: permits the use of unsafe legacy renegotiation
 493 for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
 494 Set by default.
 495
 496 B<EncryptThenMac>: use encrypt-then-mac extension, enabled by
 497 default. Inverse of B<SSL_OP_NO_ENCRYPT_THEN_MAC>: that is,
 498 B<-EncryptThenMac> is the same as setting B<SSL_OP_NO_ENCRYPT_THEN_MAC>.
 499
 500 B<AllowNoDHEKEX>: In TLSv1.3 allow a non-(ec)dhe based key exchange mode on
 501 resumption. This means that there will be no forward secrecy for the resumed
 502 session. Equivalent to B<SSL_OP_ALLOW_NO_DHE_KEX>.
 503
 504 B<MiddleboxCompat>: If set then dummy Change Cipher Spec (CCS) messages are sent
 505 in TLSv1.3. This has the effect of making TLSv1.3 look more like TLSv1.2 so that
 506 middleboxes that do not understand TLSv1.3 will not drop the connection. This
 507 option is set by default. A future version of OpenSSL may not set this by
 508 default. Equivalent to B<SSL_OP_ENABLE_MIDDLEBOX_COMPAT>.
 509
 510 B<AntiReplay>: If set then OpenSSL will automatically detect if a session ticket
 511 has been used more than once, TLSv1.3 has been negotiated, and early data is
 512 enabled on the server. A full handshake is forced if a session ticket is used a
 513 second or subsequent time. This option is set by default and is only used by
 514 servers. Anti-replay measures are required to comply with the TLSv1.3
 515 specification. Some applications may be able to mitigate the replay risks in
 516 other ways and in such cases the built-in OpenSSL functionality is not required.
 517 Disabling anti-replay is equivalent to setting B<SSL_OP_NO_ANTI_REPLAY>.
 518
 519 B<ExtendedMasterSecret>: use extended master secret extension, enabled by
 520 default. Inverse of B<SSL_OP_NO_EXTENDED_MASTER_SECRET>: that is,
 521 B<-ExtendedMasterSecret> is the same as setting B<SSL_OP_NO_EXTENDED_MASTER_SECRET>.
 522
 523 B<CANames>: use CA names extension, enabled by
 524 default. Inverse of B<SSL_OP_DISABLE_TLSEXT_CA_NAMES>: that is,
 525 B<-CANames> is the same as setting B<SSL_OP_DISABLE_TLSEXT_CA_NAMES>.
 526
 527 =item B<VerifyMode>
 528
 529 The B<value> argument is a comma separated list of flags to set.
 530
 531 B<Peer> enables peer verification: for clients only.
 532
 533 B<Request> requests but does not require a certificate from the client.
 534 Servers only.
 535
 536 B<Require> requests and requires a certificate from the client: an error
 537 occurs if the client does not present a certificate. Servers only.
 538
 539 B<Once> requests a certificate from a client only on the initial connection:
 540 not when renegotiating. Servers only.
 541
 542 B<RequestPostHandshake> configures the connection to support requests but does
 543 not require a certificate from the client post-handshake. A certificate will
 544 not be requested during the initial handshake. The server application must
 545 provide a mechanism to request a certificate post-handshake. Servers only.
 546 TLSv1.3 only.
 547
 548 B<RequiresPostHandshake> configures the connection to support requests and
 549 requires a certificate from the client post-handshake: an error occurs if the
 550 client does not present a certificate. A certificate will not be requested
 551 during the initial handshake. The server application must provide a mechanism
 552 to request a certificate post-handshake. Servers only. TLSv1.3 only.
 553
 554 =item B<ClientCAFile>, B<ClientCAPath>
 555
 556 A file or directory of certificates in PEM format whose names are used as the
 557 set of acceptable names for client CAs. Servers only. This option is only
 558 supported if certificate operations are permitted.
 559
 560 =back
 561
 562 =head1 SUPPORTED COMMAND TYPES
 563
 564 The function SSL_CONF_cmd_value_type() currently returns one of the following
 565 types:
 566
 567 =over 4
 568
 569 =item B<SSL_CONF_TYPE_UNKNOWN>
 570
 571 The B<option> string is unrecognised, this return value can be use to flag
 572 syntax errors.
 573
 574 =item B<SSL_CONF_TYPE_STRING>
 575
 576 The value is a string without any specific structure.
 577
 578 =item B<SSL_CONF_TYPE_FILE>
 579
 580 The value is a filename.
 581
 582 =item B<SSL_CONF_TYPE_DIR>
 583
 584 The value is a directory name.
 585
 586 =item B<SSL_CONF_TYPE_NONE>
 587
 588 The value string is not used e.g. a command line option which doesn't take an
 589 argument.
 590
 591 =back
 592
 593 =head1 NOTES
 594
 595 The order of operations is significant. This can be used to set either defaults
 596 or values which cannot be overridden. For example if an application calls:
 597
 598  SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
 599  SSL_CONF_cmd(ctx, userparam, uservalue);
 600
 601 it will disable SSLv3 support by default but the user can override it. If
 602 however the call sequence is:
 603
 604  SSL_CONF_cmd(ctx, userparam, uservalue);
 605  SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
 606
 607 SSLv3 is B<always> disabled and attempt to override this by the user are
 608 ignored.
 609
 610 By checking the return code of SSL_CONF_cmd() it is possible to query if a
 611 given B<option> is recognised, this is useful if SSL_CONF_cmd() values are
 612 mixed with additional application specific operations.
 613
 614 For example an application might call SSL_CONF_cmd() and if it returns
 615 -2 (unrecognised command) continue with processing of application specific
 616 commands.
 617
 618 Applications can also use SSL_CONF_cmd() to process command lines though the
 619 utility function SSL_CONF_cmd_argv() is normally used instead. One way
 620 to do this is to set the prefix to an appropriate value using
 621 SSL_CONF_CTX_set1_prefix(), pass the current argument to B<option> and the
 622 following argument to B<value> (which may be NULL).
 623
 624 In this case if the return value is positive then it is used to skip that
 625 number of arguments as they have been processed by SSL_CONF_cmd(). If -2 is
 626 returned then B<option> is not recognised and application specific arguments
 627 can be checked instead. If -3 is returned a required argument is missing
 628 and an error is indicated. If 0 is returned some other error occurred and
 629 this can be reported back to the user.
 630
 631 The function SSL_CONF_cmd_value_type() can be used by applications to
 632 check for the existence of a command or to perform additional syntax
 633 checking or translation of the command value. For example if the return
 634 value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
 635 pathname to an absolute pathname.
 636
 637 =head1 RETURN VALUES
 638
 639 SSL_CONF_cmd() returns 1 if the value of B<option> is recognised and B<value> is
 640 B<NOT> used and 2 if both B<option> and B<value> are used. In other words it
 641 returns the number of arguments processed. This is useful when processing
 642 command lines.
 643
 644 A return value of -2 means B<option> is not recognised.
 645
 646 A return value of -3 means B<option> is recognised and the command requires a
 647 value but B<value> is NULL.
 648
 649 A return code of 0 indicates that both B<option> and B<value> are valid but an
 650 error occurred attempting to perform the operation: for example due to an
 651 error in the syntax of B<value> in this case the error queue may provide
 652 additional information.
 653
 654 =head1 EXAMPLES
 655
 656 Set supported signature algorithms:
 657
 658  SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
 659
 660 There are various ways to select the supported protocols.
 661
 662 This set the minimum protocol version to TLSv1, and so disables SSLv3.
 663 This is the recommended way to disable protocols.
 664
 665  SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1");
 666
 667 The following also disables SSLv3:
 668
 669  SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
 670
 671 The following will first enable all protocols, and then disable
 672 SSLv3.
 673 If no protocol versions were disabled before this has the same effect as
 674 "-SSLv3", but if some versions were disables this will re-enable them before
 675 disabling SSLv3.
 676
 677  SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3");
 678
 679 Only enable TLSv1.2:
 680
 681  SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2");
 682  SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2");
 683
 684 This also only enables TLSv1.2:
 685
 686  SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
 687
 688 Disable TLS session tickets:
 689
 690  SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
 691
 692 Enable compression:
 693
 694  SSL_CONF_cmd(ctx, "Options", "Compression");
 695
 696 Set supported curves to P-256, P-384:
 697
 698  SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
 699
 700 =head1 SEE ALSO
 701
 702 L<ssl(7)>,
 703 L<SSL_CONF_CTX_new(3)>,
 704 L<SSL_CONF_CTX_set_flags(3)>,
 705 L<SSL_CONF_CTX_set1_prefix(3)>,
 706 L<SSL_CONF_CTX_set_ssl_ctx(3)>,
 707 L<SSL_CONF_cmd_argv(3)>,
 708 L<SSL_CTX_set_options(3)>
 709
 710 =head1 HISTORY
 711
 712 The SSL_CONF_cmd() function was added in OpenSSL 1.0.2.
 713
 714 The B<SSL_OP_NO_SSL2> option doesn't have effect since 1.1.0, but the macro
 715 is retained for backwards compatibility.
 716
 717 The B<SSL_CONF_TYPE_NONE> was added in OpenSSL 1.1.0. In earlier versions of
 718 OpenSSL passing a command which didn't take an argument would return
 719 B<SSL_CONF_TYPE_UNKNOWN>.
 720
 721 B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0.
 722
 723 B<AllowNoDHEKEX> and B<PrioritizeChaCha> were added in OpenSSL 1.1.1.
 724
 725 =head1 COPYRIGHT
 726
 727 Copyright 2012-2020 The OpenSSL Project Authors. All Rights Reserved.
 728
 729 Licensed under the Apache License 2.0 (the "License").  You may not use
 730 this file except in compliance with the License.  You can obtain a copy
 731 in the file LICENSE in the source distribution or at
 732 L<https://www.openssl.org/source/license.html>.
 733
 734 =cut