PKCS#8

PKCS#8 is a standard for storing and transferring private key information. The wrapped key can either be clear or encrypted.

All encryption algorithms are based on passphrase-based key derivation. The following mechanisms are fully supported:

  • PBKDF2WithHMAC-SHA1AndAES128-CBC
  • PBKDF2WithHMAC-SHA1AndAES192-CBC
  • PBKDF2WithHMAC-SHA1AndAES256-CBC
  • PBKDF2WithHMAC-SHA1AndDES-EDE3-CBC
  • scryptAndAES128-CBC
  • scryptAndAES192-CBC
  • scryptAndAES256-CBC

The following mechanisms are only supported for importing keys. They are much weaker than the ones listed above, and they are provided for backward compatibility only:

  • pbeWithMD5AndRC2-CBC
  • pbeWithMD5AndDES-CBC
  • pbeWithSHA1AndRC2-CBC
  • pbeWithSHA1AndDES-CBC
Crypto.IO.PKCS8.wrap(private_key, key_oid, passphrase=None, protection=None, prot_params=None, key_params=None, randfunc=None)

Wrap a private key into a PKCS#8 blob (clear or encrypted).

Parameters:
  • private_key (byte string) – The private key encoded in binary form. The actual encoding is algorithm specific. In most cases, it is DER.
  • key_oid (string) – The object identifier (OID) of the private key to wrap. It is a dotted string, like 1.2.840.113549.1.1.1 (for RSA keys).
  • passphrase (bytes string or string) – The secret passphrase from which the wrapping key is derived. Set it only if encryption is required.
  • protection (string) – The identifier of the algorithm to use for securely wrapping the key. The default value is PBKDF2WithHMAC-SHA1AndDES-EDE3-CBC.
  • prot_params (dictionary) –

    Parameters for the protection algorithm.

    Key Description
    iteration_count The KDF algorithm is repeated several times to slow down brute force attacks on passwords (called N or CPU/memory cost in scrypt). The default value for PBKDF2 is 1000. The default value for scrypt is 16384.
    salt_size Salt is used to thwart dictionary and rainbow attacks on passwords. The default value is 8 bytes.
    block_size (scrypt only) Memory-cost (r). The default value is 8.
    parallelization (scrypt only) CPU-cost (p). The default value is 1.
  • key_params (DER object) – The algorithm parameters associated to the private key. It is required for algorithms like DSA, but not for others like RSA.
  • randfunc (callable) – Random number generation function; it should accept a single integer N and return a string of random data, N bytes long. If not specified, a new RNG will be instantiated from Crypto.Random.
Returns:

The PKCS#8-wrapped private key (possibly encrypted), as a byte string.
Crypto.IO.PKCS8.unwrap(p8_private_key, passphrase=None)

Unwrap a private key from a PKCS#8 blob (clear or encrypted).

Parameters:
  • p8_private_key (byte string) – The private key wrapped into a PKCS#8 blob, DER encoded.
  • passphrase (byte string or string) – The passphrase to use to decrypt the blob (if it is encrypted).
Returns:

A tuple containing

  1. the algorithm identifier of the wrapped key (OID, dotted string)
  2. the private key (byte string, DER encoded)
  3. the associated parameters (byte string, DER encoded) or None
Raises:

ValueError – if decoding fails