1SSL_CONF_cmd(3)                     OpenSSL                    SSL_CONF_cmd(3)
2
3
4

NAME

6       SSL_CONF_cmd - send configuration command
7

SYNOPSIS

9        #include <openssl/ssl.h>
10
11        int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);
12        int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd);
13        int SSL_CONF_finish(SSL_CONF_CTX *cctx);
14

DESCRIPTION

16       The function SSL_CONF_cmd() performs configuration operation cmd with
17       optional parameter value on ctx. Its purpose is to simplify application
18       configuration of SSL_CTX or SSL structures by providing a common
19       framework for command line options or configuration files.
20
21       SSL_CONF_cmd_value_type() returns the type of value that cmd refers to.
22
23       The function SSL_CONF_finish() must be called after all configuration
24       operations have been completed. It is used to finalise any operations
25       or to process defaults.
26

SUPPORTED COMMAND LINE COMMANDS

28       Currently supported cmd names for command lines (i.e. when the flag
29       SSL_CONF_CMDLINE is set) are listed below. Note: all cmd names are case
30       sensitive. Unless otherwise stated commands can be used by both clients
31       and servers and the value parameter is not used. The default prefix for
32       command line commands is - and that is reflected below.
33
34       -sigalgs
35           This sets the supported signature algorithms for TLS v1.2. For
36           clients this value is used directly for the supported signature
37           algorithms extension. For servers it is used to determine which
38           signature algorithms to support.
39
40           The value argument should be a colon separated list of signature
41           algorithms in order of decreasing preference of the form
42           algorithm+hash. algorithm is one of RSA, DSA or ECDSA and hash is a
43           supported algorithm OID short name such as SHA1, SHA224, SHA256,
44           SHA384 of SHA512.  Note: algorithm and hash names are case
45           sensitive.
46
47           If this option is not set then all signature algorithms supported
48           by the OpenSSL library are permissible.
49
50       -client_sigalgs
51           This sets the supported signature algorithms associated with client
52           authentication for TLS v1.2. For servers the value is used in the
53           supported signature algorithms field of a certificate request. For
54           clients it is used to determine which signature algorithm to with
55           the client certificate.  If a server does not request a certificate
56           this option has no effect.
57
58           The syntax of value is identical to -sigalgs. If not set then the
59           value set for -sigalgs will be used instead.
60
61       -curves
62           This sets the supported elliptic curves. For clients the curves are
63           sent using the supported curves extension. For servers it is used
64           to determine which curve to use. This setting affects curves used
65           for both signatures and key exchange, if applicable.
66
67           The value argument is a colon separated list of curves. The curve
68           can be either the NIST name (e.g. P-256) or an OpenSSL OID name
69           (e.g prime256v1). Curve names are case sensitive.
70
71       -named_curve
72           This sets the temporary curve used for ephemeral ECDH modes. Only
73           used by servers
74
75           The value argument is a curve name or the special value auto which
76           picks an appropriate curve based on client and server preferences.
77           The curve can be either the NIST name (e.g. P-256) or an OpenSSL
78           OID name (e.g prime256v1). Curve names are case sensitive.
79
80       -cipher
81           Sets the cipher suite list to value. Note: syntax checking of value
82           is currently not performed unless a SSL or SSL_CTX structure is
83           associated with cctx.
84
85       -cert
86           Attempts to use the file value as the certificate for the
87           appropriate context. It currently uses
88           SSL_CTX_use_certificate_chain_file() if an SSL_CTX structure is set
89           or SSL_use_certificate_file() with filetype PEM if an SSL structure
90           is set. This option is only supported if certificate operations are
91           permitted.
92
93       -key
94           Attempts to use the file value as the private key for the
95           appropriate context. This option is only supported if certificate
96           operations are permitted. Note: if no -key option is set then a
97           private key is not loaded: it does not currently use the -cert
98           file.
99
100       -dhparam
101           Attempts to use the file value as the set of temporary DH
102           parameters for the appropriate context. This option is only
103           supported if certificate operations are permitted.
104
105       -no_ssl2, -no_ssl3, -no_tls1, -no_tls1_1, -no_tls1_2
106           Disables protocol support for SSLv2, SSLv3, TLSv1.0, TLSv1.1 or
107           TLSv1.2 by setting the corresponding options SSL_OP_NO_SSLv2,
108           SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and
109           SSL_OP_NO_TLSv1_2 respectively.
110
111       -bugs
112           Various bug workarounds are set, same as setting SSL_OP_ALL.
113
114       -no_comp
115           Disables support for SSL/TLS compression, same as setting
116           SSL_OP_NO_COMPRESS.
117
118       -no_ticket
119           Disables support for session tickets, same as setting
120           SSL_OP_NO_TICKET.
121
122       -serverpref
123           Use server and not client preference order when determining which
124           cipher suite, signature algorithm or elliptic curve to use for an
125           incoming connection.  Equivalent to
126           SSL_OP_CIPHER_SERVER_PREFERENCE. Only used by servers.
127
128       -no_resumption_on_reneg
129           set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used
130           by servers.
131
132       -legacyrenegotiation
133           permits the use of unsafe legacy renegotiation. Equivalent to
134           setting SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION.
135
136       -legacy_server_connect, -no_legacy_server_connect
137           permits or prohibits the use of unsafe legacy renegotiation for
138           OpenSSL clients only. Equivalent to setting or clearing
139           SSL_OP_LEGACY_SERVER_CONNECT.  Set by default.
140
141       -strict
142           enables strict mode protocol handling. Equivalent to setting
143           SSL_CERT_FLAG_TLS_STRICT.
144
145       -debug_broken_protocol
146           disables various checks and permits several kinds of broken
147           protocol behaviour for testing purposes: it should NEVER be used in
148           anything other than a test environment. Only supported if OpenSSL
149           is configured with -DOPENSSL_SSL_DEBUG_BROKEN_PROTOCOL.
150

