159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 559191Skrispkcs8 - PKCS#8 format private key conversion tool 659191Skris 759191Skris=head1 SYNOPSIS 859191Skris 959191SkrisB<openssl> B<pkcs8> 1059191Skris[B<-topk8>] 1159191Skris[B<-inform PEM|DER>] 1259191Skris[B<-outform PEM|DER>] 1359191Skris[B<-in filename>] 1459191Skris[B<-passin arg>] 1559191Skris[B<-out filename>] 1659191Skris[B<-passout arg>] 1759191Skris[B<-noiter>] 1859191Skris[B<-nocrypt>] 1959191Skris[B<-nooct>] 2059191Skris[B<-embed>] 2159191Skris[B<-nsdb>] 2259191Skris[B<-v2 alg>] 23290207Sjkim[B<-v2prf alg>] 2459191Skris[B<-v1 alg>] 25111147Snectar[B<-engine id>] 2659191Skris 2759191Skris=head1 DESCRIPTION 2859191Skris 2959191SkrisThe B<pkcs8> command processes private keys in PKCS#8 format. It can handle 3059191Skrisboth unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo 3159191Skrisformat with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. 3259191Skris 3359191Skris=head1 COMMAND OPTIONS 3459191Skris 3559191Skris=over 4 3659191Skris 3759191Skris=item B<-topk8> 3859191Skris 3959191SkrisNormally a PKCS#8 private key is expected on input and a traditional format 4059191Skrisprivate key will be written. With the B<-topk8> option the situation is 4159191Skrisreversed: it reads a traditional format private key and writes a PKCS#8 4259191Skrisformat key. 4359191Skris 4459191Skris=item B<-inform DER|PEM> 4559191Skris 4659191SkrisThis specifies the input format. If a PKCS#8 format key is expected on input 4759191Skristhen either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be 4859191Skrisexpected. Otherwise the B<DER> or B<PEM> format of the traditional format 4959191Skrisprivate key is used. 5059191Skris 5159191Skris=item B<-outform DER|PEM> 5259191Skris 5359191SkrisThis specifies the output format, the options have the same meaning as the 5459191SkrisB<-inform> option. 5559191Skris 5659191Skris=item B<-in filename> 5759191Skris 5859191SkrisThis specifies the input filename to read a key from or standard input if this 5959191Skrisoption is not specified. If the key is encrypted a pass phrase will be 6059191Skrisprompted for. 6159191Skris 6259191Skris=item B<-passin arg> 6359191Skris 6459191Skristhe input file password source. For more information about the format of B<arg> 6559191Skrissee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 6659191Skris 6759191Skris=item B<-out filename> 6859191Skris 6959191SkrisThis specifies the output filename to write a key to or standard output by 7059191Skrisdefault. If any encryption options are set then a pass phrase will be 7159191Skrisprompted for. The output filename should B<not> be the same as the input 7259191Skrisfilename. 7359191Skris 7459191Skris=item B<-passout arg> 7559191Skris 7659191Skristhe output file password source. For more information about the format of B<arg> 7759191Skrissee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 7859191Skris 7959191Skris=item B<-nocrypt> 8059191Skris 8159191SkrisPKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo 8259191Skrisstructures using an appropriate password based encryption algorithm. With 8359191Skristhis option an unencrypted PrivateKeyInfo structure is expected or output. 8459191SkrisThis option does not encrypt private keys at all and should only be used 8559191Skriswhen absolutely necessary. Certain software such as some versions of Java 8659191Skriscode signing software used unencrypted private keys. 8759191Skris 8859191Skris=item B<-nooct> 8959191Skris 9059191SkrisThis option generates RSA private keys in a broken format that some software 9159191Skrisuses. Specifically the private key should be enclosed in a OCTET STRING 9259191Skrisbut some software just includes the structure itself without the 9359191Skrissurrounding OCTET STRING. 9459191Skris 9559191Skris=item B<-embed> 9659191Skris 9759191SkrisThis option generates DSA keys in a broken format. The DSA parameters are 9859191Skrisembedded inside the PrivateKey structure. In this form the OCTET STRING 9959191Skriscontains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing 10059191Skristhe parameters and an ASN1 INTEGER containing the private key. 10159191Skris 10259191Skris=item B<-nsdb> 10359191Skris 10459191SkrisThis option generates DSA keys in a broken format compatible with Netscape 10559191Skrisprivate key databases. The PrivateKey contains a SEQUENCE consisting of 10659191Skristhe public and private keys respectively. 10759191Skris 10859191Skris=item B<-v2 alg> 10959191Skris 11059191SkrisThis option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8 11159191Skrisprivate keys are encrypted with the password based encryption algorithm 11259191Skriscalled B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it 11359191Skriswas the strongest encryption algorithm supported in PKCS#5 v1.5. Using 11459191Skristhe B<-v2> option PKCS#5 v2.0 algorithms are used which can use any 11559191Skrisencryption algorithm such as 168 bit triple DES or 128 bit RC2 however 11659191Skrisnot many implementations support PKCS#5 v2.0 yet. If you are just using 11759191Skrisprivate keys with OpenSSL then this doesn't matter. 11859191Skris 11959191SkrisThe B<alg> argument is the encryption algorithm to use, valid values include 12059191SkrisB<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used. 12159191Skris 122290207Sjkim=item B<-v2prf alg> 123290207Sjkim 124290207SjkimThis option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value 125290207Sjkimvalues would be B<hmacWithSHA256>. If this option isn't set then the default 126290207Sjkimfor the cipher is used or B<hmacWithSHA1> if there is no default. 127290207Sjkim 12859191Skris=item B<-v1 alg> 12959191Skris 13059191SkrisThis option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete 13159191Skrislist of possible algorithms is included below. 13259191Skris 133111147Snectar=item B<-engine id> 134111147Snectar 135238405Sjkimspecifying an engine (by its unique B<id> string) will cause B<pkcs8> 136111147Snectarto attempt to obtain a functional reference to the specified engine, 137111147Snectarthus initialising it if needed. The engine will then be set as the default 138111147Snectarfor all available algorithms. 139111147Snectar 14059191Skris=back 14159191Skris 14259191Skris=head1 NOTES 14359191Skris 14459191SkrisThe encrypted form of a PEM encode PKCS#8 files uses the following 14559191Skrisheaders and footers: 14659191Skris 14759191Skris -----BEGIN ENCRYPTED PRIVATE KEY----- 14859191Skris -----END ENCRYPTED PRIVATE KEY----- 14959191Skris 15059191SkrisThe unencrypted form uses: 15159191Skris 15259191Skris -----BEGIN PRIVATE KEY----- 15359191Skris -----END PRIVATE KEY----- 15459191Skris 15559191SkrisPrivate keys encrypted using PKCS#5 v2.0 algorithms and high iteration 15659191Skriscounts are more secure that those encrypted using the traditional 15759191SkrisSSLeay compatible formats. So if additional security is considered 15859191Skrisimportant the keys should be converted. 15959191Skris 16059191SkrisThe default encryption is only 56 bits because this is the encryption 16159191Skristhat most current implementations of PKCS#8 will support. 16259191Skris 16359191SkrisSome software may use PKCS#12 password based encryption algorithms 16459191Skriswith PKCS#8 format private keys: these are handled automatically 16559191Skrisbut there is no option to produce them. 16659191Skris 16759191SkrisIt is possible to write out DER encoded encrypted private keys in 16859191SkrisPKCS#8 format because the encryption details are included at an ASN1 16959191Skrislevel whereas the traditional format includes them at a PEM level. 17059191Skris 17159191Skris=head1 PKCS#5 v1.5 and PKCS#12 algorithms. 17259191Skris 17359191SkrisVarious algorithms can be used with the B<-v1> command line option, 17459191Skrisincluding PKCS#5 v1.5 and PKCS#12. These are described in more detail 17559191Skrisbelow. 17659191Skris 17759191Skris=over 4 17859191Skris 17959191Skris=item B<PBE-MD2-DES PBE-MD5-DES> 18059191Skris 18159191SkrisThese algorithms were included in the original PKCS#5 v1.5 specification. 18259191SkrisThey only offer 56 bits of protection since they both use DES. 18359191Skris 18459191Skris=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES> 18559191Skris 18659191SkrisThese algorithms are not mentioned in the original PKCS#5 v1.5 specification 18759191Skrisbut they use the same key derivation algorithm and are supported by some 18859191Skrissoftware. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or 18959191Skris56 bit DES. 19059191Skris 19159191Skris=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40> 19259191Skris 19359191SkrisThese algorithms use the PKCS#12 password based encryption algorithm and 19459191Skrisallow strong encryption algorithms like triple DES or 128 bit RC2 to be used. 19559191Skris 19659191Skris=back 19759191Skris 19859191Skris=head1 EXAMPLES 19959191Skris 20059191SkrisConvert a private from traditional to PKCS#5 v2.0 format using triple 20159191SkrisDES: 20259191Skris 20359191Skris openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem 20459191Skris 205290207SjkimConvert a private from traditional to PKCS#5 v2.0 format using AES with 206290207Sjkim256 bits in CBC mode and B<hmacWithSHA256> PRF: 207290207Sjkim 208290207Sjkim openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem 209290207Sjkim 21059191SkrisConvert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm 21159191Skris(DES): 21259191Skris 21359191Skris openssl pkcs8 -in key.pem -topk8 -out enckey.pem 21459191Skris 21559191SkrisConvert a private key to PKCS#8 using a PKCS#12 compatible algorithm 21659191Skris(3DES): 21759191Skris 21859191Skris openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES 21959191Skris 22059191SkrisRead a DER unencrypted PKCS#8 format private key: 22159191Skris 22259191Skris openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem 22359191Skris 22459191SkrisConvert a private key from any PKCS#8 format to traditional format: 22559191Skris 22659191Skris openssl pkcs8 -in pk8.pem -out key.pem 22759191Skris 22859191Skris=head1 STANDARDS 22959191Skris 23059191SkrisTest vectors from this PKCS#5 v2.0 implementation were posted to the 23159191Skrispkcs-tng mailing list using triple DES, DES and RC2 with high iteration 23259191Skriscounts, several people confirmed that they could decrypt the private 23359191Skriskeys produced and Therefore it can be assumed that the PKCS#5 v2.0 23459191Skrisimplementation is reasonably accurate at least as far as these 23559191Skrisalgorithms are concerned. 23659191Skris 23759191SkrisThe format of PKCS#8 DSA (and other) private keys is not well documented: 23859191Skrisit is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA 23959191SkrisPKCS#8 private key format complies with this standard. 24059191Skris 24159191Skris=head1 BUGS 24259191Skris 24359191SkrisThere should be an option that prints out the encryption algorithm 24459191Skrisin use and other details such as the iteration count. 24559191Skris 24659191SkrisPKCS#8 using triple DES and PKCS#5 v2.0 should be the default private 24759191Skriskey format for OpenSSL: for compatibility several of the utilities use 24859191Skristhe old format at present. 24959191Skris 25059191Skris=head1 SEE ALSO 25159191Skris 25259191SkrisL<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>, 25359191SkrisL<gendsa(1)|gendsa(1)> 25459191Skris 25559191Skris=cut 256