1=pod 2 3=head1 NAME 4 5pkcs8 - PKCS#8 format private key conversion tool 6 7=head1 SYNOPSIS 8 9B<openssl> B<pkcs8> 10[B<-topk8>] 11[B<-inform PEM|DER>] 12[B<-outform PEM|DER>] 13[B<-in filename>] 14[B<-passin arg>] 15[B<-out filename>] 16[B<-passout arg>] 17[B<-noiter>] 18[B<-nocrypt>] 19[B<-nooct>] 20[B<-embed>] 21[B<-nsdb>] 22[B<-v2 alg>] 23[B<-v2prf alg>] 24[B<-v1 alg>] 25[B<-engine id>] 26 27=head1 DESCRIPTION 28 29The B<pkcs8> command processes private keys in PKCS#8 format. It can handle 30both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo 31format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. 32 33=head1 COMMAND OPTIONS 34 35=over 4 36 37=item B<-topk8> 38 39Normally a PKCS#8 private key is expected on input and a traditional format 40private key will be written. With the B<-topk8> option the situation is 41reversed: it reads a traditional format private key and writes a PKCS#8 42format key. 43 44=item B<-inform DER|PEM> 45 46This specifies the input format. If a PKCS#8 format key is expected on input 47then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be 48expected. Otherwise the B<DER> or B<PEM> format of the traditional format 49private key is used. 50 51=item B<-outform DER|PEM> 52 53This specifies the output format, the options have the same meaning as the 54B<-inform> option. 55 56=item B<-in filename> 57 58This specifies the input filename to read a key from or standard input if this 59option is not specified. If the key is encrypted a pass phrase will be 60prompted for. 61 62=item B<-passin arg> 63 64the input file password source. For more information about the format of B<arg> 65see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 66 67=item B<-out filename> 68 69This specifies the output filename to write a key to or standard output by 70default. If any encryption options are set then a pass phrase will be 71prompted for. The output filename should B<not> be the same as the input 72filename. 73 74=item B<-passout arg> 75 76the output file password source. For more information about the format of B<arg> 77see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 78 79=item B<-nocrypt> 80 81PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo 82structures using an appropriate password based encryption algorithm. With 83this option an unencrypted PrivateKeyInfo structure is expected or output. 84This option does not encrypt private keys at all and should only be used 85when absolutely necessary. Certain software such as some versions of Java 86code signing software used unencrypted private keys. 87 88=item B<-nooct> 89 90This option generates RSA private keys in a broken format that some software 91uses. Specifically the private key should be enclosed in a OCTET STRING 92but some software just includes the structure itself without the 93surrounding OCTET STRING. 94 95=item B<-embed> 96 97This option generates DSA keys in a broken format. The DSA parameters are 98embedded inside the PrivateKey structure. In this form the OCTET STRING 99contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing 100the parameters and an ASN1 INTEGER containing the private key. 101 102=item B<-nsdb> 103 104This option generates DSA keys in a broken format compatible with Netscape 105private key databases. The PrivateKey contains a SEQUENCE consisting of 106the public and private keys respectively. 107 108=item B<-v2 alg> 109 110This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8 111private keys are encrypted with the password based encryption algorithm 112called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it 113was the strongest encryption algorithm supported in PKCS#5 v1.5. Using 114the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any 115encryption algorithm such as 168 bit triple DES or 128 bit RC2 however 116not many implementations support PKCS#5 v2.0 yet. If you are just using 117private keys with OpenSSL then this doesn't matter. 118 119The B<alg> argument is the encryption algorithm to use, valid values include 120B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used. 121 122=item B<-v2prf alg> 123 124This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value 125values would be B<hmacWithSHA256>. If this option isn't set then the default 126for the cipher is used or B<hmacWithSHA1> if there is no default. 127 128=item B<-v1 alg> 129 130This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete 131list of possible algorithms is included below. 132 133=item B<-engine id> 134 135specifying an engine (by its unique B<id> string) will cause B<pkcs8> 136to attempt to obtain a functional reference to the specified engine, 137thus initialising it if needed. The engine will then be set as the default 138for all available algorithms. 139 140=back 141 142=head1 NOTES 143 144The encrypted form of a PEM encode PKCS#8 files uses the following 145headers and footers: 146 147 -----BEGIN ENCRYPTED PRIVATE KEY----- 148 -----END ENCRYPTED PRIVATE KEY----- 149 150The unencrypted form uses: 151 152 -----BEGIN PRIVATE KEY----- 153 -----END PRIVATE KEY----- 154 155Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration 156counts are more secure that those encrypted using the traditional 157SSLeay compatible formats. So if additional security is considered 158important the keys should be converted. 159 160The default encryption is only 56 bits because this is the encryption 161that most current implementations of PKCS#8 will support. 162 163Some software may use PKCS#12 password based encryption algorithms 164with PKCS#8 format private keys: these are handled automatically 165but there is no option to produce them. 166 167It is possible to write out DER encoded encrypted private keys in 168PKCS#8 format because the encryption details are included at an ASN1 169level whereas the traditional format includes them at a PEM level. 170 171=head1 PKCS#5 v1.5 and PKCS#12 algorithms. 172 173Various algorithms can be used with the B<-v1> command line option, 174including PKCS#5 v1.5 and PKCS#12. These are described in more detail 175below. 176 177=over 4 178 179=item B<PBE-MD2-DES PBE-MD5-DES> 180 181These algorithms were included in the original PKCS#5 v1.5 specification. 182They only offer 56 bits of protection since they both use DES. 183 184=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES> 185 186These algorithms are not mentioned in the original PKCS#5 v1.5 specification 187but they use the same key derivation algorithm and are supported by some 188software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or 18956 bit DES. 190 191=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40> 192 193These algorithms use the PKCS#12 password based encryption algorithm and 194allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. 195 196=back 197 198=head1 EXAMPLES 199 200Convert a private from traditional to PKCS#5 v2.0 format using triple 201DES: 202 203 openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem 204 205Convert a private from traditional to PKCS#5 v2.0 format using AES with 206256 bits in CBC mode and B<hmacWithSHA256> PRF: 207 208 openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem 209 210Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm 211(DES): 212 213 openssl pkcs8 -in key.pem -topk8 -out enckey.pem 214 215Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm 216(3DES): 217 218 openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES 219 220Read a DER unencrypted PKCS#8 format private key: 221 222 openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem 223 224Convert a private key from any PKCS#8 format to traditional format: 225 226 openssl pkcs8 -in pk8.pem -out key.pem 227 228=head1 STANDARDS 229 230Test vectors from this PKCS#5 v2.0 implementation were posted to the 231pkcs-tng mailing list using triple DES, DES and RC2 with high iteration 232counts, several people confirmed that they could decrypt the private 233keys produced and Therefore it can be assumed that the PKCS#5 v2.0 234implementation is reasonably accurate at least as far as these 235algorithms are concerned. 236 237The format of PKCS#8 DSA (and other) private keys is not well documented: 238it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA 239PKCS#8 private key format complies with this standard. 240 241=head1 BUGS 242 243There should be an option that prints out the encryption algorithm 244in use and other details such as the iteration count. 245 246PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private 247key format for OpenSSL: for compatibility several of the utilities use 248the old format at present. 249 250=head1 SEE ALSO 251 252L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>, 253L<gendsa(1)|gendsa(1)> 254 255=cut 256