diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 20 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/serialization.rst | 52 |
2 files changed, 72 insertions, 0 deletions
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index ff389cb5..78a35cd9 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -263,6 +263,26 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: ``True`` if the specified ``algorithm`` is supported by this backend, otherwise ``False``. + .. method:: rsa_padding_supported(padding) + + Check if the specified ``padding`` is supported by the backend. + + :param padding: An instance of an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :returns: ``True`` if the specified ``padding`` is supported by this + backend, otherwise ``False``. + + .. method:: generate_rsa_parameters_supported(public_exponent, key_size) + + Check if the specified parameters are supported for key generation by + the backend. + + :param int public_exponent: The public exponent. + + :param int key_size: The bit length of the generated modulus. + .. method:: decrypt_rsa(private_key, ciphertext, padding) :param private_key: An instance of an diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 8d32ae58..2b3eb511 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -9,6 +9,58 @@ 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 an instance of the appropriate type. You should check that +the returned key matches the type your application expects when using these +methods. + + .. code-block:: pycon + + >>> key = load_pkcs8_private_key(pem_data, None, 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 + + +PKCS #8 Format +~~~~~~~~~~~~~~ + +PKCS #8 is a serialization format originally standardized by RSA and +currently maintained by the IETF in :rfc:`5208`. It supports password based +encryption and additional key metadata attributes. + + +.. function:: load_pkcs8_private_key(data, password, backend) + + .. versionadded:: 0.5 + + 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: A + :class:`~cryptography.hazmat.backends.interfaces.PKCS8SerializationBackend` + provider. + + :returns: A new instance of a private key. + + :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 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. + Traditional OpenSSL Format ~~~~~~~~~~~~~~~~~~~~~~~~~~ |