documentation fixes
[openssl.git] / doc / ssl / SSL_CONF_cmd.pod
1 =pod
2
3 =head1 NAME
4
5 SSL_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
13 =head1 DESCRIPTION
14
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.
19
20 =head1 SUPPORTED COMMAND LINE COMMANDS
21
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.
27
28 =over 4
29
30 =item B<-sigalgs>
31
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.
35
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.
41
42 If this option is not set then all signature algorithms supported by the
43 OpenSSL library are permissible.
44
45 =item B<-client_sigalgs>
46
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.
52
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.
55
56 =item B<-curves>
57
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.
62
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.
66
67 =item B<-named_curve>
68
69 This sets the temporary curve used for ephemeral ECDH modes. Only used by 
70 servers
71
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.
76
77 =item B<-cipher>
78
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>.
82
83 =item B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
84
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.
88
89 =item B<-bugs>
90
91 Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
92
93 =item B<-no_comp>
94
95 Disables support for SSL/TLS compression, same as setting B<SSL_OP_NO_COMPRESS>.
96
97 =item B<-no_ticket>
98
99 Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
100
101 =item B<-serverpref>
102
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.
106
107 =item B<-legacyrenegotiation>
108
109 permits the use of unsafe legacy renegotiation. Equivalent to setting
110 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
111
112 =item B<-legacy_server_connect>, B<-no_legacy_server_connect>
113
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>.
116 Set by default.
117
118 =item B<-strict>
119
120 enables strict mode protocol handling. Equivalent to setting
121 B<SSL_CERT_FLAG_TLS_STRICT>.
122
123 =item B<-debug_broken_protocol>
124
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>.
129
130 =back
131
132 =head1 SUPPORTED CONFIGURATION FILE COMMANDS
133
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.
139
140 Note: the command prefix (if set) alters the recognised B<cmd> values.
141
142 =over 4
143
144 =item B<CipherString>
145
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>.
149
150 =item B<SignatureAlgorithms>
151
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.
155
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.
161
162 If this option is not set then all signature algorithms supported by the
163 OpenSSL library are permissible.
164
165 =item B<ClientSignatureAlgorithms>
166
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.
171
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.
174
175 =item B<Curves>
176
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.
181
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.
185
186 =item B<ECDHParameters>
187
188 This sets the temporary curve used for ephemeral ECDH modes. Only used by 
189 servers
190
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.
195
196 =item B<Protocol>
197
198 The supported versions of the SSL or TLS protocol.
199
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.
206
207 =item B<Options>
208
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.
212
213 Each option is listed below. Where an operation is enabled by default
214 the B<-flag> syntax is needed to disable it.
215
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
218 B<SSL_OP_NO_TICKET>.
219
220 B<Compression>: SSL/TLS compression support, enabled by default. Inverse
221 of B<SSL_OP_NO_COMPRESSION>.
222
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>.
226
227 B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>.
228
229 B<DHSingle>: enable single use DH keys, set by default. Inverse of
230 B<SSL_OP_DH_SINGLE>. Only used by servers.
231
232 B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of
233 B<SSL_OP_ECDH_SINGLE>. Only used by servers.
234
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.
239
240 B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation.
241 Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
242
243 B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation
244 for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
245 Set by default.
246
247 =back
248
249 =head1 NOTES
250
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:
253
254  SSL_CONF_cmd(ctx, "Protocol", "-SSLv2");
255  SSL_CONF_cmd(ctx, userparam, uservalue);
256
257 it will disable SSLv2 support by default but the user can override it. If 
258 however the call sequence is:
259
260  SSL_CONF_cmd(ctx, userparam, uservalue);
261  SSL_CONF_cmd(ctx, "Protocol", "-SSLv2");
262
263 SSLv2 is B<always> disabled and attempt to override this by the user are
264 ignored.
265
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.
269
270 For example an application might call SSL_CTX_cmd() and if it returns
271 -2 (unrecognised command) continue with processing of application specific
272 commands.
273
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).
279
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.
286
287 =head1 EXAMPLES
288
289 Set supported signature algorithms:
290
291  SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
292
293 Enable all protocols except SSLv3 and SSLv2:
294
295  SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2");
296
297 Only enable TLSv1.2:
298
299  SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
300
301 Disable TLS session tickets:
302
303  SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
304
305 Set supported curves to P-256, P-384:
306
307  SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
308
309 Set automatic support for any elliptic curve for key exchange:
310
311  SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic");
312
313 =head1 RETURN VALUES
314
315 SSL_CONF_cmd() return 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
318 command lines.
319
320 A return value of -2 means B<cmd> is not recognised.
321
322 A return value of -3 means B<cmd> is recognised and the command requires a
323 value but B<value> is NULL.
324
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.
329
330 =head1 SEE ALSO
331
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)>
337
338 =head1 HISTORY
339
340 SSL_CONF_cmd() was first added to OpenSSL 1.1.0
341
342 =cut