Fix some of the command line password stuff. New function

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

diff --git a/doc/man/pkcs8.pod b/doc/man/pkcs8.pod
index 64cf65a78c7d2660dfd9959881d2d33669a45852..3d5885638804063232e5003c0b074be696a39054 100644 (file)
--- a/doc/man/pkcs8.pod
+++ b/doc/man/pkcs8.pod
@@ -11,11 +11,16 @@ B<openssl> B<pkcs8>
 [B<-inform PEM|DER>]
 [B<-outform PEM|DER>]
 [B<-in filename>]
+[B<-passin password>]
+[B<-envpassin var>]
 [B<-out filename>]
+[B<-passout password>]
+[B<-envpassout var>]
 [B<-noiter>]
 [B<-nocrypt>]
 [B<-nooct>]
 [B<-v2 alg>]
+[B<-v1 alg>]
 
 =head1 DESCRIPTION
 
@@ -52,6 +57,15 @@ This specifies the input filename to read a key from or standard input if this
 option is not specified. If the key is encrypted a pass phrase will be
 prompted for.
 
+=item B<-passin password>
+
+the input file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassin var>
+
+read the input file password from the environment variable B<var>.
+
 =item B<-out filename>
 
 This specifies the output filename to write a key to or standard output by
@@ -59,6 +73,15 @@ default. If any encryption options are set then a pass phrase will be
 prompted for. The output filename should B<not> be the same as the input
 filename.
 
+=item B<-passout password>
+
+the output file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassout var>
+
+read the output file password from the environment variable B<var>.
+
 =item B<-nocrypt>
 
 PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
@@ -89,10 +112,26 @@ private keys with OpenSSL then this doesn't matter.
 The B<alg> argument is the encryption algorithm to use, valid values include
 B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
 
+=item B<-v1 alg>
+
+This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
+list of possible algorithms is included below.
+
 =back
 
 =head1 NOTES
 
+The encrypted form of a PEM encode PKCS#8 files uses the following
+headers and footers:
+
+ -----BEGIN ENCRYPTED PRIVATE KEY-----
+ -----END ENCRYPTED PRIVATE KEY-----
+
+The unencrypted form uses:
+
+ -----BEGIN PRIVATE KEY-----
+ -----END PRIVATE KEY-----
+
 Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
 counts are more secure that those encrypted using the traditional
 SSLeay compatible formats. So if additional security is considered
@@ -109,6 +148,33 @@ It is possible to write out DER encoded encrypted private keys in
 PKCS#8 format because the encryption details are included at an ASN1
 level whereas the traditional format includes them at a PEM level.
 
+=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
+
+Various algorithms can be used with the B<-v1> command line option,
+including PKCS#5 v1.5 and PKCS#12. These are described in more detail
+below.
+
+=over 4
+
+=item B<PBE-MD2-DES PBE-MD5-DES>
+
+These algorithms were included in the original PKCS#5 v1.5 specification.
+They only offer 56 bits of protection since they both use DES.
+
+=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES>
+
+These algorithms are not mentioned in the original PKCS#5 v1.5 specification
+but they use the same key derivation algorithm and are supported by some
+software. They are mentioned in PKCS#5 v1.5. They use either 64 bit RC2 or
+56 bit DES.
+
+=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40>
+
+These algorithms use the PKCS#12 password based encryption algorithm and
+allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
+
+=back
+
 =head1 EXAMPLES
 
 Convert a private from traditional to PKCS#5 v2.0 format using triple
@@ -121,6 +187,11 @@ Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
 
  openssl pkcs8 -in key.pem -topk8 -out enckey.pem
 
+Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
+(3DES):
+
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
+
 Read a DER unencrypted PKCS#8 format private key:
 
  openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
@@ -139,9 +210,6 @@ reasonably accurate at least as far as these algorithms are concerned.
 
 =head1 BUGS
 
-It isn't possible to produce keys encrypted using PKCS#5 v1.5 algorithms
-other than B<pbeWithMD5AndDES-CBC> using this utility.
-
 There should be an option that prints out the encryption algorithm
 in use and other details such as the iteration count.