Fix some of the command line password stuff. New function
[openssl.git] / doc / man / pkcs8.pod
index 3ec4235..3d58856 100644 (file)
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-pkcs8 - PKCS#8 format private key processing tool
+pkcs8 - PKCS#8 format private key conversion tool
 
 =head1 SYNOPSIS
 
@@ -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
 
@@ -29,7 +34,7 @@ format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
 
 =item B<-topk8>
 
-Normally a PKCS#8 private key is expected on input and a "traditional" format
+Normally a PKCS#8 private key is expected on input and a traditional format
 private key will be written. With the B<-topk8> option the situation is
 reversed: it reads a traditional format private key and writes a PKCS#8
 format key.
@@ -38,10 +43,10 @@ format key.
 
 This specifies the input format. If a PKCS#8 format key is expected on input
 then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
-expected. Otherwise the B<DER> or B<PEM> format of the "traditional" format
+expected. Otherwise the B<DER> or B<PEM> format of the traditional format
 private key is used.
 
-=item B<-outform DER|NET|PEM>
+=item B<-outform DER|PEM>
 
 This specifies the output format, the options have the same meaning as the 
 B<-inform> option.
@@ -52,82 +57,168 @@ 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
-is not specified. If any encryption options are set then a pass phrase will be
+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<-des|-des3|-idea>
+=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>.
 
-These options encrypt the private key with the DES, triple DES, or the 
-IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
-If none of these options is specified the key is written in plain text. This
-means that using the B<rsa> utility to read in an encrypted key with no
-encryption option can be used to remove the pass phrase from a key, or by
-setting the encryption options it can be use to add or change the pass phrase.
-These options can only be used with PEM format output files.
+=item B<-nocrypt>
 
-=item B<-text>
+PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
+structures using an appropriate password based encryption algorithm. With
+this option an unencrypted PrivateKeyInfo structure is expected or output.
+This option does not encrypt private keys at all and should only be used
+when absolutely necessary. Certain software such as some versions of Java
+code signing software used unencrypted private keys.
 
-prints out the various public or private key components in
-plain text in addition to the encoded version. 
+=item B<-nooct>
 
-=item B<-noout>
+This option generates private keys in a broken format that some software
+uses. Specifically the private key should be enclosed in a OCTET STRING
+but some software just includes the structure itself without the
+surrounding OCTET STRING.
+
+=item B<-v2 alg>
+
+This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
+private keys are encrypted with the password based encryption algorithm
+called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
+was the strongest encryption algorithm supported in PKCS#5 v1.5. Using 
+the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
+encryption algorithm such as 168 bit triple DES or 128 bit RC2 however
+not many implementations support PKCS#5 v2.0 yet. If you are just using
+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
 
-this option prevents output of the encoded version of the key.
+=head1 NOTES
 
-=item B<-modulus>
+The encrypted form of a PEM encode PKCS#8 files uses the following
+headers and footers:
 
-this option prints out the value of the modulus of the key.
+ -----BEGIN ENCRYPTED PRIVATE KEY-----
+ -----END ENCRYPTED PRIVATE KEY-----
 
-=item B<-check>
+The unencrypted form uses:
 
-this option checks the consistency of an RSA private key.
+ -----BEGIN PRIVATE KEY-----
+ -----END PRIVATE KEY-----
 
-=item B<-pubin>
+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
+important the keys should be converted.
 
-by default a private key is input file with this option a public key is input
-instead.
+The default encryption is only 56 bits because this is the encryption
+that most current implementations of PKCS#8 will support.
 
-=item B<-pubout>
+Some software may use PKCS#12 password based encryption algorithms
+with PKCS#8 format private keys: these are handled automatically
+but there is no option to produce them.
 
-by default a private key is output with this option a public
-key will be output instead. This option is automatically set if the input is
-a public key.
+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
 
-To remove the pass phrase on an RSA private key:
+Convert a private from traditional to PKCS#5 v2.0 format using triple
+DES:
 
-C<openssl rsa -in key.pem -out keyout.pem>
+ openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
 
-To encrypt a private key using triple DES:
+Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
+(DES):
 
-C<openssl rsa -in key.pem -des3 -out keyout.pem>
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem
 
-To convert a private key from PEM to DER format: 
+Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
+(3DES):
 
-C<openssl rsa -in key.pem -outform DER -out keyout.der>
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
 
-To print out the components of a private key to standard output:
+Read a DER unencrypted PKCS#8 format private key:
 
-C<openssl rsa -in key.pem -text -noout>
+ openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
 
-To just output the public part of a private key:
+Convert a private key from any PKCS#8 format to traditional format:
 
-C<openssl rsa -in key.pem -pubout -out pubkey.pem>
+ openssl pkcs8 -in pk8.pem -out key.pem
+
+=head1 STANDARDS
+
+Test vectors from this implementation were posted to the pkcs-tng mailing
+list using triple DES, DES and RC2 with high iteration counts, several
+people confirmed that they could decrypt the private keys produced and
+Therefore it can be assumed that the PKCS#5 v2.0 implementation is
+reasonably accurate at least as far as these algorithms are concerned.
 
 =head1 BUGS
 
-It should be possible to read or produce PKCS#8 format encrypted RSA keys:
-at present it isn't.
+There should be an option that prints out the encryption algorithm
+in use and other details such as the iteration count.
+
+PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
+key format for OpenSSL: for compatability several of the utilities use
+the old format at present.
 
 =head1 SEE ALSO
 
-L<pkcs8>, dsa(1), genrsa(1), gendsa(1)
+dsa(1), rsa(1), genrsa(1), gendsa(1)
 
 =cut