| 1 | =pod |
| 2 | |
| 3 | =head1 NAME |
| 4 | |
| 5 | enc - symmetric cipher routines |
| 6 | |
| 7 | =head1 SYNOPSIS |
| 8 | |
| 9 | B<openssl enc -ciphername> |
| 10 | [B<-in filename>] |
| 11 | [B<-out filename>] |
| 12 | [B<-pass arg>] |
| 13 | [B<-e>] |
| 14 | [B<-d>] |
| 15 | [B<-a>] |
| 16 | [B<-A>] |
| 17 | [B<-k password>] |
| 18 | [B<-kfile filename>] |
| 19 | [B<-K key>] |
| 20 | [B<-iv IV>] |
| 21 | [B<-p>] |
| 22 | [B<-P>] |
| 23 | [B<-bufsize number>] |
| 24 | [B<-nopad>] |
| 25 | [B<-debug>] |
| 26 | |
| 27 | =head1 DESCRIPTION |
| 28 | |
| 29 | The symmetric cipher commands allow data to be encrypted or decrypted |
| 30 | using various block and stream ciphers using keys based on passwords |
| 31 | or explicitly provided. Base64 encoding or decoding can also be performed |
| 32 | either by itself or in addition to the encryption or decryption. |
| 33 | |
| 34 | =head1 OPTIONS |
| 35 | |
| 36 | =over 4 |
| 37 | |
| 38 | =item B<-in filename> |
| 39 | |
| 40 | the input filename, standard input by default. |
| 41 | |
| 42 | =item B<-out filename> |
| 43 | |
| 44 | the output filename, standard output by default. |
| 45 | |
| 46 | =item B<-pass arg> |
| 47 | |
| 48 | the password source. For more information about the format of B<arg> |
| 49 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. |
| 50 | |
| 51 | =item B<-salt> |
| 52 | |
| 53 | use a salt in the key derivation routines. This option should B<ALWAYS> |
| 54 | be used unless compatibility with previous versions of OpenSSL or SSLeay |
| 55 | is required. This option is only present on OpenSSL versions 0.9.5 or |
| 56 | above. |
| 57 | |
| 58 | =item B<-nosalt> |
| 59 | |
| 60 | don't use a salt in the key derivation routines. This is the default for |
| 61 | compatibility with previous versions of OpenSSL and SSLeay. |
| 62 | |
| 63 | =item B<-e> |
| 64 | |
| 65 | encrypt the input data: this is the default. |
| 66 | |
| 67 | =item B<-d> |
| 68 | |
| 69 | decrypt the input data. |
| 70 | |
| 71 | =item B<-a> |
| 72 | |
| 73 | base64 process the data. This means that if encryption is taking place |
| 74 | the data is base64 encoded after encryption. If decryption is set then |
| 75 | the input data is base64 decoded before being decrypted. |
| 76 | |
| 77 | =item B<-A> |
| 78 | |
| 79 | if the B<-a> option is set then base64 process the data on one line. |
| 80 | |
| 81 | =item B<-k password> |
| 82 | |
| 83 | the password to derive the key from. This is for compatibility with previous |
| 84 | versions of OpenSSL. Superseded by the B<-pass> argument. |
| 85 | |
| 86 | =item B<-kfile filename> |
| 87 | |
| 88 | read the password to derive the key from the first line of B<filename>. |
| 89 | This is for compatibility with previous versions of OpenSSL. Superseded by |
| 90 | the B<-pass> argument. |
| 91 | |
| 92 | =item B<-S salt> |
| 93 | |
| 94 | the actual salt to use: this must be represented as a string comprised only |
| 95 | of hex digits. |
| 96 | |
| 97 | =item B<-K key> |
| 98 | |
| 99 | the actual key to use: this must be represented as a string comprised only |
| 100 | of hex digits. If only the key is specified, the IV must additionally specified |
| 101 | using the B<-iv> option. When both a key and a password are specified, the |
| 102 | key given with the B<-K> option will be used and the IV generated from the |
| 103 | password will be taken. It probably does not make much sense to specify |
| 104 | both key and password. |
| 105 | |
| 106 | =item B<-iv IV> |
| 107 | |
| 108 | the actual IV to use: this must be represented as a string comprised only |
| 109 | of hex digits. When only the key is specified using the B<-K> option, the |
| 110 | IV must explicitly be defined. When a password is being specified using |
| 111 | one of the other options, the IV is generated from this password. |
| 112 | |
| 113 | =item B<-p> |
| 114 | |
| 115 | print out the key and IV used. |
| 116 | |
| 117 | =item B<-P> |
| 118 | |
| 119 | print out the key and IV used then immediately exit: don't do any encryption |
| 120 | or decryption. |
| 121 | |
| 122 | =item B<-bufsize number> |
| 123 | |
| 124 | set the buffer size for I/O |
| 125 | |
| 126 | =item B<-nopad> |
| 127 | |
| 128 | disable standard block padding |
| 129 | |
| 130 | =item B<-debug> |
| 131 | |
| 132 | debug the BIOs used for I/O. |
| 133 | |
| 134 | =back |
| 135 | |
| 136 | =head1 NOTES |
| 137 | |
| 138 | The program can be called either as B<openssl ciphername> or |
| 139 | B<openssl enc -ciphername>. |
| 140 | |
| 141 | A password will be prompted for to derive the key and IV if necessary. |
| 142 | |
| 143 | The B<-salt> option should B<ALWAYS> be used if the key is being derived |
| 144 | from a password unless you want compatibility with previous versions of |
| 145 | OpenSSL and SSLeay. |
| 146 | |
| 147 | Without the B<-salt> option it is possible to perform efficient dictionary |
| 148 | attacks on the password and to attack stream cipher encrypted data. The reason |
| 149 | for this is that without the salt the same password always generates the same |
| 150 | encryption key. When the salt is being used the first eight bytes of the |
| 151 | encrypted data are reserved for the salt: it is generated at random when |
| 152 | encrypting a file and read from the encrypted file when it is decrypted. |
| 153 | |
| 154 | Some of the ciphers do not have large keys and others have security |
| 155 | implications if not used correctly. A beginner is advised to just use |
| 156 | a strong block cipher in CBC mode such as bf or des3. |
| 157 | |
| 158 | All the block ciphers normally use PKCS#5 padding also known as standard block |
| 159 | padding: this allows a rudimentary integrity or password check to be |
| 160 | performed. However since the chance of random data passing the test is |
| 161 | better than 1 in 256 it isn't a very good test. |
| 162 | |
| 163 | If padding is disabled then the input data must be a multiple of the cipher |
| 164 | block length. |
| 165 | |
| 166 | All RC2 ciphers have the same key and effective key length. |
| 167 | |
| 168 | Blowfish and RC5 algorithms use a 128 bit key. |
| 169 | |
| 170 | =head1 SUPPORTED CIPHERS |
| 171 | |
| 172 | base64 Base 64 |
| 173 | |
| 174 | bf-cbc Blowfish in CBC mode |
| 175 | bf Alias for bf-cbc |
| 176 | bf-cfb Blowfish in CFB mode |
| 177 | bf-ecb Blowfish in ECB mode |
| 178 | bf-ofb Blowfish in OFB mode |
| 179 | |
| 180 | cast-cbc CAST in CBC mode |
| 181 | cast Alias for cast-cbc |
| 182 | cast5-cbc CAST5 in CBC mode |
| 183 | cast5-cfb CAST5 in CFB mode |
| 184 | cast5-ecb CAST5 in ECB mode |
| 185 | cast5-ofb CAST5 in OFB mode |
| 186 | |
| 187 | des-cbc DES in CBC mode |
| 188 | des Alias for des-cbc |
| 189 | des-cfb DES in CBC mode |
| 190 | des-ofb DES in OFB mode |
| 191 | des-ecb DES in ECB mode |
| 192 | |
| 193 | des-ede-cbc Two key triple DES EDE in CBC mode |
| 194 | des-ede Two key triple DES EDE in ECB mode |
| 195 | des-ede-cfb Two key triple DES EDE in CFB mode |
| 196 | des-ede-ofb Two key triple DES EDE in OFB mode |
| 197 | |
| 198 | des-ede3-cbc Three key triple DES EDE in CBC mode |
| 199 | des-ede3 Three key triple DES EDE in ECB mode |
| 200 | des3 Alias for des-ede3-cbc |
| 201 | des-ede3-cfb Three key triple DES EDE CFB mode |
| 202 | des-ede3-ofb Three key triple DES EDE in OFB mode |
| 203 | |
| 204 | desx DESX algorithm. |
| 205 | |
| 206 | idea-cbc IDEA algorithm in CBC mode |
| 207 | idea same as idea-cbc |
| 208 | idea-cfb IDEA in CFB mode |
| 209 | idea-ecb IDEA in ECB mode |
| 210 | idea-ofb IDEA in OFB mode |
| 211 | |
| 212 | rc2-cbc 128 bit RC2 in CBC mode |
| 213 | rc2 Alias for rc2-cbc |
| 214 | rc2-cfb 128 bit RC2 in CFB mode |
| 215 | rc2-ecb 128 bit RC2 in ECB mode |
| 216 | rc2-ofb 128 bit RC2 in OFB mode |
| 217 | rc2-64-cbc 64 bit RC2 in CBC mode |
| 218 | rc2-40-cbc 40 bit RC2 in CBC mode |
| 219 | |
| 220 | rc4 128 bit RC4 |
| 221 | rc4-64 64 bit RC4 |
| 222 | rc4-40 40 bit RC4 |
| 223 | |
| 224 | rc5-cbc RC5 cipher in CBC mode |
| 225 | rc5 Alias for rc5-cbc |
| 226 | rc5-cfb RC5 cipher in CFB mode |
| 227 | rc5-ecb RC5 cipher in ECB mode |
| 228 | rc5-ofb RC5 cipher in OFB mode |
| 229 | |
| 230 | aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode |
| 231 | aes-[128|192|256] Alias for aes-[128|192|256]-cbc |
| 232 | aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode |
| 233 | aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode |
| 234 | aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode |
| 235 | aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode |
| 236 | aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode |
| 237 | |
| 238 | =head1 EXAMPLES |
| 239 | |
| 240 | Just base64 encode a binary file: |
| 241 | |
| 242 | openssl base64 -in file.bin -out file.b64 |
| 243 | |
| 244 | Decode the same file |
| 245 | |
| 246 | openssl base64 -d -in file.b64 -out file.bin |
| 247 | |
| 248 | Encrypt a file using triple DES in CBC mode using a prompted password: |
| 249 | |
| 250 | openssl des3 -salt -in file.txt -out file.des3 |
| 251 | |
| 252 | Decrypt a file using a supplied password: |
| 253 | |
| 254 | openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword |
| 255 | |
| 256 | Encrypt a file then base64 encode it (so it can be sent via mail for example) |
| 257 | using Blowfish in CBC mode: |
| 258 | |
| 259 | openssl bf -a -salt -in file.txt -out file.bf |
| 260 | |
| 261 | Base64 decode a file then decrypt it: |
| 262 | |
| 263 | openssl bf -d -salt -a -in file.bf -out file.txt |
| 264 | |
| 265 | Decrypt some data using a supplied 40 bit RC4 key: |
| 266 | |
| 267 | openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 |
| 268 | |
| 269 | =head1 BUGS |
| 270 | |
| 271 | The B<-A> option when used with large files doesn't work properly. |
| 272 | |
| 273 | There should be an option to allow an iteration count to be included. |
| 274 | |
| 275 | The B<enc> program only supports a fixed number of algorithms with |
| 276 | certain parameters. So if, for example, you want to use RC2 with a |
| 277 | 76 bit key or RC4 with an 84 bit key you can't use this program. |
| 278 | |
| 279 | =cut |