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