1=pod
2
3=head1 NAME
4
5SSL_CONF_cmd - send configuration command
6
7=head1 SYNOPSIS
8
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
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
24The function SSL_CONF_finish() must be called after all configuration
25operations have been completed. It is used to finalise any operations
26or to process defaults.
27
28=head1 SUPPORTED COMMAND LINE COMMANDS
29
30Currently supported B<cmd> names for command lines (i.e. when the
31flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<cmd> names
32are case sensitive. Unless otherwise stated commands can be used by
33both clients and servers and the B<value> parameter is not used. The default
34prefix for command line commands is B<-> and that is reflected below.
35
36=over 4
37
38=item B<-sigalgs>
39
40This sets the supported signature algorithms for TLS v1.2. For clients this
41value is used directly for the supported signature algorithms extension. For
42servers it is used to determine which signature algorithms to support.
43
44The B<value> argument should be a colon separated list of signature algorithms
45in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
46is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
47OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
48Note: algorithm and hash names are case sensitive.
49
50If this option is not set then all signature algorithms supported by the
51OpenSSL library are permissible.
52
53=item B<-client_sigalgs>
54
55This sets the supported signature algorithms associated with client
56authentication for TLS v1.2. For servers the value is used in the supported
57signature algorithms field of a certificate request. For clients it is
58used to determine which signature algorithm to with the client certificate.
59If a server does not request a certificate this option has no effect.
60
61The syntax of B<value> is identical to B<-sigalgs>. If not set then
62the value set for B<-sigalgs> will be used instead.
63
64=item B<-curves>
65
66This sets the supported elliptic curves. For clients the curves are
67sent using the supported curves extension. For servers it is used
68to determine which curve to use. This setting affects curves used for both
69signatures and key exchange, if applicable.
70
71The B<value> argument is a colon separated list of curves. The curve can be
72either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
73B<prime256v1>). Curve names are case sensitive.
74
75=item B<-named_curve>
76
77This sets the temporary curve used for ephemeral ECDH modes. Only used by
78servers
79
80The B<value> argument is a curve name or the special value B<auto> which
81picks an appropriate curve based on client and server preferences. The curve
82can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
83(e.g B<prime256v1>). Curve names are case sensitive.
84
85=item B<-cipher>
86
87Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
88currently not performed unless a B<SSL> or B<SSL_CTX> structure is
89associated with B<cctx>.
90
91=item B<-cert>
92
93Attempts to use the file B<value> as the certificate for the appropriate
94context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
95structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
96structure is set. This option is only supported if certificate operations
97are permitted.
98
99=item B<-key>
100
101Attempts to use the file B<value> as the private key for the appropriate
102context. This option is only supported if certificate operations
103are permitted. Note: if no B<-key> option is set then a private key is
104not loaded: it does not currently use the B<-cert> file.
105
106=item B<-dhparam>
107
108Attempts to use the file B<value> as the set of temporary DH parameters for
109the appropriate context. This option is only supported if certificate
110operations are permitted.
111
112=item B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
113
114Disables protocol support for SSLv2, SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2
115by setting the corresponding options B<SSL_OP_NO_SSLv2>, B<SSL_OP_NO_SSLv3>,
116B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and B<SSL_OP_NO_TLSv1_2> respectively.
117
118=item B<-bugs>
119
120Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
121
122=item B<-no_comp>
123
124Disables support for SSL/TLS compression, same as setting B<SSL_OP_NO_COMPRESS>.
125
126=item B<-no_ticket>
127
128Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
129
130=item B<-serverpref>
131
132Use server and not client preference order when determining which cipher suite,
133signature algorithm or elliptic curve to use for an incoming connection.
134Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
135
136=item B<-no_resumption_on_reneg>
137
138set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers.
139
140=item B<-legacyrenegotiation>
141
142permits the use of unsafe legacy renegotiation. Equivalent to setting
143B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
144
145=item B<-legacy_server_connect>, B<-no_legacy_server_connect>
146
147permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
148clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
149Set by default.
150
151=item B<-strict>
152
153enables strict mode protocol handling. Equivalent to setting
154B<SSL_CERT_FLAG_TLS_STRICT>.
155
156=item B<-debug_broken_protocol>
157
158disables various checks and permits several kinds of broken protocol behaviour
159for testing purposes: it should B<NEVER> be used in anything other than a test
160environment. Only supported if OpenSSL is configured with
161B<-DOPENSSL_SSL_DEBUG_BROKEN_PROTOCOL>.
162
163=back
164
165=head1 SUPPORTED CONFIGURATION FILE COMMANDS
166
167Currently supported B<cmd> names for configuration files (i.e. when the
168flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
169B<cmd> names and are case insensitive so B<signaturealgorithms> is recognised
170as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
171are also case insensitive.
172
173Note: the command prefix (if set) alters the recognised B<cmd> values.
174
175=over 4
176
177=item B<CipherString>
178
179Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
180currently not performed unless an B<SSL> or B<SSL_CTX> structure is
181associated with B<cctx>.
182
183=item B<Certificate>
184
185Attempts to use the file B<value> as the certificate for the appropriate
186context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
187structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
188structure is set. This option is only supported if certificate operations
189are permitted.
190
191=item B<PrivateKey>
192
193Attempts to use the file B<value> as the private key for the appropriate
194context. This option is only supported if certificate operations
195are permitted. Note: if no B<-key> option is set then a private key is
196not loaded: it does not currently use the B<Certificate> file.
197
198=item B<ServerInfoFile>
199
200Attempts to use the file B<value> in the "serverinfo" extension using the
201function SSL_CTX_use_serverinfo_file.
202
203=item B<DHParameters>
204
205Attempts to use the file B<value> as the set of temporary DH parameters for
206the appropriate context. This option is only supported if certificate
207operations are permitted.
208
209=item B<SignatureAlgorithms>
210
211This sets the supported signature algorithms for TLS v1.2. For clients this
212value is used directly for the supported signature algorithms extension. For
213servers it is used to determine which signature algorithms to support.
214
215The B<value> argument should be a colon separated list of signature algorithms
216in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
217is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
218OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
219Note: algorithm and hash names are case sensitive.
220
221If this option is not set then all signature algorithms supported by the
222OpenSSL library are permissible.
223
224=item B<ClientSignatureAlgorithms>
225
226This sets the supported signature algorithms associated with client
227authentication for TLS v1.2. For servers the value is used in the supported
228signature algorithms field of a certificate request. For clients it is
229used to determine which signature algorithm to with the client certificate.
230
231The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
232the value set for B<SignatureAlgorithms> will be used instead.
233
234=item B<Curves>
235
236This sets the supported elliptic curves. For clients the curves are
237sent using the supported curves extension. For servers it is used
238to determine which curve to use. This setting affects curves used for both
239signatures and key exchange, if applicable.
240
241The B<value> argument is a colon separated list of curves. The curve can be
242either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
243B<prime256v1>). Curve names are case sensitive.
244
245=item B<ECDHParameters>
246
247This sets the temporary curve used for ephemeral ECDH modes. Only used by
248servers
249
250The B<value> argument is a curve name or the special value B<Automatic> which
251picks an appropriate curve based on client and server preferences. The curve
252can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
253(e.g B<prime256v1>). Curve names are case sensitive.
254
255=item B<Protocol>
256
257The supported versions of the SSL or TLS protocol.
258
259The B<value> argument is a comma separated list of supported protocols to
260enable or disable. If an protocol is preceded by B<-> that version is disabled.
261Currently supported protocol values are B<SSLv2>, B<SSLv3>, B<TLSv1>,
262B<TLSv1.1> and B<TLSv1.2>.
263All protocol versions other than B<SSLv2> are enabled by default.
264To avoid inadvertent enabling of B<SSLv2>, when SSLv2 is disabled, it is not
265possible to enable it via the B<Protocol> command.
266
267=item B<Options>
268
269The B<value> argument is a comma separated list of various flags to set.
270If a flag string is preceded B<-> it is disabled. See the
271B<SSL_CTX_set_options> function for more details of individual options.
272
273Each option is listed below. Where an operation is enabled by default
274the B<-flag> syntax is needed to disable it.
275
276B<SessionTicket>: session ticket support, enabled by default. Inverse of
277B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting
278B<SSL_OP_NO_TICKET>.
279
280B<Compression>: SSL/TLS compression support, enabled by default. Inverse
281of B<SSL_OP_NO_COMPRESSION>.
282
283B<EmptyFragments>: use empty fragments as a countermeasure against a
284SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It
285is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>.
286
287B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>.
288
289B<DHSingle>: enable single use DH keys, set by default. Inverse of
290B<SSL_OP_DH_SINGLE>. Only used by servers.
291
292B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of
293B<SSL_OP_ECDH_SINGLE>. Only used by servers.
294
295B<ServerPreference> use server and not client preference order when
296determining which cipher suite, signature algorithm or elliptic curve
297to use for an incoming connection.  Equivalent to
298B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
299
300B<NoResumptionOnRenegotiation> set
301B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers.
302
303B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation.
304Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
305
306B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation
307for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
308Set by default.
309
310=back
311
312=head1 SUPPORTED COMMAND TYPES
313
314The function SSL_CONF_cmd_value_type() currently returns one of the following
315types:
316
317=over 4
318
319=item B<SSL_CONF_TYPE_UNKNOWN>
320
321The B<cmd> string is unrecognised, this return value can be use to flag
322syntax errors.
323
324=item B<SSL_CONF_TYPE_STRING>
325
326The value is a string without any specific structure.
327
328=item B<SSL_CONF_TYPE_FILE>
329
330The value is a file name.
331
332=item B<SSL_CONF_TYPE_DIR>
333
334The value is a directory name.
335
336=back
337
338=head1 NOTES
339
340The order of operations is significant. This can be used to set either defaults
341or values which cannot be overridden. For example if an application calls:
342
343 SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
344 SSL_CONF_cmd(ctx, userparam, uservalue);
345
346it will disable SSLv3 support by default but the user can override it. If
347however the call sequence is:
348
349 SSL_CONF_cmd(ctx, userparam, uservalue);
350 SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
351
352then SSLv3 is B<always> disabled and attempt to override this by the user are
353ignored.
354
355By checking the return code of SSL_CTX_cmd() it is possible to query if a
356given B<cmd> is recognised, this is useful is SSL_CTX_cmd() values are
357mixed with additional application specific operations.
358
359For example an application might call SSL_CTX_cmd() and if it returns
360-2 (unrecognised command) continue with processing of application specific
361commands.
362
363Applications can also use SSL_CTX_cmd() to process command lines though the
364utility function SSL_CTX_cmd_argv() is normally used instead. One way
365to do this is to set the prefix to an appropriate value using
366SSL_CONF_CTX_set1_prefix(), pass the current argument to B<cmd> and the
367following argument to B<value> (which may be NULL).
368
369In this case if the return value is positive then it is used to skip that
370number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is
371returned then B<cmd> is not recognised and application specific arguments
372can be checked instead. If -3 is returned a required argument is missing
373and an error is indicated. If 0 is returned some other error occurred and
374this can be reported back to the user.
375
376The function SSL_CONF_cmd_value_type() can be used by applications to
377check for the existence of a command or to perform additional syntax
378checking or translation of the command value. For example if the return
379value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
380pathname to an absolute pathname.
381
382=head1 EXAMPLES
383
384Set supported signature algorithms:
385
386 SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
387
388Enable all protocols except SSLv3 and SSLv2:
389
390 SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2");
391
392Only enable TLSv1.2:
393
394 SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
395
396Disable TLS session tickets:
397
398 SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
399
400Set supported curves to P-256, P-384:
401
402 SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
403
404Set automatic support for any elliptic curve for key exchange:
405
406 SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic");
407
408=head1 RETURN VALUES
409
410SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
411B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
412returns the number of arguments processed. This is useful when processing
413command lines.
414
415A return value of -2 means B<cmd> is not recognised.
416
417A return value of -3 means B<cmd> is recognised and the command requires a
418value but B<value> is NULL.
419
420A return code of 0 indicates that both B<cmd> and B<value> are valid but an
421error occurred attempting to perform the operation: for example due to an
422error in the syntax of B<value> in this case the error queue may provide
423additional information.
424
425SSL_CONF_finish() returns 1 for success and 0 for failure.
426
427=head1 SEE ALSO
428
429L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>,
430L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>,
431L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>,
432L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>,
433L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)>
434
435=head1 HISTORY
436
437SSL_CONF_cmd() was first added to OpenSSL 1.0.2
438
439=cut
440