Danger
This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.
Key Serialization¶
There are several common schemes for serializing asymmetric private and public keys to bytes. They generally support encryption of private keys and additional key metadata.
Many serialization formats support multiple different types of asymmetric keys and will return an instance of the appropriate type. You should check that the returned key matches the type your application expects when using these methods.
>>> from cryptography.hazmat.primitives.asymmetric import dsa, rsa >>> from cryptography.hazmat.primitives.serialization import load_pem_private_key >>> key = load_pem_private_key(pem_data, password=None) >>> if isinstance(key, rsa.RSAPrivateKey): ... signature = sign_with_rsa_key(key, message) ... elif isinstance(key, dsa.DSAPrivateKey): ... signature = sign_with_dsa_key(key, message) ... else: ... raise TypeError
Key dumping¶
The serialization
module contains functions for loading keys from
bytes
. To dump a key
object to bytes
, you must call the appropriate
method on the key object. Documentation for these methods in found in the
rsa
,
dsa
, and
ec
module documentation.
PEM¶
PEM is an encapsulation format, meaning keys in it can actually be any of
several different key types. However these are all self-identifying, so you
don’t need to worry about this detail. PEM keys are recognizable because they
all begin with -----BEGIN {format}-----
and end with -----END
{format}-----
.
Note
A PEM block which starts with -----BEGIN CERTIFICATE-----
is not a
public or private key, it’s an X.509 Certificate. You
can load it using load_pem_x509_certificate()
and
extract the public key with
Certificate.public_key
.
- cryptography.hazmat.primitives.serialization.load_pem_private_key(data, password)[source]¶
New in version 0.6.
Deserialize a private key from PEM encoded data to one of the supported asymmetric private key types.
- Parameters
data (bytes-like) – The PEM encoded key data.
password – The password to use to decrypt the data. Should be
None
if the private key is not encrypted.
- Returns
One of
Ed25519PrivateKey
,X25519PrivateKey
,Ed448PrivateKey
,X448PrivateKey
,RSAPrivateKey
,DSAPrivateKey
,DHPrivateKey
, orEllipticCurvePrivateKey
depending on the contents ofdata
.- Raises
ValueError – If the PEM data could not be decrypted or if its structure could not be decoded successfully.
TypeError – If a
password
was given and the private key was not encrypted. Or if the key was encrypted but no password was supplied.cryptography.exceptions.UnsupportedAlgorithm – If the serialized key type is not supported by the OpenSSL version
cryptography
is using.
- cryptography.hazmat.primitives.serialization.load_pem_public_key(data)[source]¶
New in version 0.6.
Deserialize a public key from PEM encoded data to one of the supported asymmetric public key types. The PEM encoded data is typically a
subjectPublicKeyInfo
payload as specified in RFC 5280.>>> from cryptography.hazmat.primitives.serialization import load_pem_public_key >>> key = load_pem_public_key(public_pem_data) >>> isinstance(key, rsa.RSAPublicKey) True
- Parameters
data (bytes) – The PEM encoded key data.
- Returns
One of
Ed25519PublicKey
,X25519PublicKey
,Ed448PublicKey
,X448PublicKey
,RSAPublicKey
,DSAPublicKey
,DHPublicKey
, orEllipticCurvePublicKey
depending on the contents ofdata
.- Raises
ValueError – If the PEM data’s structure could not be decoded successfully.
cryptography.exceptions.UnsupportedAlgorithm – If the serialized key type is not supported by the OpenSSL version
cryptography
is using.
- cryptography.hazmat.primitives.serialization.load_pem_parameters(data)[source]¶
- .. versionadded:: 2.0
Deserialize parameters from PEM encoded data to one of the supported asymmetric parameters types.
>>> from cryptography.hazmat.primitives.serialization import load_pem_parameters >>> from cryptography.hazmat.primitives.asymmetric import dh >>> parameters = load_pem_parameters(parameters_pem_data) >>> isinstance(parameters, dh.DHParameters) True
- Parameters
data (bytes) – The PEM encoded parameters data.
- Returns
Currently only
DHParameters
supported.- Raises
ValueError – If the PEM data’s structure could not be decoded successfully.
cryptography.exceptions.UnsupportedAlgorithm – If the serialized key type is not supported by the OpenSSL version
cryptography
is using.
DER¶
DER is an ASN.1 encoding type. There are no encapsulation boundaries and the data is binary. DER keys may be in a variety of formats, but as long as you know whether it is a public or private key the loading functions will handle the rest.
- cryptography.hazmat.primitives.serialization.load_der_private_key(data, password)[source]¶
New in version 0.8.
Deserialize a private key from DER encoded data to one of the supported asymmetric private key types.
- Parameters
data (bytes-like) – The DER encoded key data.
password (bytes-like) – The password to use to decrypt the data. Should be
None
if the private key is not encrypted.
- Returns
One of
Ed25519PrivateKey
,X25519PrivateKey
,Ed448PrivateKey
,X448PrivateKey
,RSAPrivateKey
,DSAPrivateKey
,DHPrivateKey
, orEllipticCurvePrivateKey
depending on the contents ofdata
.- Raises
ValueError – If the DER data could not be decrypted or if its structure could not be decoded successfully.
TypeError – If a
password
was given and the private key was not encrypted. Or if the key was encrypted but no password was supplied.cryptography.exceptions.UnsupportedAlgorithm – If the serialized key type is not supported by the OpenSSL version
cryptography
is using.
>>> from cryptography.hazmat.primitives.asymmetric import rsa >>> from cryptography.hazmat.primitives.serialization import load_der_private_key >>> key = load_der_private_key(der_data, password=None) >>> isinstance(key, rsa.RSAPrivateKey) True
- cryptography.hazmat.primitives.serialization.load_der_public_key(data)[source]¶
New in version 0.8.
Deserialize a public key from DER encoded data to one of the supported asymmetric public key types. The DER encoded data is typically a
subjectPublicKeyInfo
payload as specified in RFC 5280.- Parameters
data (bytes) – The DER encoded key data.
- Returns
One of
Ed25519PublicKey
,X25519PublicKey
,Ed448PublicKey
,X448PublicKey
,RSAPublicKey
,DSAPublicKey
,DHPublicKey
, orEllipticCurvePublicKey
depending on the contents ofdata
.- Raises
ValueError – If the DER data’s structure could not be decoded successfully.
cryptography.exceptions.UnsupportedAlgorithm – If the serialized key type is not supported by the OpenSSL version
cryptography
is using.
>>> from cryptography.hazmat.primitives.asymmetric import rsa >>> from cryptography.hazmat.primitives.serialization import load_der_public_key >>> key = load_der_public_key(public_der_data) >>> isinstance(key, rsa.RSAPublicKey) True
- cryptography.hazmat.primitives.serialization.load_der_parameters(data)[source]¶
New in version 2.0.
Deserialize parameters from DER encoded data to one of the supported asymmetric parameters types.
- Parameters
data (bytes) – The DER encoded parameters data.
- Returns
Currently only
DHParameters
supported.- Raises
ValueError – If the DER data’s structure could not be decoded successfully.
cryptography.exceptions.UnsupportedAlgorithm – If the serialized key type is not supported by the OpenSSL version
cryptography
is using.
>>> from cryptography.hazmat.primitives.asymmetric import dh >>> from cryptography.hazmat.primitives.serialization import load_der_parameters >>> parameters = load_der_parameters(parameters_der_data) >>> isinstance(parameters, dh.DHParameters) True
OpenSSH Public Key¶
The format used by OpenSSH to store public keys, as specified in RFC 4253.
An example RSA key in OpenSSH format (line breaks added for formatting purposes):
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDu/XRP1kyK6Cgt36gts9XAk
FiiuJLW6RU0j3KKVZSs1I7Z3UmU9/9aVh/rZV43WQG8jaR6kkcP4stOR0DEtll
PDA7ZRBnrfiHpSQYQ874AZaAoIjgkv7DBfsE6gcDQLub0PFjWyrYQUJhtOLQEK
vY/G0vt2iRL3juawWmCFdTK3W3XvwAdgGk71i6lHt+deOPNEPN2H58E4odrZ2f
sxn/adpDqfb2sM0kPwQs0aWvrrKGvUaustkivQE4XWiSFnB0oJB/lKK/CKVKuy
///ImSCGHQRvhwariN2tvZ6CBNSLh3iQgeB0AkyJlng7MXB2qYq/Ci2FUOryCX
2MzHvnbv testkey@localhost
DSA keys look almost identical but begin with ssh-dss
rather than
ssh-rsa
. ECDSA keys have a slightly different format, they begin with
ecdsa-sha2-{curve}
.
- cryptography.hazmat.primitives.serialization.load_ssh_public_key(data)[source]¶
New in version 0.7.
Deserialize a public key from OpenSSH (RFC 4253 and PROTOCOL.certkeys) encoded data to an instance of the public key type.
- Parameters
data (bytes-like) – The OpenSSH encoded key data.
- Returns
One of
RSAPublicKey
,DSAPublicKey
,EllipticCurvePublicKey
, orEd25519PublicKey
, depending on the contents ofdata
.- Raises
ValueError – If the OpenSSH data could not be properly decoded or if the key is not in the proper format.
cryptography.exceptions.UnsupportedAlgorithm – If the serialized key is of a type that is not supported.
OpenSSH Private Key¶
The format used by OpenSSH to store private keys, as approximately specified in PROTOCOL.key.
An example ECDSA key in OpenSSH format:
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAaAAAABNlY2RzYS
1zaGEyLW5pc3RwMjU2AAAACG5pc3RwMjU2AAAAQQRI0fWnI1CxX7qYqp0ih6bxjhGmUrZK
/Axf8vhM8Db3oH7CFR+JdL715lUdu4XCWvQZKVf60/h3kBFhuxQC23XjAAAAqKPzVaOj81
WjAAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEjR9acjULFfupiq
nSKHpvGOEaZStkr8DF/y+EzwNvegfsIVH4l0vvXmVR27hcJa9BkpV/rT+HeQEWG7FALbde
MAAAAga/VGV2asRlL3kXXao0aochQ59nXHA2xEGeAoQd952r0AAAAJbWFya29AdmZmAQID
BAUGBw==
-----END OPENSSH PRIVATE KEY-----
- cryptography.hazmat.primitives.serialization.load_ssh_private_key(data, password)[source]¶
New in version 3.0.
Deserialize a private key from OpenSSH encoded data to an instance of the private key type.
- Parameters
data (bytes-like) – The PEM encoded OpenSSH private key data.
password (bytes) – Password bytes to use to decrypt password-protected key. Or
None
if not needed.
- Returns
One of
RSAPrivateKey
,DSAPrivateKey
,EllipticCurvePrivateKey
orEd25519PrivateKey
, depending on the contents ofdata
.- Raises
ValueError – If the OpenSSH data could not be properly decoded, if the key is not in the proper format or the incorrect password was provided.
cryptography.exceptions.UnsupportedAlgorithm – If the serialized key is of a type that is not supported.
PKCS12¶
PKCS12 is a binary format described in RFC 7292. It can contain
certificates, keys, and more. PKCS12 files commonly have a pfx
or p12
file suffix.
Note
cryptography
only supports a single private key and associated
certificates when parsing PKCS12 files at this time.
- cryptography.hazmat.primitives.serialization.pkcs12.load_key_and_certificates(data, password)[source]¶
New in version 2.5.
Deserialize a PKCS12 blob.
- Parameters
data (bytes-like) – The binary data.
password (bytes-like) – The password to use to decrypt the data.
None
if the PKCS12 is not encrypted.
- Returns
A tuple of
(private_key, certificate, additional_certificates)
.private_key
is a private key type orNone
,certificate
is either theCertificate
whose public key matches the private key in the PKCS 12 object orNone
, andadditional_certificates
is a list of all otherCertificate
instances in the PKCS12 object.
- cryptography.hazmat.primitives.serialization.pkcs12.load_pkcs12(data, password)[source]¶
New in version 36.0.
Deserialize a PKCS12 blob, and return a
PKCS12KeyAndCertificates
instance.- Parameters
data (bytes-like) – The binary data.
password (bytes-like) – The password to use to decrypt the data.
None
if the PKCS12 is not encrypted.
- Returns
A
PKCS12KeyAndCertificates
instance.
- cryptography.hazmat.primitives.serialization.pkcs12.serialize_key_and_certificates(name, key, cert, cas, encryption_algorithm)[source]¶
New in version 3.0.
Warning
PKCS12 encryption is not secure and should not be used as a security mechanism. Wrap a PKCS12 blob in a more secure envelope if you need to store or send it safely. Encryption is provided for compatibility reasons only.
Serialize a PKCS12 blob.
Note
Due to a bug in Firefox it’s not possible to load unencrypted PKCS12 blobs in Firefox.
- Parameters
name (bytes) – The friendly name to use for the supplied certificate and key.
key (An
RSAPrivateKey
,EllipticCurvePrivateKey
,Ed25519PrivateKey
,Ed448PrivateKey
, orDSAPrivateKey
object.) – The private key to include in the structure.cert (
Certificate
orNone
) – The certificate associated with the private key.cas (
None
, or list ofCertificate
orPKCS12Certificate
) – An optional set of certificates to also include in the structure. If aPKCS12Certificate
is given, its friendly name will be serialized.encryption_algorithm – The encryption algorithm that should be used for the key and certificate. An instance of an object conforming to the
KeySerializationEncryption
interface. PKCS12 encryption is very weak and should not be used as a security boundary.
- Return bytes
Serialized PKCS12.
- class cryptography.hazmat.primitives.serialization.pkcs12.PKCS12Certificate[source]¶
New in version 36.0.
Represents additional data provided for a certificate in a PKCS12 file.
- certificate¶
A
Certificate
instance.
- class cryptography.hazmat.primitives.serialization.pkcs12.PKCS12KeyAndCertificates[source]¶
New in version 36.0.
A simplified representation of a PKCS12 file.
- cert¶
An optional
PKCS12Certificate
instance belonging to the private keykey
.
- additional_certs¶
A list of
PKCS12Certificate
instances.
PKCS7¶
PKCS7 is a format described in RFC 2315, among other specifications. It can
contain certificates, CRLs, and much more. PKCS7 files commonly have a p7b
,
p7m
, or p7s
file suffix but other suffixes are also seen in the wild.
Note
cryptography
only supports parsing certificates from PKCS7 files at
this time.
- cryptography.hazmat.primitives.serialization.pkcs7.load_pem_pkcs7_certificates(data)[source]¶
New in version 3.1.
Deserialize a PEM encoded PKCS7 blob to a list of certificates. PKCS7 can contain many other types of data, including CRLs, but this function will ignore everything except certificates.
- Parameters
data (bytes) – The data.
- Returns
A list of
Certificate
.- Raises
ValueError – If the PKCS7 data could not be loaded.
cryptography.exceptions.UnsupportedAlgorithm – If the PKCS7 data is of a type that is not supported.
- cryptography.hazmat.primitives.serialization.pkcs7.load_der_pkcs7_certificates(data)[source]¶
New in version 3.1.
Deserialize a DER encoded PKCS7 blob to a list of certificates. PKCS7 can contain many other types of data, including CRLs, but this function will ignore everything except certificates.
- Parameters
data (bytes) – The data.
- Returns
A list of
Certificate
.- Raises
ValueError – If the PKCS7 data could not be loaded.
cryptography.exceptions.UnsupportedAlgorithm – If the PKCS7 data is of a type that is not supported.
- cryptography.hazmat.primitives.serialization.pkcs7.serialize_certificates(certs, encoding)[source]¶
New in version 37.0.
Serialize a list of certificates to a PKCS7 structure.
- Parameters
certs – A list of
Certificate
.
- Return bytes
The serialized PKCS7 data.
- class cryptography.hazmat.primitives.serialization.pkcs7.PKCS7SignatureBuilder[source]¶
The PKCS7 signature builder can create both basic PKCS7 signed messages as well as S/MIME messages, which are commonly used in email. S/MIME has multiple versions, but this implements a subset of RFC 2632, also known as S/MIME Version 3.
New in version 3.2.
>>> from cryptography import x509 >>> from cryptography.hazmat.primitives import hashes, serialization >>> from cryptography.hazmat.primitives.serialization import pkcs7 >>> cert = x509.load_pem_x509_certificate(ca_cert) >>> key = serialization.load_pem_private_key(ca_key, None) >>> options = [pkcs7.PKCS7Options.DetachedSignature] >>> pkcs7.PKCS7SignatureBuilder().set_data( ... b"data to sign" ... ).add_signer( ... cert, key, hashes.SHA256() ... ).sign( ... serialization.Encoding.SMIME, options ... ) b'...'
- set_data(data)[source]¶
- Parameters
data (bytes-like) – The data to be hashed and signed.
- add_signer(certificate, private_key, hash_algorithm)[source]¶
- Parameters
certificate – The
Certificate
.private_key – The
RSAPrivateKey
orEllipticCurvePrivateKey
associated with the certificate provided.hash_algorithm – The
HashAlgorithm
that will be used to generate the signature. This must be an instance ofSHA1
,SHA224
,SHA256
,SHA384
, orSHA512
.
- add_certificate(certificate)[source]¶
Add an additional certificate (typically used to help build a verification chain) to the PKCS7 structure. This method may be called multiple times to add as many certificates as desired.
- Parameters
certificate – The
Certificate
to add.
- class cryptography.hazmat.primitives.serialization.pkcs7.PKCS7Options[source]¶
New in version 3.2.
An enumeration of options for PKCS7 signature creation.
- Text¶
The text option adds
text/plain
headers to an S/MIME message when serializing toSMIME
. This option is disallowed withDER
serialization.
- Binary¶
Signing normally converts line endings (LF to CRLF). When passing this option the data will not be converted.
- DetachedSignature¶
Don’t embed the signed data within the ASN.1. When signing with
SMIME
this also results in the data being added as clear text before the PEM encoded structure.
- NoCapabilities¶
PKCS7 structures contain a
MIMECapabilities
section inside theauthenticatedAttributes
. Passing this as an option removesMIMECapabilities
.
- NoAttributes¶
PKCS7 structures contain an
authenticatedAttributes
section. Passing this as an option removes that section. Note that if you passNoAttributes
you can’t passNoCapabilities
sinceNoAttributes
removesMIMECapabilities
and more.
- NoCerts¶
Don’t include the signer’s certificate in the PKCS7 structure. This can reduce the size of the signature but requires that the recipient can obtain the signer’s certificate by other means (for example from a previously signed message).
Serialization Formats¶
- class cryptography.hazmat.primitives.serialization.PrivateFormat[source]¶
New in version 0.8.
An enumeration for private key formats. Used with the
private_bytes
method available onRSAPrivateKeyWithSerialization
,EllipticCurvePrivateKeyWithSerialization
,DHPrivateKeyWithSerialization
andDSAPrivateKeyWithSerialization
.- TraditionalOpenSSL¶
Frequently known as PKCS#1 format. Still a widely used format, but generally considered legacy.
A PEM encoded RSA key will look like:
-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
- PKCS8¶
A more modern format for serializing keys which allows for better encryption. Choose this unless you have explicit legacy compatibility requirements.
A PEM encoded key will look like:
-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----
- Raw¶
New in version 2.5.
A raw format used by X448 key exchange. It is a binary format and is invalid for other key types.
- class cryptography.hazmat.primitives.serialization.PublicFormat[source]¶
New in version 0.8.
An enumeration for public key formats. Used with the
public_bytes
method available onRSAPublicKeyWithSerialization
,EllipticCurvePublicKeyWithSerialization
,DHPublicKeyWithSerialization
, andDSAPublicKeyWithSerialization
.- SubjectPublicKeyInfo¶
This is the typical public key format. It consists of an algorithm identifier and the public key as a bit string. Choose this unless you have specific needs.
A PEM encoded key will look like:
-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----
- PKCS1¶
Just the public key elements (without the algorithm identifier). This format is RSA only, but is used by some older systems.
A PEM encoded key will look like:
-----BEGIN RSA PUBLIC KEY----- ... -----END RSA PUBLIC KEY-----
- OpenSSH¶
New in version 1.4.
The public key format used by OpenSSH (e.g. as found in
~/.ssh/id_rsa.pub
or~/.ssh/authorized_keys
).
- Raw¶
New in version 2.5.
A raw format used by X448 key exchange. It is a binary format and is invalid for other key types.
- CompressedPoint¶
New in version 2.5.
A compressed elliptic curve public key as defined in ANSI X9.62 section 4.3.6 (as well as SEC 1 v2.0).
- UncompressedPoint¶
New in version 2.5.
An uncompressed elliptic curve public key as defined in ANSI X9.62 section 4.3.6 (as well as SEC 1 v2.0).
- class cryptography.hazmat.primitives.serialization.ParameterFormat[source]¶
New in version 2.0.
An enumeration for parameters formats. Used with the
parameter_bytes
method available onDHParametersWithSerialization
.
Serialization Encodings¶
- class cryptography.hazmat.primitives.serialization.Encoding[source]¶
An enumeration for encoding types. Used with the
private_bytes
method available onRSAPrivateKeyWithSerialization
,EllipticCurvePrivateKeyWithSerialization
,DHPrivateKeyWithSerialization
,DSAPrivateKeyWithSerialization
, andX448PrivateKey
as well aspublic_bytes
onRSAPublicKey
,DHPublicKey
,EllipticCurvePublicKey
, andX448PublicKey
.- PEM¶
New in version 0.8.
For PEM format. This is a base64 format with delimiters.
- DER¶
New in version 0.9.
For DER format. This is a binary format.
- OpenSSH¶
New in version 1.4.
The format used by OpenSSH public keys. This is a text format.
- Raw¶
New in version 2.5.
A raw format used by X448 key exchange. It is a binary format and is invalid for other key types.
- X962¶
New in version 2.5.
The format used by elliptic curve point encodings. This is a binary format.
- SMIME¶
New in version 3.2.
An output format used for PKCS7. This is a text format.
Serialization Encryption Types¶
- class cryptography.hazmat.primitives.serialization.KeySerializationEncryption[source]¶
Objects with this interface are usable as encryption types with methods like
private_bytes
available onRSAPrivateKey
,EllipticCurvePrivateKey
,DHPrivateKey
andDSAPrivateKey
. All other classes in this section represent the available choices for encryption and have this interface.