b7e577b24f8db4ec7188a7da082bca3ef53f8146
[openssl.git] / doc / apps / ciphers.pod
1 =pod
2
3 =head1 NAME
4
5 ciphers - SSL cipher display and cipher list tool.
6
7 =head1 SYNOPSIS
8
9 B<openssl> B<ciphers>
10 [B<-v>]
11 [B<-ssl2>]
12 [B<-ssl3>]
13 [B<-tls1>]
14 [B<cipherlist>]
15
16 =head1 DESCRIPTION
17
18 The B<cipherlist> command converts OpenSSL cipher lists into ordered
19 SSL cipher preference lists. It can be used as a test tool to determine
20 the appropriate cipherlist.
21
22 =head1 COMMAND OPTIONS
23
24 =over 4
25
26 =item B<-v>
27
28 verbose option. List ciphers with a complete description of
29 protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange,
30 authentication, encryption and mac algorithms used along with any key size
31 restrictions and whether the algorithm is classed as an "export" cipher.
32 Note that without the B<-v> option, ciphers may seem to appear twice
33 in a cipher list; this is when similar ciphers are available for
34 SSL v2 and for SSL v3/TLS v1.
35
36 =item B<-ssl3>
37
38 only include SSL v3 ciphers.
39
40 =item B<-ssl2>
41
42 only include SSL v2 ciphers.
43
44 =item B<-tls1>
45
46 only include TLS v1 ciphers.
47
48 =item B<-h>, B<-?>
49
50 print a brief usage message.
51
52 =item B<cipherlist>
53
54 a cipher list to convert to a cipher preference list. If it is not included
55 then the default cipher list will be used. The format is described below.
56
57 =back
58
59 =head1 CIPHER LIST FORMAT
60
61 The cipher list consists of one or more I<cipher strings> separated by colons.
62 Commas or spaces are also acceptable separators but colons are normally used.
63
64 The actual cipher string can take several different forms.
65
66 It can consist of a single cipher suite such as B<RC4-SHA>.
67
68 It can represent a list of cipher suites containing a certain algorithm, or
69 cipher suites of a certain type. For example B<SHA1> represents all ciphers
70 suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3
71 algorithms.
72
73 Lists of cipher suites can be combined in a single cipher string using the
74 B<+> character. This is used as a logical B<and> operation. For example
75 B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES
76 algorithms.
77
78 Each cipher string can be optionally preceded by the characters B<!>,
79 B<-> or B<+>.
80
81 If B<!> is used then the ciphers are permanently deleted from the list.
82 The ciphers deleted can never reappear in the list even if they are
83 explicitly stated.
84
85 If B<-> is used then the ciphers are deleted from the list, but some or
86 all of the ciphers can be added again by later options.
87
88 If B<+> is used then the ciphers are moved to the end of the list. This
89 option doesn't add any new ciphers it just moves matching existing ones.
90
91 If none of these characters is present then the string is just interpreted
92 as a list of ciphers to be appended to the current preference list. If the
93 list includes any ciphers already present they will be ignored: that is they
94 will not moved to the end of the list.
95
96 Additionally the cipher string B<@STRENGTH> can be used at any point to sort
97 the current cipher list in order of encryption algorithm key length.
98
99 =head1 CIPHER STRINGS
100
101 The following is a list of all permitted cipher strings and their meanings.
102
103 =over 4
104
105 =item B<DEFAULT>
106
107 the default cipher list. This is determined at compile time and is normally
108 B<ALL:!ADH:RC4+RSA:+SSLv2:@STRENGTH>. This must be the first cipher string
109 specified.
110
111 =item B<COMPLEMENTOFDEFAULT>
112
113 the ciphers included in B<ALL>, but not enabled by default. Currently
114 this is B<ADH>. Note that this rule does not cover B<eNULL>, which is
115 not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
116
117 =item B<ALL>
118
119 all ciphers suites except the B<eNULL> ciphers which must be explicitly enabled.
120
121 =item B<COMPLEMENTOFALL>
122
123 the cipher suites not enabled by B<ALL>, currently being B<eNULL>.
124
125 =item B<HIGH>
126
127 "high" encryption cipher suites. This currently means those with key lengths larger
128 than 128 bits.
129
130 =item B<MEDIUM>
131
132 "medium" encryption cipher suites, currently those using 128 bit encryption.
133
134 =item B<LOW>
135
136 "low" encryption cipher suites, currently those using 64 or 56 bit encryption algorithms
137 but excluding export cipher suites.
138
139 =item B<EXP>, B<EXPORT>
140
141 export encryption algorithms. Including 40 and 56 bits algorithms.
142
143 =item B<EXPORT40>
144
145 40 bit export encryption algorithms
146
147 =item B<EXPORT56>
148
149 56 bit export encryption algorithms.
150
151 =item B<eNULL>, B<NULL>
152
153 the "NULL" ciphers that is those offering no encryption. Because these offer no
154 encryption at all and are a security risk they are disabled unless explicitly
155 included.
156
157 =item B<aNULL>
158
159 the cipher suites offering no authentication. This is currently the anonymous
160 DH algorithms. These cipher suites are vulnerable to a "man in the middle"
161 attack and so their use is normally discouraged.
162
163 =item B<kRSA>, B<RSA>
164
165 cipher suites using RSA key exchange.
166
167 =item B<kEDH>
168
169 cipher suites using ephemeral DH key agreement.
170
171 =item B<kDHr>, B<kDHd>
172
173 cipher suites using DH key agreement and DH certificates signed by CAs with RSA
174 and DSS keys respectively. Not implemented.
175
176 =item B<aRSA>
177
178 cipher suites using RSA authentication, i.e. the certificates carry RSA keys.
179
180 =item B<aDSS>, B<DSS>
181
182 cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
183
184 =item B<aDH>
185
186 cipher suites effectively using DH authentication, i.e. the certificates carry
187 DH keys.  Not implemented.
188
189 =item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA>
190
191 ciphers suites using FORTEZZA key exchange, authentication, encryption or all
192 FORTEZZA algorithms. Not implemented.
193
194 =item B<TLSv1>, B<SSLv3>, B<SSLv2>
195
196 TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively.
197
198 =item B<DH>
199
200 cipher suites using DH, including anonymous DH.
201
202 =item B<ADH>
203
204 anonymous DH cipher suites.
205
206 =item B<3DES>
207
208 cipher suites using triple DES.
209
210 =item B<DES>
211
212 cipher suites using DES (not triple DES).
213
214 =item B<RC4>
215
216 cipher suites using RC4.
217
218 =item B<RC2>
219
220 cipher suites using RC2.
221
222 =item B<IDEA>
223
224 cipher suites using IDEA.
225
226 =item B<MD5>
227
228 cipher suites using MD5.
229
230 =item B<SHA1>, B<SHA>
231
232 cipher suites using SHA1.
233
234 =back
235
236 =head1 CIPHER SUITE NAMES
237
238 The following lists give the SSL or TLS cipher suites names from the
239 relevant specification and their OpenSSL equivalents.
240
241 =head2 SSL v3.0 cipher suites.
242
243  SSL_RSA_WITH_NULL_MD5                   NULL-MD5
244  SSL_RSA_WITH_NULL_SHA                   NULL-SHA
245  SSL_RSA_EXPORT_WITH_RC4_40_MD5          EXP-RC4-MD5
246  SSL_RSA_WITH_RC4_128_MD5                RC4-MD5
247  SSL_RSA_WITH_RC4_128_SHA                RC4-SHA
248  SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5      EXP-RC2-CBC-MD5
249  SSL_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA
250  SSL_RSA_EXPORT_WITH_DES40_CBC_SHA       EXP-DES-CBC-SHA
251  SSL_RSA_WITH_DES_CBC_SHA                DES-CBC-SHA
252  SSL_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA
253
254  SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA    Not implemented.
255  SSL_DH_DSS_WITH_DES_CBC_SHA             Not implemented.
256  SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA        Not implemented.
257  SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA    Not implemented.
258  SSL_DH_RSA_WITH_DES_CBC_SHA             Not implemented.
259  SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA        Not implemented.
260  SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA   EXP-EDH-DSS-DES-CBC-SHA
261  SSL_DHE_DSS_WITH_DES_CBC_SHA            EDH-DSS-CBC-SHA
262  SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA       EDH-DSS-DES-CBC3-SHA
263  SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA   EXP-EDH-RSA-DES-CBC-SHA
264  SSL_DHE_RSA_WITH_DES_CBC_SHA            EDH-RSA-DES-CBC-SHA
265  SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA       EDH-RSA-DES-CBC3-SHA
266
267  SSL_DH_anon_EXPORT_WITH_RC4_40_MD5      EXP-ADH-RC4-MD5
268  SSL_DH_anon_WITH_RC4_128_MD5            ADH-RC4-MD5
269  SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA   EXP-ADH-DES-CBC-SHA
270  SSL_DH_anon_WITH_DES_CBC_SHA            ADH-DES-CBC-SHA
271  SSL_DH_anon_WITH_3DES_EDE_CBC_SHA       ADH-DES-CBC3-SHA
272
273  SSL_FORTEZZA_KEA_WITH_NULL_SHA          Not implemented.
274  SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA  Not implemented.
275  SSL_FORTEZZA_KEA_WITH_RC4_128_SHA       Not implemented.
276
277 =head2 TLS v1.0 cipher suites.
278
279  TLS_RSA_WITH_NULL_MD5                   NULL-MD5
280  TLS_RSA_WITH_NULL_SHA                   NULL-SHA
281  TLS_RSA_EXPORT_WITH_RC4_40_MD5          EXP-RC4-MD5
282  TLS_RSA_WITH_RC4_128_MD5                RC4-MD5
283  TLS_RSA_WITH_RC4_128_SHA                RC4-SHA
284  TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5      EXP-RC2-CBC-MD5
285  TLS_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA
286  TLS_RSA_EXPORT_WITH_DES40_CBC_SHA       EXP-DES-CBC-SHA
287  TLS_RSA_WITH_DES_CBC_SHA                DES-CBC-SHA
288  TLS_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA
289
290  TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA    Not implemented.
291  TLS_DH_DSS_WITH_DES_CBC_SHA             Not implemented.
292  TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA        Not implemented.
293  TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA    Not implemented.
294  TLS_DH_RSA_WITH_DES_CBC_SHA             Not implemented.
295  TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA        Not implemented.
296  TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA   EXP-EDH-DSS-DES-CBC-SHA
297  TLS_DHE_DSS_WITH_DES_CBC_SHA            EDH-DSS-CBC-SHA
298  TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA       EDH-DSS-DES-CBC3-SHA
299  TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA   EXP-EDH-RSA-DES-CBC-SHA
300  TLS_DHE_RSA_WITH_DES_CBC_SHA            EDH-RSA-DES-CBC-SHA
301  TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA       EDH-RSA-DES-CBC3-SHA
302
303  TLS_DH_anon_EXPORT_WITH_RC4_40_MD5      EXP-ADH-RC4-MD5
304  TLS_DH_anon_WITH_RC4_128_MD5            ADH-RC4-MD5
305  TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA   EXP-ADH-DES-CBC-SHA
306  TLS_DH_anon_WITH_DES_CBC_SHA            ADH-DES-CBC-SHA
307  TLS_DH_anon_WITH_3DES_EDE_CBC_SHA       ADH-DES-CBC3-SHA
308
309 =head2 Additional Export 1024 and other cipher suites
310
311 Note: these ciphers can also be used in SSL v3.
312
313  TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA     EXP1024-DES-CBC-SHA
314  TLS_RSA_EXPORT1024_WITH_RC4_56_SHA      EXP1024-RC4-SHA
315  TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DHE-DSS-DES-CBC-SHA
316  TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA  EXP1024-DHE-DSS-RC4-SHA
317  TLS_DHE_DSS_WITH_RC4_128_SHA            DHE-DSS-RC4-SHA
318
319 =head2 SSL v2.0 cipher suites.
320
321  SSL_CK_RC4_128_WITH_MD5                 RC4-MD5
322  SSL_CK_RC4_128_EXPORT40_WITH_MD5        EXP-RC4-MD5
323  SSL_CK_RC2_128_CBC_WITH_MD5             RC2-MD5
324  SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5    EXP-RC2-MD5
325  SSL_CK_IDEA_128_CBC_WITH_MD5            IDEA-CBC-MD5
326  SSL_CK_DES_64_CBC_WITH_MD5              DES-CBC-MD5
327  SSL_CK_DES_192_EDE3_CBC_WITH_MD5        DES-CBC3-MD5
328
329 =head1 NOTES
330
331 The non-ephemeral DH modes are currently unimplemented in OpenSSL
332 because there is no support for DH certificates.
333
334 Some compiled versions of OpenSSL may not include all the ciphers
335 listed here because some ciphers were excluded at compile time.
336
337 =head1 EXAMPLES
338
339 Verbose listing of all OpenSSL ciphers including NULL ciphers:
340
341  openssl ciphers -v 'ALL:eNULL'
342
343 Include all ciphers except NULL and anonymous DH then sort by
344 strength:
345
346  openssl ciphers -v 'ALL:!ADH:@STRENGTH'
347
348 Include only 3DES ciphers and then place RSA ciphers last:
349
350  openssl ciphers -v '3DES:+RSA'
351
352 Include all RC4 ciphers but leave out those without authentication:
353
354  openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
355
356 Include all chiphers with RSA authentication but leave out ciphers without
357 encryption.
358
359  openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
360
361 =head1 SEE ALSO
362
363 L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)>
364
365 =head1 HISTORY
366
367 The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options were
368 added in version 0.9.7.
369
370 =cut