5 SSL_CONF_cmd - send configuration command
9 #include <openssl/ssl.h>
11 int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);
15 The function SSL_CONF_cmd() performs configuration operation B<cmd> with
16 optional parameter B<value> on B<ctx>. Its purpose is to simplify application
17 configuration of B<SSL_CTX> or B<SSL> structures by providing a common
18 framework for command line options or configuration files.
20 =head1 SUPPORTED COMMAND LINE COMMANDS
22 Currently supported B<cmd> names for command lines (i.e. when the
23 flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<cmd> names
24 and are case sensitive. Unless otherwise stated commands can be used by
25 both clients and servers and the B<value> parameter is not used. The default
26 prefix for command line commands is B<-> and that is reflected below.
32 This sets the supported signature algorithms for TLS v1.2. For clients this
33 value is used directly for the supported signature algorithms extension. For
34 servers it is used to determine which signature algorithms to support.
36 The B<value> argument should be a colon separated list of signature algorithms
37 in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
38 is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
39 OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
40 Note: algorithm and hash names are case sensitive.
42 If this option is not set then all signature algorithms supported by the
43 OpenSSL library are permissible.
45 =item B<-client_sigalgs>
47 This sets the supported signature algorithms associated with client
48 authentication for TLS v1.2. For servers the value is used in the supported
49 signature algorithms field of a certificate request. For clients it is
50 used to determine which signature algorithm to with the client certificate.
51 If a server does not request a certificate this option has no effect.
53 The syntax of B<value> is identical to B<-sigalgs>. If not set then
54 the value set for B<-sigalgs> will be used instead.
58 This sets the supported elliptic curves. For clients the curves are
59 sent using the supported curves extension. For servers it is used
60 to determine which curve to use. This setting affects curves used for both
61 signatures and key exchange, if applicable.
63 The B<value> argument is a colon separated list of curves. The curve can be
64 either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
65 B<prime256v1>). Curve names are case sensitive.
69 This sets the temporary curve used for ephemeral ECDH modes. Only used by
72 The B<value> argument is a curve name or the special value B<auto> which
73 picks an appropriate curve based on client and server preferences. The curve
74 can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
75 (e.g B<prime256v1>). Curve names are case sensitive.
79 Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
80 currently not performed unless a B<SSL> or B<SSL_CTX> structure is
81 associated with B<cctx>.
83 =item B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
85 Disables protocol support for SSLv2, SSLv3, TLS 1.0, TLS 1.1 or TLS 1.2
86 by setting the corresponding options B<SSL_OP_NO_SSL2>, B<SSL_OP_NO_SSL3>,
87 B<SSL_OP_NO_TLS1>, B<SSL_OP_NO_TLS1_1> and B<SSL_OP_NO_TLS1_2> respectively.
91 Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
95 Disables support for SSL/TLS compression, same as setting B<SSL_OP_NO_COMPRESS>.
99 Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
103 Use server and not client preference order when determining which cipher suite,
104 signature algorithm or elliptic curve to use for an incoming connection.
105 Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
107 =item B<-legacyrenegotiation>
109 permits the use of unsafe legacy renegotiation. Equivalent to setting
110 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
112 =item B<-legacy_server_connect>, B<-no_legacy_server_connect>
114 permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
115 clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
120 enables strict mode protocol handling. Equivalent to setting
121 B<SSL_CERT_FLAG_TLS_STRICT>.
123 =item B<-debug_broken_protocol>
125 disables various checks and permits several kinds of broken protocol behaviour
126 for testing purposes: it should B<NEVER> be used in anything other than a test
127 environment. Only supported if OpenSSL is configured with
128 B<-DOPENSSL_SSL_DEBUG_BROKEN_PROTOCOL>.
132 =head1 SUPPORTED CONFIGURATION FILE COMMANDS
134 Currently supported B<cmd> names for configuration files (i.e. when the
135 flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
136 B<cmd> names and are case insensitive so B<signaturealgorithms> is recognised
137 as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
138 are also case insensitive.
140 Note: the command prefix (if set) alters the recognised B<cmd> values.
144 =item B<CipherString>
146 Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
147 currently not performed unless an B<SSL> or B<SSL_CTX> structure is
148 associated with B<cctx>.
150 =item B<SignatureAlgorithms>
152 This sets the supported signature algorithms for TLS v1.2. For clients this
153 value is used directly for the supported signature algorithms extension. For
154 servers it is used to determine which signature algorithms to support.
156 The B<value> argument should be a colon separated list of signature algorithms
157 in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
158 is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
159 OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
160 Note: algorithm and hash names are case sensitive.
162 If this option is not set then all signature algorithms supported by the
163 OpenSSL library are permissible.
165 =item B<ClientSignatureAlgorithms>
167 This sets the supported signature algorithms associated with client
168 authentication for TLS v1.2. For servers the value is used in the supported
169 signature algorithms field of a certificate request. For clients it is
170 used to determine which signature algorithm to with the client certificate.
172 The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
173 the value set for B<SignatureAlgorithms> will be used instead.
177 This sets the supported elliptic curves. For clients the curves are
178 sent using the supported curves extension. For servers it is used
179 to determine which curve to use. This setting affects curves used for both
180 signatures and key exchange, if applicable.
182 The B<value> argument is a colon separated list of curves. The curve can be
183 either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
184 B<prime256v1>). Curve names are case sensitive.
186 =item B<ECDHParameters>
188 This sets the temporary curve used for ephemeral ECDH modes. Only used by
191 The B<value> argument is a curve name or the special value B<Automatic> which
192 picks an appropriate curve based on client and server preferences. The curve
193 can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
194 (e.g B<prime256v1>). Curve names are case sensitive.
198 The supported versions of the SSL or TLS protocol.
200 The B<value> argument is a comma separated list of supported protocols to
201 enable or disable. If an protocol is preceded by B<-> that version is disabled.
202 All versions are enabled by default, though applications may choose to
203 explicitly disable some. Currently supported protocol values are B<SSLv2>,
204 B<SSLv3>, B<TLSv1>, B<TLSv1.1> and B<TLSv1.2>. The special value B<ALL> refers
205 to all supported versions.
209 The B<value> argument is a comma separated list of various flags to set.
210 If a flag string is preceded B<-> it is disabled. See the
211 B<SSL_CTX_set_options> function for more details of individual options.
213 Each option is listed below. Where an operation is enabled by default
214 the B<-flag> syntax is needed to disable it.
216 B<SessionTicket>: session ticket support, enabled by default. Inverse of
217 B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting
220 B<Compression>: SSL/TLS compression support, enabled by default. Inverse
221 of B<SSL_OP_NO_COMPRESSION>.
223 B<EmptyFragments>: use empty fragments as a countermeasure against a
224 SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It
225 is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>.
227 B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>.
229 B<DHSingle>: enable single use DH keys, set by default. Inverse of
230 B<SSL_OP_DH_SINGLE>. Only used by servers.
232 B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of
233 B<SSL_OP_ECDH_SINGLE>. Only used by servers.
235 B<ServerPreference> use server and not client preference order when
236 determining which cipher suite, signature algorithm or elliptic curve
237 to use for an incoming connection. Equivalent to
238 B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
240 B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation.
241 Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
243 B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation
244 for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
251 The order of operations is significant. This can be used to set either defaults
252 or values which cannot be overridden. For example if an application calls:
254 SSL_CONF_cmd(ctx, "Protocol", "-SSLv2");
255 SSL_CONF_cmd(ctx, userparam, uservalue);
257 it will disable SSLv2 support by default but the user can override it. If
258 however the call sequence is:
260 SSL_CONF_cmd(ctx, userparam, uservalue);
261 SSL_CONF_cmd(ctx, "Protocol", "-SSLv2");
263 SSLv2 is B<always> disabled and attempt to override this by the user are
266 By checking the return code of SSL_CTX_cmd() it is possible to query if a
267 given B<cmd> is recognised, this is useful is SSL_CTX_cmd() values are
268 mixed with additional application specific operations.
270 For example an application might call SSL_CTX_cmd() and if it returns
271 -2 (unrecognised command) continue with processing of application specific
274 Applications can also use SSL_CTX_cmd() to process command lines though the
275 utility function SSL_CTX_cmd_argv() is normally used instead. One way
276 to do this is to set the prefix to an appropriate value using
277 SSL_CONF_CTX_set1_prefix(), pass the current argument to B<cmd> and the
278 following argument to B<value> (which may be NULL).
280 In this case if the return value is positive then it is used to skip that
281 number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is
282 returned then B<cmd> is not recognised and application specific arguments
283 can be checked instead. If -3 is returned a required argument is missing
284 and an error is indicated. If 0 is returned some other error occurred and
285 this can be reported back to the user.
289 Set supported signature algorithms:
291 SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
293 Enable all protocols except SSLv3 and SSLv2:
295 SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2");
299 SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
301 Disable TLS session tickets:
303 SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
305 Set supported curves to P-256, P-384:
307 SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
309 Set automatic support for any elliptic curve for key exchange:
311 SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic");
315 SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
316 B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
317 returns the number of arguments processed. This is useful when processing
320 A return value of -2 means B<cmd> is not recognised.
322 A return value of -3 means B<cmd> is recognised and the command requires a
323 value but B<value> is NULL.
325 A return code of 0 indicates that both B<cmd> and B<value> are valid but an
326 error occurred attempting to perform the operation: for example due to an
327 error in the syntax of B<value> in this case the error queue may provide
328 additional information.
332 L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>,
333 L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>,
334 L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>,
335 L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>,
336 L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)>
340 SSL_CONF_cmd() was first added to OpenSSL 1.0.2