Clarify docs.

[openssl.git] / doc / man / enc.pod

diff --git a/doc/man/enc.pod b/doc/man/enc.pod
index 53884ed3eddd9ef2e8889732ff7c8f84cfa5b3a8..eceee9fee88b667d58c372f96ce20000e0230c2c 100644 (file)
--- a/doc/man/enc.pod
+++ b/doc/man/enc.pod
@@ -40,6 +40,18 @@ the input filename, standard input by default.
 
 the output filename, standard output by default.
 
+=item B<-salt>
+
+use a salt in the key derivation routines. This option should B<ALWAYS>
+be used unless compatability with previous versions of OpenSSL or SSLeay
+is required. This option is only present on OpenSSL versions 0.9.5 or
+above.
+
+=item B<-nosalt>
+
+don't use a salt in the key derivation routines. This is the default for
+compatability with previous versions of OpenSSL and SSLeay.
+
 =item B<-e>
 
 encrypt the input data: this is the default.
@@ -66,6 +78,11 @@ the password to derive the key from.
 
 read the password to derive the key from the first line of B<filename>
 
+=item B<-S salt>
+
+the actual salt to use: this must be represented as a string comprised only
+of hex digits.
+
 =item B<-K key>
 
 the actual key to use: this must be represented as a string comprised only
@@ -102,6 +119,21 @@ B<openssl enc -ciphername>.
 
 A password will be prompted for to derive the key and IV if necessary.
 
+The B<-salt> option should B<ALWAYS> be used if the key is being derived
+from a password unless you want compatability with previous versions of
+OpenSSL and SSLeay.
+
+Without the B<-salt> option it is possible to perform efficient dictionary
+attacks on the password and to attack stream cipher encrypted data. The reason
+for this is that without the salt the same password always generates the same
+encryption key. When the salt is being used the first eight bytes of the
+encrypted data are reserved for the salt: it is generated at random when
+encrypting a file and read from the encrypted file when it is decrypted.
+
+Some of the ciphers do not have large keys and others have security
+implications if not used correctly. A beginner is advised to just use
+a strong block cipher in CBC mode such as bf or des3.
+
 All the block ciphers use PKCS#5 padding also known as standard block
 padding: this allows a rudimentary integrity or password check to be
 performed. However since the chance of random data passing the test is
@@ -173,15 +205,40 @@ Blowfish and RC5 algorithms use a 128 bit key.
 
 =head1 EXAMPLES
 
-To be added....
+Just base64 encode a binary file:
+
+ openssl base64 -in file.bin -out file.b64
+
+Decode the same file
+
+ openssl base64 -d -in file.b64 -out file.bin 
+
+Encrypt a file using triple DES in CBC mode using a prompted password:
+
+ openssl des3 -salt -in file.txt -out file.des3 
+
+Decrypt a file using a supplied password:
+
+ openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
+
+Encrypt a file then base64 encode it (so it can be sent via mail for example)
+using Blowfish in CBC mode:
+
+ openssl bf -a -salt -in file.txt -out file.bf
+
+Base64 decode a file then decrypt it:
+
+ openssl bf -d -salt -a -in file.bf -out file.txt
+
+Decrypt some data using a supplied 40 bit RC4 key:
+
+ openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
 
 =head1 BUGS
 
 The B<-A> option when used with large files doesn't work properly.
 
-The key derivation algorithm used is compatible with the SSLeay algorithm. It
-is not very good: it uses unsalted MD5. There should be an option to allow a
-salt or iteration count to be included.
+There should be an option to allow an iteration count to be included.
 
 Like the EVP library the B<enc> program only supports a fixed number of
 algorithms with certain parameters. So if, for example, you want to use RC2