diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2016-05-17 14:15:20 +0100 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2016-05-23 16:41:34 +0100 |
commit | 05dba8151bd418cdc111d62102aaf9f4e7bd2f3f (patch) | |
tree | d29b35e495de274097853570f16271fe29f32cb8 /doc/apps | |
parent | 07930a75a1f82fd359d0af7849f01990b73659dd (diff) |
Support for traditional format private keys.
Add new function PEM_write_bio_PrivateKey_traditional() to enforce the
use of legacy "traditional" private key format. Add -traditional option
to pkcs8 and pkey utilities.
Reviewed-by: Matt Caswell <matt@openssl.org>
Diffstat (limited to 'doc/apps')
-rw-r--r-- | doc/apps/pkcs8.pod | 74 | ||||
-rw-r--r-- | doc/apps/pkey.pod | 7 |
2 files changed, 57 insertions, 24 deletions
diff --git a/doc/apps/pkcs8.pod b/doc/apps/pkcs8.pod index d8522b2e04..cd6db02a59 100644 --- a/doc/apps/pkcs8.pod +++ b/doc/apps/pkcs8.pod @@ -18,6 +18,7 @@ B<openssl> B<pkcs8> [B<-iter count>] [B<-noiter>] [B<-nocrypt>] +[B<-traditional>] [B<-v2 alg>] [B<-v2prf alg>] [B<-v1 alg>] @@ -43,22 +44,22 @@ Print out a usage message. =item B<-topk8> -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. +Normally a PKCS#8 private key is expected on input and a private key will be +written to the output file. With the B<-topk8> option the situation is +reversed: it reads a private key and writes a PKCS#8 format key. =item B<-inform DER|PEM> -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 -private key is used. +This specifies the input format: see L<KEY FORMATS> for more details. =item B<-outform DER|PEM> -This specifies the output format, the options have the same meaning as the -B<-inform> option. +This specifies the output format: see L<KEY FORMATS> for more details. + +=item B<-traditional> + +When this option is present and B<-topk8> is not a traditional format private +key is written. =item B<-in filename> @@ -119,7 +120,7 @@ the B<hmacWithSHA1> option to work. This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some older implementations may not support PKCS#5 v2.0 and may require this option. -If not specified PKCS#5 v2.0 for is used. +If not specified PKCS#5 v2.0 form is used. =item B<-engine id> @@ -141,6 +142,27 @@ sets the scrypt B<N>, B<r> or B<p> parameters. =back +=head1 KEY FORMATS + +Various different formats are used by the pkcs8 utility. These are detailed +below. + +If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is +not used) then the input file must be in PKCS#8 format. An encrypted +key is expected unless B<-nocrypt> is included. + +If B<-topk8> is not used and B<PEM> mode is set the output file will be an +unencrypted private key in PKCS#8 format. If the B<-traditional> option is +used then a traditional format private key is written instead. + +If B<-topk8> is not used and B<DER> mode is set the output file will be an +unencrypted private key in traditional DER format. + +If B<-topk8> is used then any supported private key can be used for the input +file in a format specified by B<-inform>. The output file will be encrypted +PKCS#8 format using the specified encryption parameters unless B<-nocrypt> +is included. + =head1 NOTES By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit @@ -199,20 +221,28 @@ allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. =head1 EXAMPLES -Convert a private from traditional to PKCS#5 v2.0 format using triple -DES: +Convert a private key to PKCS#8 format using default parameters (AES with +256 bit key and B<hmacWithSHA256>): + + openssl pkcs8 -in key.pem -topk8 -out enckey.pem + +Convert a private key to PKCS#8 unencrypted format: + + openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem + +Convert a private key to PKCS#5 v2.0 format using triple DES: openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem -Convert a private from traditional to PKCS#5 v2.0 format using AES with -256 bits in CBC mode and B<hmacWithSHA256> PRF: +Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC +mode and B<hmacWithSHA512> PRF: - openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem + openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm (DES): - openssl pkcs8 -in key.pem -topk8 -out enckey.pem + openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm (3DES): @@ -223,14 +253,14 @@ Read a DER unencrypted PKCS#8 format private key: openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem -Convert a private key from any PKCS#8 format to traditional format: +Convert a private key from any PKCS#8 encrypted format to traditional format: - openssl pkcs8 -in pk8.pem -out key.pem + openssl pkcs8 -in pk8.pem -traditional -out key.pem Convert a private key to PKCS#8 format, encrypting with AES-256 and with one million iterations of the password: - openssl pkcs8 -in raw.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem + openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem =head1 STANDARDS @@ -250,10 +280,6 @@ PKCS#8 private key format complies with this standard. 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 compatibility several of the utilities use -the old format at present. - =head1 SEE ALSO L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>, diff --git a/doc/apps/pkey.pod b/doc/apps/pkey.pod index 2848502535..dc736a3370 100644 --- a/doc/apps/pkey.pod +++ b/doc/apps/pkey.pod @@ -14,6 +14,7 @@ B<openssl> B<pkey> [B<-passin arg>] [B<-out filename>] [B<-passout arg>] +[B<-traditional>] [B<-cipher>] [B<-text>] [B<-text_pub>] @@ -67,6 +68,12 @@ filename. the output file password source. For more information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. +=item B<-traditional> + +normally a private key is written using standard format: this is PKCS#8 form +with the appropriate encryption algorithm (if any). If the B<-traditional> +option is specified then the older "traditional" format is used instead. + =item B<-cipher> These options encrypt the private key with the supplied cipher. Any algorithm |