When only the key is given to "enc", the IV is undefined

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

diff --git a/doc/apps/enc.pod b/doc/apps/enc.pod
index 349fca00f8bc4f524afc3cf0156b467296f164de..99b914789d63b2181131bdbd8d36a24340fecb42 100644 (file)
--- a/doc/apps/enc.pod
+++ b/doc/apps/enc.pod
@@ -9,6 +9,7 @@ enc - symmetric cipher routines
 B<openssl enc -ciphername>
 [B<-in filename>]
 [B<-out filename>]
 B<openssl enc -ciphername>
 [B<-in filename>]
 [B<-out filename>]

+[B<-pass arg>]

 [B<-e>]
 [B<-d>]
 [B<-a>]
 [B<-e>]
 [B<-d>]
 [B<-a>]


@@ -20,6 +21,7 @@ B<openssl enc -ciphername>
 [B<-p>]
 [B<-P>]
 [B<-bufsize number>]
 [B<-p>]
 [B<-P>]
 [B<-bufsize number>]

+[B<-nopad>]

 [B<-debug>]
 
 =head1 DESCRIPTION
 [B<-debug>]
 
 =head1 DESCRIPTION


@@ -41,6 +43,11 @@ the input filename, standard input by default.
 
 the output filename, standard output 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>
 =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>
 
 
 =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>
 
 
 =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>
 
 
 =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
 =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
 
 =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>
 
 
 =item B<-p>
 


@@ -107,6 +123,10 @@ or decryption.
 
 set the buffer size for I/O
 
 
 set the buffer size for I/O
 

+=item B<-nopad>
+
+disable standard block padding
+

 =item B<-debug>
 
 debug the BIOs used for I/O.
 =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.
 
 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.
 
 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.
 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.
 
 
 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
 
 =cut