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