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