SUPPORTED CONFIGURATION FILE COMMANDS

152       Currently supported cmd names for configuration files (i.e. when the
153       flag SSL_CONF_FLAG_FILE is set) are listed below. All configuration
154       file cmd names and are case insensitive so signaturealgorithms is
155       recognised as well as SignatureAlgorithms. Unless otherwise stated the
156       value names are also case insensitive.
157
158       Note: the command prefix (if set) alters the recognised cmd values.
159
160       CipherString
161           Sets the cipher suite list to value. Note: syntax checking of value
162           is currently not performed unless an SSL or SSL_CTX structure is
163           associated with cctx.
164
165       Certificate
166           Attempts to use the file value as the certificate for the
167           appropriate context. It currently uses
168           SSL_CTX_use_certificate_chain_file() if an SSL_CTX structure is set
169           or SSL_use_certificate_file() with filetype PEM if an SSL structure
170           is set. This option is only supported if certificate operations are
171           permitted.
172
173       PrivateKey
174           Attempts to use the file value as the private key for the
175           appropriate context. This option is only supported if certificate
176           operations are permitted. Note: if no -key option is set then a
177           private key is not loaded: it does not currently use the
178           Certificate file.
179
180       ServerInfoFile
181           Attempts to use the file value in the "serverinfo" extension using
182           the function SSL_CTX_use_serverinfo_file.
183
184       DHParameters
185           Attempts to use the file value as the set of temporary DH
186           parameters for the appropriate context. This option is only
187           supported if certificate operations are permitted.
188
189       SignatureAlgorithms
190           This sets the supported signature algorithms for TLS v1.2. For
191           clients this value is used directly for the supported signature
192           algorithms extension. For servers it is used to determine which
193           signature algorithms to support.
194
195           The value argument should be a colon separated list of signature
196           algorithms in order of decreasing preference of the form
197           algorithm+hash. algorithm is one of RSA, DSA or ECDSA and hash is a
198           supported algorithm OID short name such as SHA1, SHA224, SHA256,
199           SHA384 of SHA512.  Note: algorithm and hash names are case
200           sensitive.
201
202           If this option is not set then all signature algorithms supported
203           by the OpenSSL library are permissible.
204
205       ClientSignatureAlgorithms
206           This sets the supported signature algorithms associated with client
207           authentication for TLS v1.2. For servers the value is used in the
208           supported signature algorithms field of a certificate request. For
209           clients it is used to determine which signature algorithm to with
210           the client certificate.
211
212           The syntax of value is identical to SignatureAlgorithms. If not set
213           then the value set for SignatureAlgorithms will be used instead.
214
215       Curves
216           This sets the supported elliptic curves. For clients the curves are
217           sent using the supported curves extension. For servers it is used
218           to determine which curve to use. This setting affects curves used
219           for both signatures and key exchange, if applicable.
220
221           The value argument is a colon separated list of curves. The curve
222           can be either the NIST name (e.g. P-256) or an OpenSSL OID name
223           (e.g prime256v1). Curve names are case sensitive.
224
225       ECDHParameters
226           This sets the temporary curve used for ephemeral ECDH modes. Only
227           used by servers
228
229           The value argument is a curve name or the special value Automatic
230           which picks an appropriate curve based on client and server
231           preferences. The curve can be either the NIST name (e.g. P-256) or
232           an OpenSSL OID name (e.g prime256v1). Curve names are case
233           sensitive.
234
235       Protocol
236           The supported versions of the SSL or TLS protocol.
237
238           The value argument is a comma separated list of supported protocols
239           to enable or disable. If an protocol is preceded by - that version
240           is disabled.  Currently supported protocol values are SSLv2, SSLv3,
241           TLSv1, TLSv1.1 and TLSv1.2.  All protocol versions other than SSLv2
242           are enabled by default.  To avoid inadvertent enabling of SSLv2,
243           when SSLv2 is disabled, it is not possible to enable it via the
244           Protocol command.
245
246       Options
247           The value argument is a comma separated list of various flags to
248           set.  If a flag string is preceded - it is disabled. See the
249           SSL_CTX_set_options function for more details of individual
250           options.
251
252           Each option is listed below. Where an operation is enabled by
253           default the -flag syntax is needed to disable it.
254
255           SessionTicket: session ticket support, enabled by default. Inverse
256           of SSL_OP_NO_TICKET: that is -SessionTicket is the same as setting
257           SSL_OP_NO_TICKET.
258
259           Compression: SSL/TLS compression support, enabled by default.
260           Inverse of SSL_OP_NO_COMPRESSION.
261
262           EmptyFragments: use empty fragments as a countermeasure against a
263           SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It is
264           set by default. Inverse of SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS.
265
266           Bugs: enable various bug workarounds. Same as SSL_OP_ALL.
267
268           DHSingle: enable single use DH keys, set by default. Inverse of
269           SSL_OP_DH_SINGLE. Only used by servers.
270
271           ECDHSingle enable single use ECDH keys, set by default. Inverse of
272           SSL_OP_ECDH_SINGLE. Only used by servers.
273
274           ServerPreference use server and not client preference order when
275           determining which cipher suite, signature algorithm or elliptic
276           curve to use for an incoming connection.  Equivalent to
277           SSL_OP_CIPHER_SERVER_PREFERENCE. Only used by servers.
278
279           NoResumptionOnRenegotiation set
280           SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by
281           servers.
282
283           UnsafeLegacyRenegotiation permits the use of unsafe legacy
284           renegotiation.  Equivalent to
285           SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION.
286
287           UnsafeLegacyServerConnect permits the use of unsafe legacy
288           renegotiation for OpenSSL clients only. Equivalent to
289           SSL_OP_LEGACY_SERVER_CONNECT.  Set by default.
290

