doc/man1/openssl-enc.pod.in

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