diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 76 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/serialization.rst | 66 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 2 |
3 files changed, 143 insertions, 1 deletions
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index fd97d75b..924696db 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -80,6 +80,39 @@ password. If the key is encrypted we can pass a ``bytes`` object as the There is also support for :func:`loading public keys in the SSH format <cryptography.hazmat.primitives.serialization.load_ssh_public_key>`. +Key serialization +~~~~~~~~~~~~~~~~~ + +If you have a key that you've loaded or generated which implements the +:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization` +interface you can use +:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.private_bytes` +to serialize the key. + +.. doctest:: + + >>> from cryptography.hazmat.primitives import serialization + >>> pem = private_key.private_bytes( + ... encoding=serialization.Encoding.PEM, + ... format=serialization.Format.PKCS8, + ... encryption_algorithm=serialization.BestAvailableEncryption(b'mypassword') + ... ) + >>> pem.splitlines()[0] + '-----BEGIN ENCRYPTED PRIVATE KEY-----' + +It is also possible to serialize without encryption using +:class:`~cryptography.hazmat.primitives.serialization.NoEncryption`. + +.. doctest:: + + >>> pem = private_key.private_bytes( + ... encoding=serialization.Encoding.PEM, + ... format=serialization.Format.TraditionalOpenSSL, + ... encryption_algorithm=serialization.NoEncryption() + ... ) + >>> pem.splitlines()[0] + '-----BEGIN RSA PRIVATE KEY-----' + Signing ~~~~~~~ @@ -485,6 +518,49 @@ Key interfaces instance. +.. class:: RSAPrivateKeyWithSerialization + + .. versionadded:: 0.8 + + Extends :class:`RSAPrivateKey`. + + .. method:: private_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers` + object. + + :returns: An + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers` + instance. + + .. method:: private_bytes(encoding, format, encryption_algorithm) + + Allows serialization of the key to bytes. Encoding ( + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`), + format ( + :attr:`~cryptography.hazmat.primitives.serialization.Format.TraditionalOpenSSL` + or + :attr:`~cryptography.hazmat.primitives.serialization.Format.PKCS8`) and + encryption algorithm (such as + :class:`~cryptography.hazmat.primitives.serialization.BestAvailableEncryption` + or :class:`~cryptography.hazmat.primitives.serialization.NoEncryption`) + are chosen to define the exact serialization. + + :param encoding: A value from the + :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum. + + :param format: A value from the + :class:`~cryptography.hazmat.primitives.serialization.Format` enum. + + :param encryption_algorithm: An instance of an object conforming to the + :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption` + interface. + + :return bytes: Serialized key. + + .. class:: RSAPublicKey .. versionadded:: 0.2 diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 87f3c0b0..4940ebd4 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -3,7 +3,7 @@ Key Serialization ================= -.. currentmodule:: cryptography.hazmat.primitives.serialization +.. module:: cryptography.hazmat.primitives.serialization .. testsetup:: @@ -282,3 +282,67 @@ DSA keys look almost identical but begin with ``ssh-dss`` rather than :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key is of a type that is not supported. + +Serialization Formats +~~~~~~~~~~~~~~~~~~~~~ + +.. class:: Format + + .. versionadded:: 0.8 + + An enumeration for key formats. Used with + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.private_bytes`. + + .. 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. + +Serialization Encodings +~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: Encoding + + .. versionadded:: 0.8 + + An enumeration for encoding types. Used with + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.private_bytes`. + + .. attribute:: PEM + + For PEM format. This is a base64 format with delimiters. + + .. attribute:: DER + + For DER format. This is a binary format. + + +Serialization Encryption Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: KeySerializationEncryption + + Objects with this interface are usable as encryption types with methods + like + :meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.private_bytes`. + 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. diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 9434a0b7..81310d2d 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -45,6 +45,8 @@ pseudorandom pyOpenSSL Schneier scrypt +Serializers +serializer Solaris Tanja testability |