SUPPORTED COMMAND TYPES

292       The function SSL_CONF_cmd_value_type() currently returns one of the
293       following types:
294
295       SSL_CONF_TYPE_UNKNOWN
296           The cmd string is unrecognised, this return value can be use to
297           flag syntax errors.
298
299       SSL_CONF_TYPE_STRING
300           The value is a string without any specific structure.
301
302       SSL_CONF_TYPE_FILE
303           The value is a file name.
304
305       SSL_CONF_TYPE_DIR
306           The value is a directory name.
307

NOTES

309       The order of operations is significant. This can be used to set either
310       defaults or values which cannot be overridden. For example if an
311       application calls:
312
313        SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
314        SSL_CONF_cmd(ctx, userparam, uservalue);
315
316       it will disable SSLv3 support by default but the user can override it.
317       If however the call sequence is:
318
319        SSL_CONF_cmd(ctx, userparam, uservalue);
320        SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
321
322       then SSLv3 is always disabled and attempt to override this by the user
323       are ignored.
324
325       By checking the return code of SSL_CTX_cmd() it is possible to query if
326       a given cmd is recognised, this is useful is SSL_CTX_cmd() values are
327       mixed with additional application specific operations.
328
329       For example an application might call SSL_CTX_cmd() and if it returns
330       -2 (unrecognised command) continue with processing of application
331       specific commands.
332
333       Applications can also use SSL_CTX_cmd() to process command lines though
334       the utility function SSL_CTX_cmd_argv() is normally used instead. One
335       way to do this is to set the prefix to an appropriate value using
336       SSL_CONF_CTX_set1_prefix(), pass the current argument to cmd and the
337       following argument to value (which may be NULL).
338
339       In this case if the return value is positive then it is used to skip
340       that number of arguments as they have been processed by SSL_CTX_cmd().
341       If -2 is returned then cmd is not recognised and application specific
342       arguments can be checked instead. If -3 is returned a required argument
343       is missing and an error is indicated. If 0 is returned some other error
344       occurred and this can be reported back to the user.
345
346       The function SSL_CONF_cmd_value_type() can be used by applications to
347       check for the existence of a command or to perform additional syntax
348       checking or translation of the command value. For example if the return
349       value is SSL_CONF_TYPE_FILE an application could translate a relative
350       pathname to an absolute pathname.
351

