| blob | a64826e5782f9b12211b0f5f80b45fbe59ce2318 |
1 .\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.7 2018/04/10 21:37:20 schwarze Exp $
2 .\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3 .\"
4 .\" This file is a derived work.
5 .\" The changes are covered by the following Copyright and license:
6 .\"
7 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software for any
10 .\" purpose with or without fee is hereby granted, provided that the above
11 .\" copyright notice and this permission notice appear in all copies.
12 .\"
13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 .\"
21 .\" The original file was written by Lutz Jaenicke <jaenicke@openssl.org>.
22 .\" Copyright (c) 2000, 2001, 2013 The OpenSSL Project. All rights reserved.
23 .\"
24 .\" Redistribution and use in source and binary forms, with or without
25 .\" modification, are permitted provided that the following conditions
26 .\" are met:
27 .\"
28 .\" 1. Redistributions of source code must retain the above copyright
29 .\" notice, this list of conditions and the following disclaimer.
30 .\"
31 .\" 2. Redistributions in binary form must reproduce the above copyright
32 .\" notice, this list of conditions and the following disclaimer in
33 .\" the documentation and/or other materials provided with the
34 .\" distribution.
35 .\"
36 .\" 3. All advertising materials mentioning features or use of this
37 .\" software must display the following acknowledgment:
38 .\" "This product includes software developed by the OpenSSL Project
39 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40 .\"
41 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42 .\" endorse or promote products derived from this software without
43 .\" prior written permission. For written permission, please contact
44 .\" openssl-core@openssl.org.
45 .\"
46 .\" 5. Products derived from this software may not be called "OpenSSL"
47 .\" nor may "OpenSSL" appear in their names without prior written
48 .\" permission of the OpenSSL Project.
49 .\"
50 .\" 6. Redistributions of any form whatsoever must retain the following
51 .\" acknowledgment:
52 .\" "This product includes software developed by the OpenSSL Project
53 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54 .\"
55 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
59 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
67 .\"
68 .Dd $Mdocdate: April 10 2018 $
69 .Dt SSL_CTX_SET_CIPHER_LIST 3
70 .Os
71 .Sh NAME
72 .Nm SSL_CTX_set_cipher_list ,
73 .Nm SSL_set_cipher_list
74 .Nd choose list of available SSL_CIPHERs
75 .Sh SYNOPSIS
76 .In openssl/ssl.h
77 .Ft int
78 .Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "const char *control"
79 .Ft int
80 .Fn SSL_set_cipher_list "SSL *ssl" "const char *control"
81 .Sh DESCRIPTION
82 .Fn SSL_CTX_set_cipher_list
83 sets the list of available cipher suites for
84 .Fa ctx
85 using the
86 .Fa control
87 string.
88 The list of cipher suites is inherited by all
89 .Fa ssl
90 objects created from
91 .Fa ctx .
92 .Pp
93 .Fn SSL_set_cipher_list
94 sets the list of cipher suites only for
95 .Fa ssl .
96 .Pp
97 The control string consists of one or more control words
98 separated by colon characters
99 .Pq Ql \&: .
100 Space
101 .Pq Ql \ \& ,
102 semicolon
103 .Pq Ql \&; ,
104 and comma
105 .Pq Ql \&,
106 characters can also be used as separators.
107 Each control words selects a set of cipher suites
108 and can take one of the following optional prefix characters:
109 .Bl -tag -width Ds
110 .It \&No prefix:
111 Those of the selected cipher suites that have not been made available
112 yet are added to the end of the list of available cipher suites,
113 preserving their order.
114 .It Prefixed minus sign Pq Ql \- :
115 Those of the selected cipher suites that have been made available
116 earlier are moved back from the list of available cipher suites to
117 the beginning of the list of unavailable cipher suites,
118 also preserving their order.
119 .It Prefixed plus sign Pq Ql + :
120 Those of the selected cipher suites have been made available earlier
121 are moved to end of the list of available cipher suites, reducing
122 their priority, but preserving the order among themselves.
123 .It Prefixed exclamation mark Pq Ql \&! :
124 The selected cipher suites are permanently deleted, no matter whether
125 they had earlier been made available or not, and can no longer
126 be added or re-added by later words.
127 .El
128 .Pp
129 The following special words can only be used without a prefix:
130 .Bl -tag -width Ds
131 .It Cm DEFAULT
132 An alias for
133 .Sm off
134 .Cm ALL No :! Cm aNULL No :! Cm eNULL .
135 .Sm on
136 It can only be used as the first word.
137 .It Cm @STRENGTH
138 Sort the list by decreasing encryption strength,
139 preserving the order of cipher suites that have the same strength.
140 It is usally given as the last word.
141 .El
142 .Pp
143 The following words can be used to select groups of cipher suites,
144 with or without a prefix character.
145 If two or more of these words are joined with plus signs
146 .Pq Ql +
147 to form a longer word, only the intersection of the specified sets
148 is selected.
149 .Bl -tag -width Ds
150 .It Cm ADH
151 Cipher suites using ephemeral DH for key exchange
152 without doing any server authentication.
153 Equivalent to
154 .Cm kEDH Ns + Ns Cm aNULL .
155 .It Cm aDSS
156 Cipher suites using DSS server authentication.
157 LibreSSL does not provide any such cipher suites.
158 .It Cm AEAD
159 Cipher suites using Authenticated Encryption with Additional Data.
160 .It Cm AECDH
161 Cipher suites using ephemeral ECDH for key exchange
162 without doing any server authentication.
163 Equivalent to
164 .Cm kEECDH Ns + Ns Cm aNULL .
165 .It Cm aECDSA
166 Cipher suites using ECDSA server authentication.
167 .It Cm AES
168 Cipher suites using AES or AESGCM for symmetric encryption.
169 .It Cm AES128
170 Cipher suites using AES(128) or AESGCM(128) for symmetric encryption.
171 .It Cm AES256
172 Cipher suites using AES(256) or AESGCM(256) for symmetric encryption.
173 .It Cm AESGCM
174 Cipher suites using AESGCM for symmetric encryption.
175 .It Cm aGOST
176 An alias for
177 .Cm aGOST01 .
178 .It Cm aGOST01
179 Cipher suites using GOST R 34.10-2001 server authentication.
180 .It Cm ALL
181 All cipher suites except those selected by
182 .Cm eNULL .
183 .It Cm aNULL
184 Cipher suites that don't do any server authentication.
185 Not enabled by
186 .Cm DEFAULT .
187 Beware of man-in-the-middle attacks.
188 .It Cm aRSA
189 Cipher suites using RSA server authentication.
190 .It Cm CAMELLIA
191 Cipher suites using Camellia for symmetric encryption.
192 .It Cm CAMELLIA128
193 Cipher suites using Camellia(128) for symmetric encryption.
194 .It Cm CAMELLIA256
195 Cipher suites using Camellia(256) for symmetric encryption.
196 .It Cm CHACHA20
197 Cipher suites using ChaCha20-Poly1305 for symmetric encryption.
198 .It Cm COMPLEMENTOFALL
199 Cipher suites that are not included in
200 .Cm ALL .
201 Currently an alias for
202 .Cm eNULL .
203 .It Cm COMPLEMENTOFDEFAULT
204 Cipher suites that are included in
205 .Cm ALL ,
206 but not included in
207 .Cm DEFAULT .
208 Currently similar to
209 .Cm aNULL Ns :! Ns Cm eNULL
210 except for the order of the cipher suites which are
211 .Em not
212 selected.
213 .It Cm DES
214 Cipher suites using single DES for symmetric encryption.
215 .It Cm 3DES
216 Cipher suites using triple DES for symmetric encryption.
217 .It Cm DH
218 An alias for
219 .Cm kEDH .
220 .It Cm DHE
221 Cipher suites using ephemeral DH for key exchange,
222 but excluding those that don't do any server authentication.
223 Similar to
224 .Cm kEDH Ns :! Ns Cm aNULL
225 except for the order of the cipher suites which are
226 .Em not
227 selected.
228 .It Cm DSS
229 An alias for
230 .Cm aDSS .
231 .It Cm ECDH
232 An alias for
233 .Cm kEECHD .
234 .It Cm ECDHE
235 Cipher suites using ephemeral ECDH for key exchange,
236 but excluding those that don't do any server authentication.
237 Similar to
238 .Cm kEECDH Ns :! Ns Cm aNULL
239 except for the order of the cipher suites which are
240 .Em not
241 selected.
242 .It Cm ECDSA
243 An alias for
244 .Cm aECDSA .
245 .It Cm EDH
246 An alias for
247 .Cm DHE .
248 .It Cm EECHD
249 An alias for
250 .Cm ECDHE .
251 .It Cm eNULL
252 Cipher suites that do not use any encryption.
253 Not enabled by
254 .Cm DEFAULT ,
255 and not even included in
256 .Cm ALL .
257 .It Cm GOST89MAC
258 Cipher suites using GOST 28147-89 for message authentication
259 instead of HMAC.
260 .It Cm GOST94
261 Cipher suites using HMAC based on GOST R 34.11-94
262 for message authentication.
263 .It Cm HIGH
264 Cipher suites of high strength.
265 Currently, these are cipher suites using
266 .Cm CHACHA20 ,
267 .Cm AES ,
268 .Cm CAMELLIA ,
269 or GOST-28178-89-CNT symmetric encryption.
270 .It Cm IDEA
271 Cipher suites using IDEA for symmetric encryption.
272 LibreSSL does not provide any such cipher suites.
273 .It Cm kEDH
274 Cipher suites using ephemeral DH for key exchange.
275 .It Cm kEECDH
276 Cipher suites using ephemeral ECDH for key exchange.
277 .It Cm kGOST
278 Cipher suites using VKO 34.10 key exchange, specified in RFC 4357.
279 .It Cm kRSA
280 Cipher suites using RSA key exchange.
281 .It Cm LOW
282 Cipher suites of low strength.
283 Currently, these are cipher suites using
284 .Cm DES
285 or
286 .Cm RC4
287 symmetric encryption.
288 .It Cm MD5
289 Cipher suites using MD5 for message authentication.
290 .It Cm MEDIUM
291 Cipher suites of medium strength.
292 Currently, these are cipher suites using
293 .Cm 3DES
294 symmetric encryption.
295 .It Cm NULL
296 An alias for
297 .Cm eNULL .
298 .It Cm RC4
299 Cipher suites using RC4 for symmetric encryption.
300 .It Cm RSA
301 Cipher suites using RSA for both key exchange and server authentication.
302 Equivalent to
303 .Cm kRSA Ns + Ns Cm aRSA .
304 .It Cm SHA
305 An alias for
306 .Cm SHA1 .
307 .It Cm SHA1
308 Cipher suites using SHA1 for message authentication.
309 .It Cm SHA256
310 Cipher suites using SHA256 for message authentication.
311 .It Cm SHA384
312 Cipher suites using SHA384 for message authentication.
313 .It Cm SSLv3
314 An alias for
315 .Cm TLSv1 .
316 .It Cm STREEBOG256
317 Cipher suites using STREEBOG256 for message authentication.
318 .It Cm TLSv1
319 Cipher suites usable with any TLS protocol.
320 .It Cm TLSv1.2
321 Cipher suites for the TLSv1.2 protocol.
322 .El
323 .Pp
324 The full words returned by the
325 .Xr openssl 1
326 .Cm ciphers
327 command can be used to select individual cipher suites.
328 .Pp
329 Unknown words are silently ignored, selecting no cipher suites.
330 Failure is only flagged if the
331 .Fa control
332 string contains invalid bytes
333 or if no matching cipher suites are available at all.
334 .Pp
335 On the client side, including a cipher suite into the list of
336 available cipher suites is sufficient for using it.
337 On the server side, all cipher suites have additional requirements.
338 ADH ciphers don't need a certificate, but DH-parameters must have been set.
339 All other cipher suites need a corresponding certificate and key.
340 .Pp
341 A RSA cipher can only be chosen when a RSA certificate is available.
342 RSA ciphers using DHE need a certificate and key and additional DH-parameters
343 (see
344 .Xr SSL_CTX_set_tmp_dh_callback 3 ) .
345 .Pp
346 A DSA cipher can only be chosen when a DSA certificate is available.
347 DSA ciphers always use DH key exchange and therefore need DH-parameters (see
348 .Xr SSL_CTX_set_tmp_dh_callback 3 ) .
349 .Pp
350 When these conditions are not met
351 for any cipher suite in the list (for example, a
352 client only supports export RSA ciphers with an asymmetric key length of 512
353 bits and the server is not configured to use temporary RSA keys), the
354 .Dq no shared cipher
355 .Pq Dv SSL_R_NO_SHARED_CIPHER
356 error is generated and the handshake will fail.
357 .Sh RETURN VALUES
358 .Fn SSL_CTX_set_cipher_list
359 and
360 .Fn SSL_set_cipher_list
361 return 1 if any cipher suite could be selected and 0 on complete failure.
362 .Sh SEE ALSO
363 .Xr ssl 3 ,
364 .Xr SSL_CTX_set1_groups 3 ,
365 .Xr SSL_CTX_set_tmp_dh_callback 3 ,
366 .Xr SSL_CTX_use_certificate 3 ,
367 .Xr SSL_get_ciphers 3
368 .Sh HISTORY
369 .Fn SSL_CTX_set_cipher_list
370 and
371 .Fn SSL_set_cipher_list
372 first appeared in SSLeay 0.5.2 and have been available since
373 .Ox 2.4 .