]>
Commit | Line | Data |
---|---|---|
a0e9f529 | 1 | =pod |
19d2bb57 | 2 | |
a0e9f529 DSH |
3 | =head1 NAME |
4 | ||
3f2181e6 | 5 | openssl-enc, |
a0e9f529 DSH |
6 | enc - symmetric cipher routines |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
e75138ab | 10 | B<openssl enc -I<cipher>> |
169394d4 | 11 | [B<-help>] |
3b5bea36 | 12 | [B<-ciphers>] |
a0e9f529 DSH |
13 | [B<-in filename>] |
14 | [B<-out filename>] | |
cd3c54e5 | 15 | [B<-pass arg>] |
a0e9f529 DSH |
16 | [B<-e>] |
17 | [B<-d>] | |
e75138ab RS |
18 | [B<-a>] |
19 | [B<-base64>] | |
a0e9f529 DSH |
20 | [B<-A>] |
21 | [B<-k password>] | |
22 | [B<-kfile filename>] | |
23 | [B<-K key>] | |
24 | [B<-iv IV>] | |
e5fa864f DSH |
25 | [B<-S salt>] |
26 | [B<-salt>] | |
27 | [B<-nosalt>] | |
28 | [B<-z>] | |
9e8b6f04 | 29 | [B<-md digest>] |
a0e9f529 DSH |
30 | [B<-p>] |
31 | [B<-P>] | |
32 | [B<-bufsize number>] | |
f2e5ca84 | 33 | [B<-nopad>] |
a0e9f529 | 34 | [B<-debug>] |
e5fa864f | 35 | [B<-none>] |
3ee1eac2 RS |
36 | [B<-rand file...>] |
37 | [B<-writerand file>] | |
e5fa864f | 38 | [B<-engine id>] |
a0e9f529 | 39 | |
e75138ab RS |
40 | B<openssl> I<[cipher]> [B<...>] |
41 | ||
a0e9f529 DSH |
42 | =head1 DESCRIPTION |
43 | ||
19d2bb57 | 44 | The symmetric cipher commands allow data to be encrypted or decrypted |
a0e9f529 DSH |
45 | using various block and stream ciphers using keys based on passwords |
46 | or explicitly provided. Base64 encoding or decoding can also be performed | |
47 | either by itself or in addition to the encryption or decryption. | |
48 | ||
49 | =head1 OPTIONS | |
50 | ||
51 | =over 4 | |
52 | ||
169394d4 MR |
53 | =item B<-help> |
54 | ||
55 | Print out a usage message. | |
56 | ||
3b5bea36 RS |
57 | =item B<-ciphers> |
58 | ||
59 | List all supported ciphers. | |
60 | ||
a0e9f529 DSH |
61 | =item B<-in filename> |
62 | ||
3fd5ece3 | 63 | The input filename, standard input by default. |
a0e9f529 DSH |
64 | |
65 | =item B<-out filename> | |
66 | ||
3fd5ece3 | 67 | The output filename, standard output by default. |
a0e9f529 | 68 | |
cd3c54e5 DSH |
69 | =item B<-pass arg> |
70 | ||
3fd5ece3 | 71 | The password source. For more information about the format of B<arg> |
9b86974e | 72 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. |
cd3c54e5 | 73 | |
a0e9f529 DSH |
74 | =item B<-e> |
75 | ||
3fd5ece3 | 76 | Encrypt the input data: this is the default. |
a0e9f529 DSH |
77 | |
78 | =item B<-d> | |
79 | ||
3fd5ece3 | 80 | Decrypt the input data. |
a0e9f529 DSH |
81 | |
82 | =item B<-a> | |
83 | ||
3fd5ece3 | 84 | Base64 process the data. This means that if encryption is taking place |
a0e9f529 DSH |
85 | the data is base64 encoded after encryption. If decryption is set then |
86 | the input data is base64 decoded before being decrypted. | |
87 | ||
e5fa864f DSH |
88 | =item B<-base64> |
89 | ||
3fd5ece3 | 90 | Same as B<-a> |
e5fa864f | 91 | |
a0e9f529 DSH |
92 | =item B<-A> |
93 | ||
3fd5ece3 | 94 | If the B<-a> option is set then base64 process the data on one line. |
a0e9f529 DSH |
95 | |
96 | =item B<-k password> | |
97 | ||
3fd5ece3 | 98 | The password to derive the key from. This is for compatibility with previous |
cd3c54e5 | 99 | versions of OpenSSL. Superseded by the B<-pass> argument. |
a0e9f529 DSH |
100 | |
101 | =item B<-kfile filename> | |
102 | ||
3fd5ece3 | 103 | Read the password to derive the key from the first line of B<filename>. |
e544b0dc | 104 | This is for compatibility with previous versions of OpenSSL. Superseded by |
cd3c54e5 | 105 | the B<-pass> argument. |
a0e9f529 | 106 | |
9e8b6f04 RS |
107 | =item B<-md digest> |
108 | ||
109 | Use the specified digest to create the key from the passphrase. | |
110 | The default algorithm is sha-256. | |
111 | ||
e5fa864f DSH |
112 | =item B<-nosalt> |
113 | ||
3fd5ece3 | 114 | Don't use a salt in the key derivation routines. This option B<SHOULD NOT> be |
ed233db7 RS |
115 | used except for test purposes or compatibility with ancient versions of |
116 | OpenSSL. | |
e5fa864f DSH |
117 | |
118 | =item B<-salt> | |
119 | ||
3fd5ece3 P |
120 | Use salt (randomly generated or provide with B<-S> option) when |
121 | encrypting, this is the default. | |
e5fa864f | 122 | |
fd699ac5 DSH |
123 | =item B<-S salt> |
124 | ||
3fd5ece3 | 125 | The actual salt to use: this must be represented as a string of hex digits. |
fd699ac5 | 126 | |
a0e9f529 DSH |
127 | =item B<-K key> |
128 | ||
3fd5ece3 | 129 | The actual key to use: this must be represented as a string comprised only |
43f9391b LJ |
130 | of hex digits. If only the key is specified, the IV must additionally specified |
131 | using the B<-iv> option. When both a key and a password are specified, the | |
132 | key given with the B<-K> option will be used and the IV generated from the | |
3fd5ece3 P |
133 | password will be taken. It does not make much sense to specify both key |
134 | and password. | |
a0e9f529 DSH |
135 | |
136 | =item B<-iv IV> | |
137 | ||
3fd5ece3 | 138 | The actual IV to use: this must be represented as a string comprised only |
43f9391b LJ |
139 | of hex digits. When only the key is specified using the B<-K> option, the |
140 | IV must explicitly be defined. When a password is being specified using | |
141 | one of the other options, the IV is generated from this password. | |
a0e9f529 DSH |
142 | |
143 | =item B<-p> | |
144 | ||
3fd5ece3 | 145 | Print out the key and IV used. |
a0e9f529 DSH |
146 | |
147 | =item B<-P> | |
148 | ||
3fd5ece3 | 149 | Print out the key and IV used then immediately exit: don't do any encryption |
a0e9f529 DSH |
150 | or decryption. |
151 | ||
152 | =item B<-bufsize number> | |
153 | ||
3fd5ece3 | 154 | Set the buffer size for I/O. |
a0e9f529 | 155 | |
f2e5ca84 DSH |
156 | =item B<-nopad> |
157 | ||
3fd5ece3 | 158 | Disable standard block padding. |
f2e5ca84 | 159 | |
a0e9f529 DSH |
160 | =item B<-debug> |
161 | ||
3fd5ece3 | 162 | Debug the BIOs used for I/O. |
a0e9f529 | 163 | |
e5fa864f DSH |
164 | =item B<-z> |
165 | ||
166 | Compress or decompress clear text using zlib before encryption or after | |
167 | decryption. This option exists only if OpenSSL with compiled with zlib | |
168 | or zlib-dynamic option. | |
169 | ||
170 | =item B<-none> | |
171 | ||
172 | Use NULL cipher (no encryption or decryption of input). | |
173 | ||
3ee1eac2 RS |
174 | =item B<-rand file...> |
175 | ||
176 | A file or files containing random data used to seed the random number | |
177 | generator. | |
178 | Multiple files can be specified separated by an OS-dependent character. | |
179 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for | |
180 | all others. | |
181 | ||
182 | =item [B<-writerand file>] | |
183 | ||
184 | Writes random data to the specified I<file> upon exit. | |
185 | This can be used with a subsequent B<-rand> flag. | |
186 | ||
a0e9f529 DSH |
187 | =back |
188 | ||
189 | =head1 NOTES | |
190 | ||
e75138ab RS |
191 | The program can be called either as B<openssl cipher> or |
192 | B<openssl enc -cipher>. The first form doesn't work with | |
e5fa864f DSH |
193 | engine-provided ciphers, because this form is processed before the |
194 | configuration file is read and any ENGINEs loaded. | |
e75138ab | 195 | Use the B<list> command to get a list of supported ciphers. |
e5fa864f | 196 | |
3fd5ece3 | 197 | Engines which provide entirely new encryption algorithms (such as the ccgost |
e5fa864f | 198 | engine which provides gost89 algorithm) should be configured in the |
3fd5ece3 | 199 | configuration file. Engines specified on the command line using -engine |
4c583c36 | 200 | options can only be used for hardware-assisted implementations of |
3fd5ece3 | 201 | ciphers which are supported by the OpenSSL core or another engine specified |
e5fa864f DSH |
202 | in the configuration file. |
203 | ||
3fd5ece3 | 204 | When the enc command lists supported ciphers, ciphers provided by engines, |
e5fa864f | 205 | specified in the configuration files are listed too. |
a0e9f529 DSH |
206 | |
207 | A password will be prompted for to derive the key and IV if necessary. | |
208 | ||
6d1b637b | 209 | The B<-salt> option should B<ALWAYS> be used if the key is being derived |
19d2bb57 | 210 | from a password unless you want compatibility with previous versions of |
b0700d2c | 211 | OpenSSL. |
fd699ac5 DSH |
212 | |
213 | Without the B<-salt> option it is possible to perform efficient dictionary | |
214 | attacks on the password and to attack stream cipher encrypted data. The reason | |
215 | for this is that without the salt the same password always generates the same | |
216 | encryption key. When the salt is being used the first eight bytes of the | |
217 | encrypted data are reserved for the salt: it is generated at random when | |
218 | encrypting a file and read from the encrypted file when it is decrypted. | |
219 | ||
4abc5c62 DSH |
220 | Some of the ciphers do not have large keys and others have security |
221 | implications if not used correctly. A beginner is advised to just use | |
3fd5ece3 | 222 | a strong block cipher, such as AES, in CBC mode. |
4abc5c62 | 223 | |
3fd5ece3 P |
224 | All the block ciphers normally use PKCS#5 padding, also known as standard |
225 | block padding. This allows a rudimentary integrity or password check to | |
226 | be performed. However since the chance of random data passing the test | |
227 | is better than 1 in 256 it isn't a very good test. | |
a0e9f529 | 228 | |
3b80e3aa | 229 | If padding is disabled then the input data must be a multiple of the cipher |
f2e5ca84 DSH |
230 | block length. |
231 | ||
a0e9f529 DSH |
232 | All RC2 ciphers have the same key and effective key length. |
233 | ||
234 | Blowfish and RC5 algorithms use a 128 bit key. | |
235 | ||
236 | =head1 SUPPORTED CIPHERS | |
237 | ||
e5fa864f DSH |
238 | Note that some of these ciphers can be disabled at compile time |
239 | and some are available only if an appropriate engine is configured | |
240 | in the configuration file. The output of the B<enc> command run with | |
3fd5ece3 | 241 | the B<-ciphers> option (that is B<openssl enc -ciphers>) produces a |
4c583c36 | 242 | list of ciphers, supported by your version of OpenSSL, including |
e5fa864f DSH |
243 | ones provided by configured engines. |
244 | ||
d4b47504 | 245 | The B<enc> program does not support authenticated encryption modes |
272cc20b BK |
246 | like CCM and GCM, and will not support such modes in the future. |
247 | The B<enc> interface by necessity must begin streaming output (e.g., | |
248 | to standard output when B<-out> is not used before the authentication | |
249 | tag could be validated, leading to the usage of B<enc> in pipelines | |
250 | that begin processing untrusted data and are not capable of rolling | |
251 | back upon authentication failure. The AEAD modes currently in common | |
252 | use also suffer from catastrophic failure of confidentiality and/or | |
253 | integrity upon reuse of key/iv/nonce, and since B<enc> places the | |
254 | entire burden of key/iv/nonce management upon the user, the risk of | |
255 | exposing AEAD modes is too great to allow. These key/iv/nonce | |
256 | management issues also affect other modes currently exposed in B<enc>, | |
257 | but the failure modes are less extreme in these cases, and the | |
258 | functionality cannot be removed with a stable release branch. | |
259 | For bulk encryption of data, whether using authenticated encryption | |
260 | modes or other modes, L<cms(1)> is recommended, as it provides a | |
261 | standard data format and performs the needed key/iv/nonce management. | |
d4b47504 | 262 | |
e5fa864f | 263 | |
a0e9f529 DSH |
264 | base64 Base 64 |
265 | ||
266 | bf-cbc Blowfish in CBC mode | |
267 | bf Alias for bf-cbc | |
19d2bb57 | 268 | bf-cfb Blowfish in CFB mode |
a0e9f529 DSH |
269 | bf-ecb Blowfish in ECB mode |
270 | bf-ofb Blowfish in OFB mode | |
271 | ||
272 | cast-cbc CAST in CBC mode | |
273 | cast Alias for cast-cbc | |
274 | cast5-cbc CAST5 in CBC mode | |
275 | cast5-cfb CAST5 in CFB mode | |
276 | cast5-ecb CAST5 in ECB mode | |
277 | cast5-ofb CAST5 in OFB mode | |
278 | ||
279 | des-cbc DES in CBC mode | |
280 | des Alias for des-cbc | |
47c07020 | 281 | des-cfb DES in CFB mode |
a0e9f529 DSH |
282 | des-ofb DES in OFB mode |
283 | des-ecb DES in ECB mode | |
284 | ||
285 | des-ede-cbc Two key triple DES EDE in CBC mode | |
701d35d1 | 286 | des-ede Two key triple DES EDE in ECB mode |
a0e9f529 DSH |
287 | des-ede-cfb Two key triple DES EDE in CFB mode |
288 | des-ede-ofb Two key triple DES EDE in OFB mode | |
289 | ||
290 | des-ede3-cbc Three key triple DES EDE in CBC mode | |
701d35d1 | 291 | des-ede3 Three key triple DES EDE in ECB mode |
a0e9f529 DSH |
292 | des3 Alias for des-ede3-cbc |
293 | des-ede3-cfb Three key triple DES EDE CFB mode | |
294 | des-ede3-ofb Three key triple DES EDE in OFB mode | |
295 | ||
296 | desx DESX algorithm. | |
297 | ||
e5fa864f | 298 | gost89 GOST 28147-89 in CFB mode (provided by ccgost engine) |
1bc74519 | 299 | gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine) |
e5fa864f | 300 | |
a0e9f529 DSH |
301 | idea-cbc IDEA algorithm in CBC mode |
302 | idea same as idea-cbc | |
303 | idea-cfb IDEA in CFB mode | |
304 | idea-ecb IDEA in ECB mode | |
305 | idea-ofb IDEA in OFB mode | |
306 | ||
307 | rc2-cbc 128 bit RC2 in CBC mode | |
308 | rc2 Alias for rc2-cbc | |
60021d91 RL |
309 | rc2-cfb 128 bit RC2 in CFB mode |
310 | rc2-ecb 128 bit RC2 in ECB mode | |
311 | rc2-ofb 128 bit RC2 in OFB mode | |
a0e9f529 DSH |
312 | rc2-64-cbc 64 bit RC2 in CBC mode |
313 | rc2-40-cbc 40 bit RC2 in CBC mode | |
314 | ||
315 | rc4 128 bit RC4 | |
316 | rc4-64 64 bit RC4 | |
317 | rc4-40 40 bit RC4 | |
318 | ||
319 | rc5-cbc RC5 cipher in CBC mode | |
320 | rc5 Alias for rc5-cbc | |
60021d91 RL |
321 | rc5-cfb RC5 cipher in CFB mode |
322 | rc5-ecb RC5 cipher in ECB mode | |
323 | rc5-ofb RC5 cipher in OFB mode | |
a0e9f529 | 324 | |
1bc74519 RS |
325 | aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode |
326 | aes[128|192|256] Alias for aes-[128|192|256]-cbc | |
327 | aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode | |
328 | aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode | |
329 | aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode | |
3fd5ece3 | 330 | aes-[128|192|256]-ctr 128/192/256 bit AES in CTR mode |
1bc74519 RS |
331 | aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode |
332 | aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode | |
330591fd | 333 | |
3fd5ece3 P |
334 | camellia-[128|192|256]-cbc 128/192/256 bit Camellia in CBC mode |
335 | camellia[128|192|256] Alias for camellia-[128|192|256]-cbc | |
336 | camellia-[128|192|256]-cfb 128/192/256 bit Camellia in 128 bit CFB mode | |
337 | camellia-[128|192|256]-cfb1 128/192/256 bit Camellia in 1 bit CFB mode | |
338 | camellia-[128|192|256]-cfb8 128/192/256 bit Camellia in 8 bit CFB mode | |
339 | camellia-[128|192|256]-ctr 128/192/256 bit Camellia in CTR mode | |
340 | camellia-[128|192|256]-ecb 128/192/256 bit Camellia in ECB mode | |
341 | camellia-[128|192|256]-ofb 128/192/256 bit Camellia in OFB mode | |
342 | ||
a0e9f529 DSH |
343 | =head1 EXAMPLES |
344 | ||
4abc5c62 DSH |
345 | Just base64 encode a binary file: |
346 | ||
347 | openssl base64 -in file.bin -out file.b64 | |
348 | ||
349 | Decode the same file | |
350 | ||
1bc74519 | 351 | openssl base64 -d -in file.b64 -out file.bin |
4abc5c62 DSH |
352 | |
353 | Encrypt a file using triple DES in CBC mode using a prompted password: | |
354 | ||
1bc74519 | 355 | openssl des3 -salt -in file.txt -out file.des3 |
4abc5c62 DSH |
356 | |
357 | Decrypt a file using a supplied password: | |
358 | ||
fd699ac5 | 359 | openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword |
4abc5c62 DSH |
360 | |
361 | Encrypt a file then base64 encode it (so it can be sent via mail for example) | |
362 | using Blowfish in CBC mode: | |
363 | ||
fd699ac5 | 364 | openssl bf -a -salt -in file.txt -out file.bf |
4abc5c62 DSH |
365 | |
366 | Base64 decode a file then decrypt it: | |
367 | ||
fd699ac5 | 368 | openssl bf -d -salt -a -in file.bf -out file.txt |
4abc5c62 DSH |
369 | |
370 | Decrypt some data using a supplied 40 bit RC4 key: | |
371 | ||
372 | openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 | |
a0e9f529 DSH |
373 | |
374 | =head1 BUGS | |
375 | ||
376 | The B<-A> option when used with large files doesn't work properly. | |
377 | ||
fd699ac5 | 378 | There should be an option to allow an iteration count to be included. |
a0e9f529 | 379 | |
f2e5ca84 DSH |
380 | The B<enc> program only supports a fixed number of algorithms with |
381 | certain parameters. So if, for example, you want to use RC2 with a | |
382 | 76 bit key or RC4 with an 84 bit key you can't use this program. | |
a0e9f529 | 383 | |
9e8b6f04 RS |
384 | =head1 HISTORY |
385 | ||
a95d7574 | 386 | The default digest was changed from MD5 to SHA256 in Openssl 1.1.0. |
9e8b6f04 | 387 | |
e2f92610 RS |
388 | =head1 COPYRIGHT |
389 | ||
6738bf14 | 390 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
391 | |
392 | Licensed under the OpenSSL license (the "License"). You may not use | |
393 | this file except in compliance with the License. You can obtain a copy | |
394 | in the file LICENSE in the source distribution or at | |
395 | L<https://www.openssl.org/source/license.html>. | |
396 | ||
397 | =cut |