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