enc.pod revision 142425
1168054Sflz=pod 2168054Sflz 3168266Sgabor=head1 NAME 4168266Sgabor 5168266Sgaborenc - symmetric cipher routines 6168266Sgabor 7168266Sgabor=head1 SYNOPSIS 8168266Sgabor 9168266SgaborB<openssl enc -ciphername> 10168266Sgabor[B<-in filename>] 11168054Sflz[B<-out filename>] 12168054Sflz[B<-pass arg>] 13168064Sflz[B<-e>] 14168064Sflz[B<-d>] 15168064Sflz[B<-a>] 16168064Sflz[B<-A>] 17168064Sflz[B<-k password>] 18168064Sflz[B<-kfile filename>] 19168064Sflz[B<-K key>] 20168064Sflz[B<-iv IV>] 21168064Sflz[B<-p>] 22168064Sflz[B<-P>] 23168064Sflz[B<-bufsize number>] 24168064Sflz[B<-nopad>] 25168064Sflz[B<-debug>] 26168064Sflz 27168054Sflz=head1 DESCRIPTION 28168054Sflz 29168064SflzThe symmetric cipher commands allow data to be encrypted or decrypted 30168054Sflzusing various block and stream ciphers using keys based on passwords 31168188Sgaboror explicitly provided. Base64 encoding or decoding can also be performed 32168357Syareither by itself or in addition to the encryption or decryption. 33168673Sjulian 34168188Sgabor=head1 OPTIONS 35168263Sru 36168194Simp=over 4 37168357Syar 38168188Sgabor=item B<-in filename> 39168188Sgabor 40168188Sgaborthe input filename, standard input by default. 41168188Sgabor 42168188Sgabor=item B<-out filename> 43168188Sgabor 44168188Sgaborthe output filename, standard output by default. 45168202Sume 46168188Sgabor=item B<-pass arg> 47168188Sgabor 48168202Sumethe password source. For more information about the format of B<arg> 49168188Sgaborsee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 50168127Sdwmalone 51168054Sflz=item B<-salt> 52168054Sflz 53168054Sflzuse a salt in the key derivation routines. This option should B<ALWAYS> 54168054Sflzbe used unless compatibility with previous versions of OpenSSL or SSLeay 55168215Sacheis required. This option is only present on OpenSSL versions 0.9.5 or 56168149Simpabove. 57168149Simp 58168179Sgabor=item B<-nosalt> 59168083Sjkim 60168123Snetchilddon't use a salt in the key derivation routines. This is the default for 61168080Smlaiercompatibility with previous versions of OpenSSL and SSLeay. 62168195Sbenno 63168131Sbmah=item B<-e> 64168183Sgabor 65168080Smlaierencrypt the input data: this is the default. 66168309Sbrian 67168308Sbrian=item B<-d> 68168150Srwatson 69168149Simpdecrypt the input data. 70168150Srwatson 71168263Sru=item B<-a> 72168054Sflz 73168183Sgaborbase64 process the data. This means that if encryption is taking place 74168674Sjulianthe data is base64 encoded after encryption. If decryption is set then 75168060Sddsthe input data is base64 decoded before being decrypted. 76168108Srafan 77168083Sjkim=item B<-A> 78168153Simp 79168080Smlaierif the B<-a> option is set then base64 process the data on one line. 80168149Simp 81168127Sdwmalone=item B<-k password> 82168263Sru 83168180Srwatsonthe password to derive the key from. This is for compatibility with previous 84168149Simpversions of OpenSSL. Superseded by the B<-pass> argument. 85168127Sdwmalone 86168054Sflz=item B<-kfile filename> 87168370Sgad 88168631Sticsoread the password to derive the key from the first line of B<filename>. 89168183SgaborThis is for compatibility with previous versions of OpenSSL. Superseded by 90168672Smavthe B<-pass> argument. 91168150Srwatson 92168195Sbenno=item B<-S salt> 93168081Sle 94168154Sgshapirothe actual salt to use: this must be represented as a string comprised only 95168127Sdwmaloneof hex digits. 96168144Simp 97168308Sbrian=item B<-K key> 98168183Sgabor 99168150Srwatsonthe actual key to use: this must be represented as a string comprised only 100168153Simpof hex digits. If only the key is specified, the IV must additionally specified 101168083Sjkimusing the B<-iv> option. When both a key and a password are specified, the 102168111Smatteokey given with the B<-K> option will be used and the IV generated from the 103168149Simppassword will be taken. It probably does not make much sense to specify 104168151Sphkboth key and password. 105168149Simp 106168673Sjulian=item B<-iv IV> 107168180Srwatson 108168535Skevlothe actual IV to use: this must be represented as a string comprised only 109168150Srwatsonof hex digits. When only the key is specified using the B<-K> option, the 110168081SleIV must explicitly be defined. When a password is being specified using 111168180Srwatsonone of the other options, the IV is generated from this password. 112168167Sphilip 113168142Srwatson=item B<-p> 114168672Smav 115168263Sruprint out the key and IV used. 116168143Smjacob 117168080Smlaier=item B<-P> 118168149Simp 119168130Sdelphijprint out the key and IV used then immediately exit: don't do any encryption 120168123Snetchildor decryption. 121168171Sphilip 122168097Sle=item B<-bufsize number> 123168149Simp 124168127Sdwmaloneset the buffer size for I/O 125168183Sgabor 126168111Smatteo=item B<-nopad> 127168151Sphk 128168321Spjddisable standard block padding 129168183Sgabor 130168101Sandre=item B<-debug> 131168108Srafan 132168149Simpdebug the BIOs used for I/O. 133168149Simp 134168149Simp=back 135168140Srwatson 136168118Srse=head1 NOTES 137168263Sru 138168140SrwatsonThe program can be called either as B<openssl ciphername> or 139168080SmlaierB<openssl enc -ciphername>. 140168149Simp 141168081SleA password will be prompted for to derive the key and IV if necessary. 142168167Sphilip 143168149SimpThe B<-salt> option should B<ALWAYS> be used if the key is being derived 144168115Ssimonfrom a password unless you want compatibility with previous versions of 145168263SruOpenSSL and SSLeay. 146168198Sume 147168150SrwatsonWithout the B<-salt> option it is possible to perform efficient dictionary 148168149Simpattacks on the password and to attack stream cipher encrypted data. The reason 149168080Smlaierfor this is that without the salt the same password always generates the same 150168631Sticsoencryption key. When the salt is being used the first eight bytes of the 151168180Srwatsonencrypted data are reserved for the salt: it is generated at random when 152168198Sumeencrypting a file and read from the encrypted file when it is decrypted. 153168271Swes 154168141SwilkoSome of the ciphers do not have large keys and others have security 155168180Srwatsonimplications if not used correctly. A beginner is advised to just use 156168356Syara strong block cipher in CBC mode such as bf or des3. 157168238Syongari 158168054SflzAll the block ciphers normally use PKCS#5 padding also known as standard block 159168151Sphkpadding: this allows a rudimentary integrity or password check to be 160168151Sphkperformed. However since the chance of random data passing the test is 161168151Sphkbetter than 1 in 256 it isn't a very good test. 162168054Sflz 163168064SflzIf padding is disabled then the input data must be a multiple of the cipher 164168064Sflzblock length. 165168054Sflz 166168151SphkAll RC2 ciphers have the same key and effective key length. 167168151Sphk 168168151SphkBlowfish and RC5 algorithms use a 128 bit key. 169168151Sphk 170168151Sphk=head1 SUPPORTED CIPHERS 171168151Sphk 172168151Sphk base64 Base 64 173168101Sandre 174168101Sandre bf-cbc Blowfish in CBC mode 175168083Sjkim bf Alias for bf-cbc 176168083Sjkim bf-cfb Blowfish in CFB mode 177168195Sbenno bf-ecb Blowfish in ECB mode 178168195Sbenno bf-ofb Blowfish in OFB mode 179168152Srwatson 180168152Srwatson cast-cbc CAST in CBC mode 181168152Srwatson cast Alias for cast-cbc 182168152Srwatson cast5-cbc CAST5 in CBC mode 183168152Srwatson cast5-cfb CAST5 in CFB mode 184168152Srwatson cast5-ecb CAST5 in ECB mode 185168152Srwatson cast5-ofb CAST5 in OFB mode 186168152Srwatson 187168352Sru des-cbc DES in CBC mode 188168080Smlaier des Alias for des-cbc 189168080Smlaier des-cfb DES in CBC mode 190168080Smlaier des-ofb DES in OFB mode 191168309Sbrian des-ecb DES in ECB mode 192168309Sbrian 193168152Srwatson des-ede-cbc Two key triple DES EDE in CBC mode 194168152Srwatson des-ede Alias for des-ede 195168140Srwatson des-ede-cfb Two key triple DES EDE in CFB mode 196168140Srwatson des-ede-ofb Two key triple DES EDE in OFB mode 197168101Sandre 198168115Ssimon des-ede3-cbc Three key triple DES EDE in CBC mode 199168101Sandre des-ede3 Alias for des-ede3-cbc 200168152Srwatson des3 Alias for des-ede3-cbc 201168152Srwatson des-ede3-cfb Three key triple DES EDE CFB mode 202168108Srafan des-ede3-ofb Three key triple DES EDE in OFB mode 203168108Srafan 204168083Sjkim desx DESX algorithm. 205168147Sdes 206168147Sdes idea-cbc IDEA algorithm in CBC mode 207168263Sru idea same as idea-cbc 208168083Sjkim idea-cfb IDEA in CFB mode 209168352Sru idea-ecb IDEA in ECB mode 210168352Sru idea-ofb IDEA in OFB mode 211168352Sru 212168147Sdes rc2-cbc 128 bit RC2 in CBC mode 213168140Srwatson rc2 Alias for rc2-cbc 214168140Srwatson rc2-cfb 128 bit RC2 in CBC mode 215168631Sticso rc2-ecb 128 bit RC2 in CBC mode 216168631Sticso rc2-ofb 128 bit RC2 in CBC mode 217168352Sru rc2-64-cbc 64 bit RC2 in CBC mode 218168352Sru rc2-40-cbc 40 bit RC2 in CBC mode 219168127Sdwmalone 220168672Smav rc4 128 bit RC4 221168672Smav rc4-64 64 bit RC4 222168140Srwatson rc4-40 40 bit RC4 223168140Srwatson 224168140Srwatson rc5-cbc RC5 cipher in CBC mode 225168352Sru rc5 Alias for rc5-cbc 226168352Sru rc5-cfb RC5 cipher in CBC mode 227168149Simp rc5-ecb RC5 cipher in CBC mode 228168149Simp rc5-ofb RC5 cipher in CBC mode 229168156Sbmah 230168149Simp=head1 EXAMPLES 231168149Simp 232168149SimpJust base64 encode a binary file: 233168149Simp 234168149Simp openssl base64 -in file.bin -out file.b64 235168149Simp 236168149SimpDecode the same file 237168149Simp 238168149Simp openssl base64 -d -in file.b64 -out file.bin 239168149Simp 240168149SimpEncrypt a file using triple DES in CBC mode using a prompted password: 241168149Simp 242168352Sru openssl des3 -salt -in file.txt -out file.des3 243168149Simp 244168149SimpDecrypt a file using a supplied password: 245168149Simp 246168149Simp openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword 247168149Simp 248168149SimpEncrypt a file then base64 encode it (so it can be sent via mail for example) 249168149Simpusing Blowfish in CBC mode: 250168080Smlaier 251168150Srwatson openssl bf -a -salt -in file.txt -out file.bf 252168150Srwatson 253168150SrwatsonBase64 decode a file then decrypt it: 254168150Srwatson 255168150Srwatson openssl bf -d -salt -a -in file.bf -out file.txt 256168180Srwatson 257168080SmlaierDecrypt some data using a supplied 40 bit RC4 key: 258168152Srwatson 259168150Srwatson openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 260168152Srwatson 261168150Srwatson=head1 BUGS 262168144Simp 263168152SrwatsonThe B<-A> option when used with large files doesn't work properly. 264168151Sphk 265168151SphkThere should be an option to allow an iteration count to be included. 266168271Swes 267168356SyarThe B<enc> program only supports a fixed number of algorithms with 268168144Simpcertain parameters. So if, for example, you want to use RC2 with a 269168180Srwatson76 bit key or RC4 with an 84 bit key you can't use this program. 270168270Sbrooks 271168180Srwatson=cut 272168309Sbrian