From 194eef0604991ea75fd1150314db756b07be3203 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Thu, 22 May 2014 22:30:19 +0100 Subject: PKCS#8 serialized key loading --- .../hazmat/primitives/asymmetric/serialization.rst | 55 ++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 8d32ae58..ac3080c8 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -46,3 +98,6 @@ header that mentions the type of the serialized key. e.g. :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. + + +.. _`X.501`: en.wikipedia.org/wiki/X.500 -- cgit v1.2.3 From 2784b4c069df4861db4c3ac24413699e517f1ccb Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Fri, 23 May 2014 21:47:52 +0100 Subject: Removed unused doc reference --- docs/hazmat/primitives/asymmetric/serialization.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index ac3080c8..2b3eb511 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -98,6 +98,3 @@ header that mentions the type of the serialized key. e.g. :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. - - -.. _`X.501`: en.wikipedia.org/wiki/X.500 -- cgit v1.2.3