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