diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 73 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 51 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/serialization.rst | 52 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 93 |
6 files changed, 272 insertions, 0 deletions
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 78a35cd9..c1ce621a 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -454,3 +454,76 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.CMACContext` + + +.. class:: PKCS8SerializationBackend + + .. versionadded:: 0.5 + + A backend with methods for working with PKCS #8 key serialization. + + .. method:: load_pkcs8_pem_private_key(data, password) + + :param bytes data: PEM data to deserialize. + + :param bytes password: The password to use if this data is encrypted. + Should be None if the data is not encrypted. + + :return: A new instance of the appropriate private key or public key + that the serialized data contains. + + :raises ValueError: If the data could not be deserialized correctly. + + :raises cryptography.exceptions.UnsupportedAlgorithm: If the data is + encrypted with an unsupported algorithm. + + +.. class:: EllipticCurveBackend + + .. versionadded:: 0.5 + + .. method:: elliptic_curve_supported(curve) + + :param curve: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve` + provider. + + :returns: True if the elliptic curve is supported by this backend. + + .. method:: elliptic_curve_signature_algorithm_supported(signature_algorithm, curve) + + :param signature_algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm` + provider. + + :param curve: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve` + provider. + + :returns: True if the signature algorithm and curve are supported by this backend. + + .. method:: generate_elliptic_curve_private_key(curve) + + :param curve: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve` + provider. + + .. method:: elliptic_curve_private_key_from_numbers(numbers) + + :param numbers: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePrivateNumbers` + provider. + + :returns: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePrivateKey` + provider. + + .. method:: elliptic_curve_public_key_from_numbers(numbers) + + :param numbers: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicNumbers` + provider. + + :returns: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey` + provider. diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 6ad0d045..e829798a 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -19,7 +19,9 @@ Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are * :class:`~cryptography.hazmat.backends.interfaces.HashBackend` * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` + * :class:`~cryptography.hazmat.backends.interfaces.PKCS8SerializationBackend` * :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + * :class:`~cryptography.hazmat.backends.interfaces.TraditionalOpenSSLSerializationBackend` It also exposes the following: diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst new file mode 100644 index 00000000..f88b965a --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -0,0 +1,51 @@ +.. hazmat:: + +Elliptic Curve +============== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.ec + + +.. class:: EllipticCurvePrivateNumbers(private_value, public_numbers) + + .. versionadded:: 0.5 + + The collection of integers that make up an EC private key. + + .. attribute:: public_numbers + + :type: :class:`~cryptography.hazmat.primitives.ec.EllipticCurvePublicNumbers` + + The :class:`EllipticCurvePublicNumbers` which makes up the EC public + key associated with this EC private key. + + .. attribute:: private_value + + :type: int + + The private value. + + +.. class:: EllipticCurvePublicNumbers(x, y, curve) + + .. versionadded:: 0.5 + + The collection of integers that make up an EC public key. + + .. attribute:: curve + + :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve` + + The elliptic curve for this key. + + .. attribute:: x + + :type: int + + The affine x component of the public point used for verifying. + + .. attribute:: y + + :type: int + + The affine y component of the public point used for verifying. diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 047f9cb9..6a5228ba 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -7,6 +7,7 @@ Asymmetric algorithms :maxdepth: 1 dsa + ec rsa padding serialization 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index dc09a26f..b2857f58 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -463,6 +463,97 @@ Asymmetric interfaces :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` +.. class:: EllipticCurve + + .. versionadded:: 0.5 + + A named elliptic curve. + + .. attribute:: name + + :type: string + + The name of the curve. Usually the name used for the ASN.1 OID such as + ``secp256k1``. + + .. attribute:: key_size + + :type: int + + The bit length of the curve's base point. + + +.. class:: EllipticCurveSignatureAlgorithm + + .. versionadded:: 0.5 + + A signature algorithm for use with elliptic curve keys. + + .. attribute:: algorithm + + :type: :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + + The digest algorithm to be used with the signature scheme. + + +.. class:: EllipticCurvePrivateKey + + .. versionadded:: 0.5 + + An elliptic curve private key for use with an algorithm such as `ECDSA`_ or + `EdDSA`_. + + .. classmethod:: signer(signature_algorithm) + + Sign data which can be verified later by others using the public key. + + :param signature_algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + + .. attribute:: curve + + :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve` + + The elliptic curve for this key. + + .. method:: public_key() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey` + + The EllipticCurvePublicKey object for this private key. + + +.. class:: EllipticCurvePublicKey + + .. versionadded:: 0.5 + + An elliptic curve public key. + + .. classmethod:: verifier(signer, signature_algorithm) + + Verify data was signed by the private key associated with this public + key. + + :param bytes signature: The signature to verify. + + :param signature_algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + + .. attribute:: curve + + :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve` + + The elliptic curve for this key. + + .. class:: AsymmetricSignatureContext .. versionadded:: 0.2 @@ -612,3 +703,5 @@ Key derivation functions .. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem .. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm .. _`CMAC`: https://en.wikipedia.org/wiki/CMAC +.. _`ECDSA`: http://en.wikipedia.org/wiki/ECDSA +.. _`EdDSA`: http://en.wikipedia.org/wiki/EdDSA |