pkcs8(1)

     PKCS8(1)               0.9.6h (2000-02-16)               PKCS8(1)

     NAME
          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]
          [-v1 alg]

     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.

          -passout arg

     Page 1                                         (printed 1/19/103)

     PKCS8(1)               0.9.6h (2000-02-16)               PKCS8(1)

              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.

     Page 2                                         (printed 1/19/103)

     PKCS8(1)               0.9.6h (2000-02-16)               PKCS8(1)

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

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

     Page 3                                         (printed 1/19/103)

     PKCS8(1)               0.9.6h (2000-02-16)               PKCS8(1)

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

     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.

     Page 4                                         (printed 1/19/103)

     PKCS8(1)               0.9.6h (2000-02-16)               PKCS8(1)

          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)

     Page 5                                         (printed 1/19/103)