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