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 eadfe31fbb3cf9e8131e7845d32d2e5cee90bdd1..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<-inform PEM|DER>]
 [B<-outform PEM|DER>]
 [B<-in filename>]

+[B<-passin password>]
+[B<-envpassin var>]

 [B<-out filename>]
 [B<-out filename>]

+[B<-passout password>]
+[B<-envpassout var>]

 [B<-noiter>]
 [B<-nocrypt>]
 [B<-nooct>]
 [B<-v2 alg>]
 [B<-noiter>]
 [B<-nocrypt>]
 [B<-nooct>]
 [B<-v2 alg>]

+[B<-v1 alg>]

 
 =head1 DESCRIPTION
 
 
 =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.
 
 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
 =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.
 
 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
 =item B<-nocrypt>
 
 PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo


@@ -89,6 +112,11 @@ 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.
 
 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
 =back
 
 =head1 NOTES


@@ -120,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.
 
 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
 =head1 EXAMPLES
 
 Convert a private from traditional to PKCS#5 v2.0 format using triple


@@ -132,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
 
 
  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
 Read a DER unencrypted PKCS#8 format private key:
 
  openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem


@@ -150,9 +210,6 @@ reasonably accurate at least as far as these algorithms are concerned.
 
 =head1 BUGS
 
 
 =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.
 
 There should be an option that prints out the encryption algorithm
 in use and other details such as the iteration count.