EXAMPLES

353       Set supported signature algorithms:
354
355        SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
356
357       Enable all protocols except SSLv3 and SSLv2:
358
359        SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2");
360
361       Only enable TLSv1.2:
362
363        SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
364
365       Disable TLS session tickets:
366
367        SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
368
369       Set supported curves to P-256, P-384:
370
371        SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
372
373       Set automatic support for any elliptic curve for key exchange:
374
375        SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic");
376

RETURN VALUES

378       SSL_CONF_cmd() returns 1 if the value of cmd is recognised and value is
379       NOT used and 2 if both cmd and value are used. In other words it
380       returns the number of arguments processed. This is useful when
381       processing command lines.
382
383       A return value of -2 means cmd is not recognised.
384
385       A return value of -3 means cmd is recognised and the command requires a
386       value but value is NULL.
387
388       A return code of 0 indicates that both cmd and value are valid but an
389       error occurred attempting to perform the operation: for example due to
390       an error in the syntax of value in this case the error queue may
391       provide additional information.
392
393       SSL_CONF_finish() returns 1 for success and 0 for failure.
394

SEE ALSO

396       SSL_CONF_CTX_new(3), SSL_CONF_CTX_set_flags(3),
397       SSL_CONF_CTX_set1_prefix(3), SSL_CONF_CTX_set_ssl_ctx(3),
398       SSL_CONF_cmd_argv(3)
399

HISTORY

401       SSL_CONF_cmd() was first added to OpenSSL 1.0.2
402
403
404
4051.0.2o                            2018-03-27                   SSL_CONF_cmd(3)
Impressum