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