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