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