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