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