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