17 The function SSL_CONF_cmd() performs configuration operation B<option> with
18 optional parameter B<value> on B<ctx>. Its purpose is to simplify application
19 configuration of B<SSL_CTX> or B<SSL> structures by providing a common
22 SSL_CONF_cmd_value_type() returns the type of value that B<option> refers to.
26 Currently supported B<option> names for command lines (i.e. when the
27 flag B<SSL_CONF_FLAG_CMDLINE> is set) are listed below. Note: all B<option>
29 both clients and servers and the B<value> parameter is not used. The default
30 prefix for command line commands is B<-> and that is reflected below.
34 =item B<-bugs>
36 Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
38 =item B<-no_comp>
41 B<SSL_OP_NO_COMPRESSION>.
44 =item B<-comp>
47 B<SSL_OP_NO_COMPRESSION>.
54 =item B<-no_ticket>
56 Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
58 =item B<-serverpref>
62 Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
64 =item B<-client_renegotiation>
67 setting B<SSL_OP_ALLOW_CLIENT_RENEGOTIATION>.
70 =item B<-legacy_renegotiation>
73 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
75 =item B<-no_renegotiation>
78 B<SSL_OP_NO_RENEGOTIATION>.
80 =item B<-no_resumption_on_reneg>
82 Sets B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION>. Only used by servers.
84 =item B<-legacy_server_connect>, B<-no_legacy_server_connect>
87 clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
89 =item B<-prioritize_chacha>
93 acceleration (e.g. mobile) is in use. Equivalent to B<SSL_OP_PRIORITIZE_CHACHA>.
94 Only used by servers. Requires B<-serverpref>.
96 =item B<-allow_no_dhe_kex>
101 =item B<-prefer_no_dhe_kex>
104 exchange mode over an (ec)dhe based one. Requires B<-allow_no_dhe_kex>.
105 Equivalent to B<SSL_OP_PREFER_NO_DHE_KEX>. Only used by servers.
107 =item B<-strict>
110 B<SSL_CERT_FLAG_TLS_STRICT>.
112 =item B<-sigalgs> I<algs>
119 The B<algs> argument should be a colon separated list of signature
120 algorithms in order of decreasing preference of the form B<algorithm+hash>
121 or B<signature_scheme>. For the default providers shipped with OpenSSL,
122 B<algorithm> is one of B<RSA>, B<DSA> or B<ECDSA> and
123 B<hash> is a supported algorithm OID short name such as B<SHA1>, B<SHA224>,
124 B<SHA256>, B<SHA384> or B<SHA512>.  Note: algorithm and hash names are case
125 sensitive.  B<signature_scheme> is one of the signature schemes defined in
126 TLSv1.3, specified using the IETF name, e.g., B<ecdsa_secp256r1_sha256>,
127 B<ed25519>, or B<rsa_pss_pss_sha256>. Additional providers may make available
135 using B<RSA> as the B<algorithm> or by using one of the B<rsa_pkcs1_*>
138 =item B<-client_sigalgs> I<algs>
141 authentication for TLSv1.2 and TLSv1.3.  For servers the B<algs> is used
142 in the B<signature_algorithms> field of a B<CertificateRequest> message.
147 The syntax of B<algs> is identical to B<-sigalgs>. If not set, then the
148 value set for B<-sigalgs> will be used instead.
150 =item B<-groups> I<groups>
156 for the B<key_share> sent by a client in a TLSv1.3 B<ClientHello>.
158 The B<groups> argument is a colon separated list of groups. The group can
159 be either the B<NIST> name (e.g. B<P-256>), some other commonly used name
160 where 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
164 Groups for B<TLSv1.3> in the default provider are B<P-256>, B<P-384>,
165 B<P-521>, B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>,
166 B<ffdhe6144>, B<ffdhe8192>, B<brainpoolP256r1tls13>,
167 B<brainpoolP384r1tls13> and B<brainpoolP512r1tls13>.
171 =item B<-curves> I<groups>
173 This is a synonym for the B<-groups> command.
175 =item B<-named_curve> I<curve>
180 =item B<-tx_cert_comp>
184 =item B<-no_tx_cert_comp>
188 =item B<-rx_cert_comp>
192 =item B<-no_rx_cert_comp>
196 =item B<-comp>
198 The B<groups> argument is a curve name or the special value B<auto> which
200 curve can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
201 (e.g. B<prime256v1>). Curve names are case sensitive.
203 =item B<-cipher> I<ciphers>
205 Sets the TLSv1.2 and below ciphersuite list to B<ciphers>. This list will be
207 of B<ciphers> is currently not performed unless a B<SSL> or B<SSL_CTX>
208 structure is associated with B<ctx>.
210 =item B<-ciphersuites> I<1.3ciphers>
217 =item B<-min_protocol> I<minprot>, B<-max_protocol> I<maxprot>
220 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
221 B<TLSv1.2>, B<TLSv1.3> for TLS; B<DTLSv1>, B<DTLSv1.2> for DTLS, and B<None>
231 =item B<-record_padding> I<padding>
233 Controls use of TLSv1.3 record layer padding.  B<padding> is a string of the
243 =item B<-debug_broken_protocol>
247 =item B<-no_middlebox>
260 =item B<-cert> I<file>
262 Attempts to use B<file> as the certificate for the appropriate context. It
263 currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
265 B<SSL> structure is set. This option is only supported if certificate
268 =item B<-key> I<file>
270 Attempts to use B<file> as the private key for the appropriate context. This
272 if no B<-key> option is set then a private key is not loaded unless the
273 flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
275 =item B<-dhparam> I<file>
277 Attempts to use B<file> as the set of temporary DH parameters for
281 =item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
284 setting the corresponding options B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>,
285 B<SSL_OP_NO_TLSv1_1>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3>
286 respectively. These options are deprecated, use B<-min_protocol> and
287 B<-max_protocol> instead.
289 =item B<-anti_replay>, B<-no_anti_replay>
299 required. Switching off anti-replay is equivalent to B<SSL_OP_NO_ANTI_REPLAY>.
305 Currently supported B<option> names for configuration files (i.e., when the
306 flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
307 B<option> names are case insensitive so B<signaturealgorithms> is recognised
308 as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
311 Note: the command prefix (if set) alters the recognised B<option> values.
315 =item B<CipherString>
317 Sets the ciphersuite list for TLSv1.2 and below to B<value>. This list will be
319 checking of B<value> is currently not performed unless an B<SSL> or B<SSL_CTX>
320 structure is associated with B<ctx>.
322 =item B<Ciphersuites>
324 Sets the available ciphersuites for TLSv1.3 to B<value>. This is a
329 =item B<Certificate>
331 Attempts to use the file B<value> as the certificate for the appropriate
332 context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
333 structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
337 =item B<PrivateKey>
339 Attempts to use the file B<value> as the private key for the appropriate
341 are permitted. Note: if no B<PrivateKey> option is set then a private key is
342 not loaded unless the B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
344 =item B<ChainCAFile>, B<ChainCAPath>, B<VerifyCAFile>, B<VerifyCAPath>
350 =item B<RequestCAFile>
354 B<certificate_authorities> extension for TLS 1.3 (in ClientHello or
358 =item B<ServerInfoFile>
360 Attempts to use the file B<value> in the "serverinfo" extension using the
363 =item B<DHParameters>
365 Attempts to use the file B<value> as the set of temporary DH parameters for
369 =item B<RecordPadding>
371 Controls use of TLSv1.3 record layer padding.  B<value> is a string of the form
381 =item B<SignatureAlgorithms>
388 The B<value> argument should be a colon separated list of signature algorithms
389 in order of decreasing preference of the form B<algorithm+hash> or
390 B<signature_scheme>. For the default providers shipped with OpenSSL,
391 B<algorithm> is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported
392 algorithm OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384>
393 or B<SHA512>.
395 B<signature_scheme> is one of the signature schemes defined in TLSv1.3,
396 specified using the IETF name, e.g., B<ecdsa_secp256r1_sha256>, B<ed25519>,
397 or B<rsa_pss_pss_sha256>.
405 using B<RSA> as the B<algorithm> or by using one of the B<rsa_pkcs1_*>
408 =item B<ClientSignatureAlgorithms>
413 B<signature_algorithms> field of a B<CertificateRequest> message.
418 The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
419 the value set for B<SignatureAlgorithms> will be used instead.
421 =item B<Groups>
427 will also be used for the B<key_share> sent by a client in a TLSv1.3
428 B<ClientHello>.
430 The B<value> argument is a colon separated list of groups. The group can be
431 either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
432 applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
433 (e.g. B<prime256v1>). Group names are case sensitive. The list should be in
436 Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
437 B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
438 B<ffdhe8192>.
440 =item B<Curves>
444 =item B<MinProtocol>
448 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
449 B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
454 The value B<None> applies to both types of contexts and disables the limits.
456 =item B<MaxProtocol>
460 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
461 B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
466 The value B<None> applies to both types of contexts and disables the limits.
468 =item B<Protocol>
473 The B<value> argument is a comma separated list of supported protocols
475 If a protocol is preceded by B<-> that version is disabled.
483 Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
484 B<TLSv1.2>, B<TLSv1.3>, B<DTLSv1> and B<DTLSv1.2>.
485 The special value B<ALL> refers to all supported versions.
487 This can't enable protocols that are disabled using B<MinProtocol>
488 or B<MaxProtocol>, but can disable protocols that are still allowed
491 The B<Protocol> command is fragile and deprecated; do not use it.
492 Use B<MinProtocol> and B<MaxProtocol> instead.
493 If you do use B<Protocol>, make sure that the resulting range of enabled
497 =item B<Options>
499 The B<value> argument is a comma separated list of various flags to set.
500 If a flag string is preceded B<-> it is disabled.
505 the B<-flag> syntax is needed to disable it.
507 B<SessionTicket>: session ticket support, enabled by default. Inverse of
508 B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting
509 B<SSL_OP_NO_TICKET>.
511 B<Compression>: SSL/TLS compression support, disabled by default. Inverse
512 of B<SSL_OP_NO_COMPRESSION>.
514 B<EmptyFragments>: use empty fragments as a countermeasure against a
516 is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>.
518 B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>.
520 B<DHSingle>: enable single use DH keys, set by default. Inverse of
521 B<SSL_OP_DH_SINGLE>. Only used by servers.
523 B<ECDHSingle>: enable single use ECDH keys, set by default. Inverse of
524 B<SSL_OP_ECDH_SINGLE>. Only used by servers.
526 B<ServerPreference>: use server and not client preference order when
529 B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
531 B<PrioritizeChaCha>: prioritizes ChaCha ciphers when the client has a
533 a mobile client is in use. Equivalent to B<SSL_OP_PRIORITIZE_CHACHA>.
536 B<NoResumptionOnRenegotiation>: set
537 B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers.
539 B<NoRenegotiation>: disables all attempts at renegotiation in TLSv1.2 and
540 earlier, same as setting B<SSL_OP_NO_RENEGOTIATION>.
542 B<UnsafeLegacyRenegotiation>: permits the use of unsafe legacy renegotiation.
543 Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
545 B<UnsafeLegacyServerConnect>: permits the use of unsafe legacy renegotiation
546 for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
548 B<EncryptThenMac>: use encrypt-then-mac extension, enabled by
549 default. Inverse of B<SSL_OP_NO_ENCRYPT_THEN_MAC>: that is,
550 B<-EncryptThenMac> is the same as setting B<SSL_OP_NO_ENCRYPT_THEN_MAC>.
552 B<AllowNoDHEKEX>: In TLSv1.3 allow a non-(ec)dhe based key exchange mode on
554 session. Equivalent to B<SSL_OP_ALLOW_NO_DHE_KEX>.
556 B<PreferNoDHEKEX>: In TLSv1.3, on resumption let the server prefer a
558 B<AllowNoDHEKEX>. Equivalent to B<SSL_OP_PREFER_NO_DHE_KEX>. Only used by
561 B<MiddleboxCompat>: If set then dummy Change Cipher Spec (CCS) messages are sent
565 default. Equivalent to B<SSL_OP_ENABLE_MIDDLEBOX_COMPAT>.
567 B<AntiReplay>: If set then OpenSSL will automatically detect if a session ticket
574 Disabling anti-replay is equivalent to setting B<SSL_OP_NO_ANTI_REPLAY>.
576 B<ExtendedMasterSecret>: use extended master secret extension, enabled by
577 default. Inverse of B<SSL_OP_NO_EXTENDED_MASTER_SECRET>: that is,
578 B<-ExtendedMasterSecret> is the same as setting B<SSL_OP_NO_EXTENDED_MASTER_SECRET>.
580 B<CANames>: use CA names extension, enabled by
581 default. Inverse of B<SSL_OP_DISABLE_TLSEXT_CA_NAMES>: that is,
582 B<-CANames> is the same as setting B<SSL_OP_DISABLE_TLSEXT_CA_NAMES>.
584 B<KTLS>: Enables kernel TLS if support has been compiled in, and it is supported
586 B<SSL_OP_ENABLE_KTLS>.
588 B<StrictCertCheck>: Enable strict certificate checking. Equivalent to
589 setting B<SSL_CERT_FLAG_TLS_STRICT> with SSL_CTX_set_cert_flags().
591 B<TxCertificateCompression>: support sending compressed certificates, enabled by
592 default. Inverse of B<SSL_OP_NO_TX_CERTIFICATE_COMPRESSION>: that is,
593 B<-TxCertificateCompression> is the same as setting B<SSL_OP_NO_TX_CERTIFICATE_COMPRESSION>.
595 B<RxCertificateCompression>: support receiving compressed certificates, enabled by
596 default. Inverse of B<SSL_OP_NO_RX_CERTIFICATE_COMPRESSION>: that is,
597 B<-RxCertificateCompression> is the same as setting B<SSL_OP_NO_RX_CERTIFICATE_COMPRESSION>.
599 B<KTLSTxZerocopySendfile>: use the zerocopy TX mode of sendfile(), which gives
602 option has no effect if B<KTLS> is not enabled. Equivalent to
603 B<SSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE>. This option only applies to Linux.
607 B<IgnoreUnexpectedEOF>: Equivalent to B<SSL_OP_IGNORE_UNEXPECTED_EOF>.
612 =item B<VerifyMode>
614 The B<value> argument is a comma separated list of flags to set.
616 B<Peer> enables peer verification: for clients only.
618 B<Request> requests but does not require a certificate from the client.
621 B<Require> requests and requires a certificate from the client: an error
624 B<Once> requests a certificate from a client only on the initial connection:
627 B<RequestPostHandshake> configures the connection to support requests but does
633 B<RequiresPostHandshake> configures the connection to support requests and
639 =item B<ClientCAFile>, B<ClientCAPath>
654 =item B<SSL_CONF_TYPE_UNKNOWN>
656 The B<option> string is unrecognised, this return value can be use to flag
659 =item B<SSL_CONF_TYPE_STRING>
663 =item B<SSL_CONF_TYPE_FILE>
667 =item B<SSL_CONF_TYPE_DIR>
671 =item B<SSL_CONF_TYPE_NONE>
692 SSLv3 is B<always> disabled and attempt to override this by the user are
696 given B<option> is recognised, this is useful if SSL_CONF_cmd() values are
706 SSL_CONF_CTX_set1_prefix(), pass the current argument to B<option> and the
707 following argument to B<value> (which may be NULL).
711 returned then B<option> is not recognised and application specific arguments
719 value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
724 SSL_CONF_cmd() returns 1 if the value of B<option> is recognised and B<value> is
725 B<NOT> used and 2 if both B<option> and B<value> are used. In other words it
729 A return value of -2 means B<option> is not recognised.
731 A return value of -3 means B<option> is recognised and the command requires a
732 value but B<value> is NULL.
734 A return code of 0 indicates that both B<option> and B<value> are valid but an
736 error in the syntax of B<value> in this case the error queue may provide
799 The B<SSL_OP_NO_SSL2> option doesn't have effect since 1.1.0, but the macro
802 The B<SSL_CONF_TYPE_NONE> was added in OpenSSL 1.1.0. In earlier versions of
804 B<SSL_CONF_TYPE_UNKNOWN>.
806 B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0.
808 B<AllowNoDHEKEX> and B<PrioritizeChaCha> were added in OpenSSL 1.1.1.
810 The B<UnsafeLegacyServerConnect> option is no longer set by default from
813 The B<TxCertificateCompression> and B<RxCertificateCompression> options were
816 B<PreferNoDHEKEX> was added in OpenSSL 3.3.

Last Index update Tue Nov 26 00:08:07 UTC 2024

Dedicated to & Maintained by Room-11