When only the key is given to "enc", the IV is undefined
[openssl.git] / doc / apps / enc.pod
index 349fca0..99b9147 100644 (file)
@@ -9,6 +9,7 @@ enc - symmetric cipher routines
 B<openssl enc -ciphername>
 [B<-in filename>]
 [B<-out filename>]
+[B<-pass arg>]
 [B<-e>]
 [B<-d>]
 [B<-a>]
@@ -20,6 +21,7 @@ B<openssl enc -ciphername>
 [B<-p>]
 [B<-P>]
 [B<-bufsize number>]
+[B<-nopad>]
 [B<-debug>]
 
 =head1 DESCRIPTION
@@ -41,6 +43,11 @@ the input filename, standard input by default.
 
 the output filename, standard output by default.
 
+=item B<-pass arg>
+
+the password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
 =item B<-salt>
 
 use a salt in the key derivation routines. This option should B<ALWAYS>
@@ -73,11 +80,14 @@ if the B<-a> option is set then base64 process the data on one line.
 
 =item B<-k password>
 
-the password to derive the key from.
+the password to derive the key from. This is for compatibility with previous
+versions of OpenSSL. Superseded by the B<-pass> argument.
 
 =item B<-kfile filename>
 
-read the password to derive the key from the first line of B<filename>
+read the password to derive the key from the first line of B<filename>.
+This is for computability with previous versions of OpenSSL. Superseded by
+the B<-pass> argument.
 
 =item B<-S salt>
 
@@ -87,12 +97,18 @@ of hex digits.
 =item B<-K key>
 
 the actual key to use: this must be represented as a string comprised only
-of hex digits.
+of hex digits. If only the key is specified, the IV must additionally specified
+using the B<-iv> option. When both a key and a password are specified, the
+key given with the B<-K> option will be used and the IV generated from the
+password will be taken. It probably does not make much sense to specify
+both key and password.
 
 =item B<-iv IV>
 
 the actual IV to use: this must be represented as a string comprised only
-of hex digits.
+of hex digits. When only the key is specified using the B<-K> option, the
+IV must explicitly be defined. When a password is being specified using
+one of the other options, the IV is generated from this password.
 
 =item B<-p>
 
@@ -107,6 +123,10 @@ or decryption.
 
 set the buffer size for I/O
 
+=item B<-nopad>
+
+disable standard block padding
+
 =item B<-debug>
 
 debug the BIOs used for I/O.
@@ -135,11 +155,14 @@ 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
+All the block ciphers normally 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
 better than 1 in 256 it isn't a very good test.
 
+If padding is disabled then the input data must be a muliple of the cipher
+block length.
+
 All RC2 ciphers have the same key and effective key length.
 
 Blowfish and RC5 algorithms use a 128 bit key.
@@ -241,8 +264,8 @@ The B<-A> option when used with large files doesn't work properly.
 
 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
-with a 76 bit key or RC4 with an 84 bit key you can't use this program.
+The B<enc> program only supports a fixed number of algorithms with
+certain parameters. So if, for example, you want to use RC2 with a
+76 bit key or RC4 with an 84 bit key you can't use this program.
 
 =cut