DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

/usr/man/cat.1/openssl-pkcs8.1



PKCS8(1)                     OpenSSL                     PKCS8(1)

NAME

     openssl-pkcs8, pkcs8 - PKCS#8 format private key conversion
     tool

SYNOPSIS

     openssl pkcs8 [-topk8] [-inform PEM|DER] [-outform PEM|DER]
     [-in filename] [-passin arg] [-out filename] [-passout arg]
     [-noiter] [-nocrypt] [-nooct] [-embed] [-nsdb] [-v2 alg]
     [-v2prf alg] [-v1 alg] [-engine id]

DESCRIPTION

     The pkcs8 command processes private keys in PKCS#8 format.
     It can handle both unencrypted PKCS#8 PrivateKeyInfo format
     and EncryptedPrivateKeyInfo format with a variety of PKCS#5
     (v1.5 and v2.0) and PKCS#12 algorithms.

COMMAND OPTIONS

     -topk8
         Normally a PKCS#8 private key is expected on input and a
         traditional format private key will be written. With the
         -topk8 option the situation is reversed: it reads a
         traditional format private key and writes a PKCS#8
         format key.

     -inform DER|PEM
         This specifies the input format. If a PKCS#8 format key
         is expected on input then either a DER or PEM encoded
         version of a PKCS#8 key will be expected. Otherwise the
         DER or PEM format of the traditional format private key
         is used.

     -outform DER|PEM
         This specifies the output format, the options have the
         same meaning as the -inform option.

     -in filename
         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.

     -passin arg
         the input file password source. For more information
         about the format of arg see the PASS PHRASE ARGUMENTS
         section in openssl(1).

     -out filename
         This specifies the output filename to write a key to or
         standard output by default. If any encryption options
         are set then a pass phrase will be prompted for. The
         output filename should not be the same as the input
         filename.

1.0.2t               Last change: 2019-09-10                    1

PKCS8(1)                     OpenSSL                     PKCS8(1)

     -passout arg
         the output file password source. For more information
         about the format of arg see the PASS PHRASE ARGUMENTS
         section in openssl(1).

     -nocrypt
         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.

     -nooct
         This option generates RSA 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.

     -embed
         This option generates DSA keys in a broken format. The
         DSA parameters are embedded inside the PrivateKey
         structure. In this form the OCTET STRING contains an
         ASN1 SEQUENCE consisting of two structures: a SEQUENCE
         containing the parameters and an ASN1 INTEGER containing
         the private key.

     -nsdb
         This option generates DSA keys in a broken format
         compatible with Netscape private key databases. The
         PrivateKey contains a SEQUENCE consisting of the public
         and private keys respectively.

     -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
         pbeWithMD5AndDES-CBC this uses 56 bit DES encryption but
         it was the strongest encryption algorithm supported in
         PKCS#5 v1.5. Using the -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 alg argument is the encryption algorithm to use,
         valid values include des, des3 and rc2. It is
         recommended that des3 is used.

1.0.2t               Last change: 2019-09-10                    2

PKCS8(1)                     OpenSSL                     PKCS8(1)

     -v2prf alg
         This option sets the PRF algorithm to use with PKCS#5
         v2.0. A typical value values would be hmacWithSHA256. If
         this option isn't set then the default for the cipher is
         used or hmacWithSHA1 if there is no default.

     -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.

     -engine id
         specifying an engine (by its unique id string) will
         cause pkcs8 to attempt to obtain a functional reference
         to the specified engine, thus initialising it if needed.
         The engine will then be set as the default for all
         available algorithms.

NOTES

     The encrypted form of a PEM encode PKCS#8 files uses the
     following headers and footers:

      -----BEGIN ENCRYPTED PRIVATE KEY-----
      -----END ENCRYPTED PRIVATE KEY-----

     The unencrypted form uses:

      -----BEGIN PRIVATE KEY-----
      -----END PRIVATE KEY-----

     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.

     The default encryption is only 56 bits because this is the
     encryption that most current implementations of PKCS#8 will
     support.

     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.

     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.

PKCS#5 v1.5 and PKCS#12 algorithms.

     Various algorithms can be used with the -v1 command line

1.0.2t               Last change: 2019-09-10                    3

PKCS8(1)                     OpenSSL                     PKCS8(1)

     option, including PKCS#5 v1.5 and PKCS#12. These are
     described in more detail below.

     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.

     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 v2.0. They use either 64
         bit RC2 or 56 bit DES.

PBE-SHA1-RC2-128 PBE-SHA1-RC2-40

     PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES
         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.

EXAMPLES

     Convert a private from traditional 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 hmacWithSHA256 PRF:

      openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -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

     Convert a private key to PKCS#8 using a PKCS#12 compatible
     algorithm (3DES):

      openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES

     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:

      openssl pkcs8 -in pk8.pem -out key.pem

1.0.2t               Last change: 2019-09-10                    4

PKCS8(1)                     OpenSSL                     PKCS8(1)

STANDARDS

     Test vectors from this PKCS#5 v2.0 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.

     The format of PKCS#8 DSA (and other) private keys is not
     well documented:  it is hidden away in PKCS#11 v2.01,
     section 11.9. OpenSSL's default DSA PKCS#8 private key
     format complies with this standard.

BUGS

     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.

SEE ALSO

     dsa(1), rsa(1), genrsa(1), gendsa(1)

1.0.2t               Last change: 2019-09-10                    5

See also pkcs8(1)
Man(1) output converted with man2html