439 lines
17 KiB
ReStructuredText
439 lines
17 KiB
ReStructuredText
.. hazmat::
|
|
|
|
Key Serialization
|
|
=================
|
|
|
|
.. module:: cryptography.hazmat.primitives.serialization
|
|
|
|
.. testsetup::
|
|
|
|
import base64
|
|
|
|
pem_data = b"""
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
MIICXgIBAAKBgQDn09PV9KPE7Q+N5K5UtNLT1DLl8z/pKM2pP5tXqWx2OsEw00lC
|
|
kDHdHESwzS050s/8rtkERKKyusCzCm9+vC1pQzUlmtibfF4PQAQc1pJL6KHqlidg
|
|
Hw49atYmnC25CaeXt65pAYXoIacOZ8k5X7FW3Eagex8nG0iMw4ObOtg6CwIDAQAB
|
|
AoGBAL31l/4YYN1rNrSZLrQgGyUSGsbLxJHEKolFon95R3O1fzoH117gkstQb4TE
|
|
Cwv3jw/JIfBaYUq8tku/AE9D2Jx51x7kYaCuQIMTavKIgkXKfxTQCQDjSEfkvXMW
|
|
4WOIj5sYdSCNbzLbaeFsWG32bSsBTy/sSheDIlCEFnqDuqwBAkEA+wYfJEMDf5nS
|
|
VCQd9VKGM4HVeTWBioaWBFCflFdhc1Vb65dsNDp8iIMZgAHC2LEX5dMUmgqXk7AT
|
|
lwFlIeW4CwJBAOxsSfuIVMuPKyx1xQ6ebpC7zeVxIOdswcM8ain91MSGDdKZw6pF
|
|
ioFh3kUbKHw4yqqHbdRmUDAJ1mcgGJQOxgECQQCmQaGylKfmhWymyd0FtIip6J4I
|
|
z4ViyEznwrZOu6kRiEF/QiUqWmpMx/fFrmTsvC5Fy43jkIxgBsiSxRvEXa+NAkB+
|
|
5m0bhwTEslchKSGZhC6inzuYAQ4BSh4C1mXBnk5bIf0/Ymtk9KiwY8CzZS1o5+7Y
|
|
c5LfI/+8mTss5UxsBDYBAkEA6NqhcsNWndIJZiWUU4u+RjFUQXqH8WCyJmEDCNxs
|
|
7SGRS1DTUGX4Y70m9dQpguy6Zg+gpHC+o+ERZR06uEQr+w==
|
|
-----END RSA PRIVATE KEY-----
|
|
""".strip()
|
|
public_pem_data = b"""
|
|
-----BEGIN PUBLIC KEY-----
|
|
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDn09PV9KPE7Q+N5K5UtNLT1DLl
|
|
8z/pKM2pP5tXqWx2OsEw00lCkDHdHESwzS050s/8rtkERKKyusCzCm9+vC1pQzUl
|
|
mtibfF4PQAQc1pJL6KHqlidgHw49atYmnC25CaeXt65pAYXoIacOZ8k5X7FW3Eag
|
|
ex8nG0iMw4ObOtg6CwIDAQAB
|
|
-----END PUBLIC KEY-----
|
|
""".strip()
|
|
der_data = base64.b64decode(
|
|
b"MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBALskegl+DrI3Msw5Z63x"
|
|
b"nj1rgoPR0KykwBi+jZgAwHv/B0TJyhy6NuEnaf+x442L7lepOqoWQzlUGXyuaSQU9mT/"
|
|
b"vHTGZ2xM8QJJaccr4eGho0MU9HePyNCFWjWVrGKpwSEAd6CLlzC0Wiy4kC9IoAUoS/IP"
|
|
b"jeyLTQNCddatgcARAgMBAAECgYAA/LlKJgeJUStTcpHgGD6mXjHvnAwWJELQKDP5+tA8"
|
|
b"VAQGwBX1G5qzJDGrPGtHQ7DSqdwF4YFZtgTpZmGq1wsAjz3lv6L4XiVsHiIPtP1B4gMx"
|
|
b"X9ogxcDzVQ7hyezXPioMAcp7Isus9Csn8HhftcL56BRabn6GvWqbIAy6zJcgEQJBAMlZ"
|
|
b"nymKW5/jKth+wkCfqEXlPhGNPO1uq87QZUbYxwdjtSM09J9+HMfH+WXR9ARCOL46DJ0I"
|
|
b"JfyjcdmuDDlh9IkCQQDt76up1Tmc7lkb/89IRBu2MudGJPMEf96VCG11nmcXulyk1OLi"
|
|
b"TXfO62YpxZbgYrvlrNxEYlSG7WQMztBgA51JAkBU2RhyJ+S+drsaaigvlVgSxCyotszi"
|
|
b"/Q0XZMgY18bfPUwanvkqsLkuEv3sw1HB7an9t3aTQdjIIpQad/acw8OJAkEAjvmnCK21"
|
|
b"KgTbjQShtQYgNNLPwImxcjG4OYvP4o6l2k9FHlNCZsQwSymOwWkXKYyK5g+CaKFBs7Zw"
|
|
b"mXWpJxjk6QJBAInqbm1w3yVfGD9I2mMQi/6oDJQP3pdWU4mU4h4sdDyRgTQLpkD4yypg"
|
|
b"jOACt4mTzxifSVT9fT+a79SkT8FFmZE="
|
|
)
|
|
public_der_data = base64.b64decode(
|
|
b"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC7JHoJfg6yNzLMOWet8Z49a4KD0dCs"
|
|
b"pMAYvo2YAMB7/wdEycocujbhJ2n/seONi+5XqTqqFkM5VBl8rmkkFPZk/7x0xmdsTPEC"
|
|
b"SWnHK+HhoaNDFPR3j8jQhVo1laxiqcEhAHegi5cwtFosuJAvSKAFKEvyD43si00DQnXW"
|
|
b"rYHAEQIDAQAB"
|
|
)
|
|
message = b""
|
|
|
|
def sign_with_rsa_key(key, message):
|
|
return b""
|
|
|
|
def sign_with_dsa_key(key, message):
|
|
return b""
|
|
|
|
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.
|
|
|
|
.. doctest::
|
|
|
|
>>> from cryptography.hazmat.backends import default_backend
|
|
>>> 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, backend=default_backend())
|
|
>>> 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
|
|
bytes on the key object. Documentation for these methods in found in the
|
|
:mod:`~cryptography.hazmat.primitives.asymmetric.rsa`,
|
|
:mod:`~cryptography.hazmat.primitives.asymmetric.dsa`, and
|
|
:mod:`~cryptography.hazmat.primitives.asymmetric.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 :doc:`X.509 Certificate </x509/index>`. You
|
|
can load it using :func:`~cryptography.x509.load_pem_x509_certificate` and
|
|
extract the public key with
|
|
:meth:`Certificate.public_key <cryptography.x509.Certificate.public_key>`.
|
|
|
|
.. function:: load_pem_private_key(data, password, backend)
|
|
|
|
.. versionadded:: 0.6
|
|
|
|
Deserialize a private key from PEM encoded data to one of the supported
|
|
asymmetric private key types.
|
|
|
|
:param bytes data: The PEM encoded key data.
|
|
|
|
:param bytes password: The password to use to decrypt the data. Should
|
|
be ``None`` if the private key is not encrypted.
|
|
|
|
:param backend: An instance of
|
|
:class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`.
|
|
|
|
:returns: One of
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
|
|
or
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
|
|
depending on the contents of ``data``.
|
|
|
|
:raises ValueError: If the PEM data could not be decrypted or if its
|
|
structure could not be decoded successfully.
|
|
|
|
:raises TypeError: If a ``password`` was given and the private key was
|
|
not encrypted. Or if the key was encrypted but no
|
|
password was supplied.
|
|
|
|
:raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key
|
|
is of a type that is not supported by the backend or if the key is
|
|
encrypted with a symmetric cipher that is not supported by the backend.
|
|
|
|
.. function:: load_pem_public_key(data, backend)
|
|
|
|
.. versionadded:: 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`.
|
|
|
|
.. doctest::
|
|
|
|
>>> from cryptography.hazmat.primitives.serialization import load_pem_public_key
|
|
>>> key = load_pem_public_key(public_pem_data, backend=default_backend())
|
|
>>> isinstance(key, rsa.RSAPublicKey)
|
|
True
|
|
|
|
:param bytes data: The PEM encoded key data.
|
|
|
|
:param backend: An instance of
|
|
:class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`.
|
|
|
|
|
|
:returns: One of
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
|
|
or
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
|
|
depending on the contents of ``data``.
|
|
|
|
:raises ValueError: If the PEM data's structure could not be decoded
|
|
successfully.
|
|
|
|
:raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key
|
|
is of a type that is not supported by the backend.
|
|
|
|
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.
|
|
|
|
.. function:: load_der_private_key(data, password, backend)
|
|
|
|
.. versionadded:: 0.8
|
|
|
|
Deserialize a private key from DER encoded data to one of the supported
|
|
asymmetric private key types.
|
|
|
|
:param bytes data: The DER encoded key data.
|
|
|
|
:param bytes password: The password to use to decrypt the data. Should
|
|
be ``None`` if the private key is not encrypted.
|
|
|
|
:param backend: An instance of
|
|
:class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`.
|
|
|
|
:returns: One of
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
|
|
or
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
|
|
depending on the contents of ``data``.
|
|
|
|
:raises ValueError: If the DER data could not be decrypted or if its
|
|
structure could not be decoded successfully.
|
|
|
|
:raises TypeError: If a ``password`` was given and the private key was
|
|
not encrypted. Or if the key was encrypted but no
|
|
password was supplied.
|
|
|
|
:raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key is of a type that
|
|
is not supported by the backend or if the key is encrypted with a
|
|
symmetric cipher that is not supported by the backend.
|
|
|
|
.. doctest::
|
|
|
|
>>> from cryptography.hazmat.backends import default_backend
|
|
>>> 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, backend=default_backend())
|
|
>>> isinstance(key, rsa.RSAPrivateKey)
|
|
True
|
|
|
|
.. function:: load_der_public_key(data, backend)
|
|
|
|
.. versionadded:: 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`.
|
|
|
|
:param bytes data: The DER encoded key data.
|
|
|
|
:param backend: An instance of
|
|
:class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`.
|
|
|
|
:returns: One of
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
|
|
or
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
|
|
depending on the contents of ``data``.
|
|
|
|
:raises ValueError: If the DER data's structure could not be decoded
|
|
successfully.
|
|
|
|
:raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key is of a type that
|
|
is not supported by the backend.
|
|
|
|
.. doctest::
|
|
|
|
>>> from cryptography.hazmat.backends import default_backend
|
|
>>> 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, backend=default_backend())
|
|
>>> isinstance(key, rsa.RSAPublicKey)
|
|
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}``.
|
|
|
|
.. function:: load_ssh_public_key(data, backend)
|
|
|
|
.. versionadded:: 0.7
|
|
|
|
Deserialize a public key from OpenSSH (:rfc:`4253`) encoded data to an
|
|
instance of the public key type for the specified backend.
|
|
|
|
.. note::
|
|
|
|
Currently Ed25519 keys are not supported.
|
|
|
|
:param bytes data: The OpenSSH encoded key data.
|
|
|
|
:param backend: A backend which implements
|
|
:class:`~cryptography.hazmat.backends.interfaces.RSABackend`,
|
|
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`, or
|
|
:class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`
|
|
depending on the key's type.
|
|
|
|
:returns: One of
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
|
|
or
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
|
|
depending on the contents of ``data``.
|
|
|
|
:raises ValueError: If the OpenSSH data could not be properly decoded or
|
|
if the key is not in the proper format.
|
|
|
|
:raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized
|
|
key is of a type that is not supported.
|
|
|
|
Serialization Formats
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. class:: PrivateFormat
|
|
|
|
.. versionadded:: 0.8
|
|
|
|
An enumeration for private key formats. Used with the ``private_bytes``
|
|
method available on
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization`
|
|
,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization`
|
|
and
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKeyWithSerialization`.
|
|
|
|
.. attribute:: TraditionalOpenSSL
|
|
|
|
Frequently known as PKCS#1 format. Still a widely used format, but
|
|
generally considered legacy.
|
|
|
|
.. attribute:: PKCS8
|
|
|
|
A more modern format for serializing keys which allows for better
|
|
encryption. Choose this unless you have explicit legacy compatibility
|
|
requirements.
|
|
|
|
.. class:: PublicFormat
|
|
|
|
.. versionadded:: 0.8
|
|
|
|
An enumeration for public key formats. Used with the ``public_bytes``
|
|
method available on
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization`
|
|
,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKeyWithSerialization`
|
|
, and
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKeyWithSerialization`.
|
|
|
|
.. attribute:: 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.
|
|
|
|
.. attribute:: PKCS1
|
|
|
|
Just the public key elements (without the algorithm identifier). This
|
|
format is RSA only, but is used by some older systems.
|
|
|
|
.. attribute:: OpenSSH
|
|
|
|
.. versionadded:: 1.4
|
|
|
|
The public key format used by OpenSSH (e.g. as found in
|
|
``~/.ssh/id_rsa.pub`` or ``~/.ssh/authorized_keys``).
|
|
|
|
Serialization Encodings
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. class:: Encoding
|
|
|
|
An enumeration for encoding types. Used with the ``private_bytes`` method
|
|
available on
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization`
|
|
,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization`
|
|
and
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKeyWithSerialization`
|
|
as well as ``public_bytes`` on
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization`
|
|
and
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKeyWithSerialization`.
|
|
|
|
.. attribute:: PEM
|
|
|
|
.. versionadded:: 0.8
|
|
|
|
For PEM format. This is a base64 format with delimiters.
|
|
|
|
.. attribute:: DER
|
|
|
|
.. versionadded:: 0.9
|
|
|
|
For DER format. This is a binary format.
|
|
|
|
.. attribute:: OpenSSH
|
|
|
|
.. versionadded:: 1.4
|
|
|
|
The format used by OpenSSH public keys. This is a text format.
|
|
|
|
|
|
Serialization Encryption Types
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. class:: KeySerializationEncryption
|
|
|
|
Objects with this interface are usable as encryption types with methods
|
|
like ``private_bytes`` available on
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization`
|
|
,
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization`
|
|
and
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKeyWithSerialization`.
|
|
All other classes in this section represent the available choices for
|
|
encryption and have this interface. They are used with
|
|
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.private_bytes`.
|
|
|
|
.. class:: BestAvailableEncryption(password)
|
|
|
|
Encrypt using the best available encryption for a given key's backend.
|
|
This is a curated encryption choice and the algorithm may change over
|
|
time.
|
|
|
|
:param bytes password: The password to use for encryption.
|
|
|
|
.. class:: NoEncryption
|
|
|
|
Do not encrypt.
|