diff options
Diffstat (limited to 'docs/hazmat/backends')
| -rw-r--r-- | docs/hazmat/backends/commoncrypto.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 160 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 14 |
3 files changed, 169 insertions, 9 deletions
diff --git a/docs/hazmat/backends/commoncrypto.rst b/docs/hazmat/backends/commoncrypto.rst index 77d6612c..ddaf97e5 100644 --- a/docs/hazmat/backends/commoncrypto.rst +++ b/docs/hazmat/backends/commoncrypto.rst @@ -3,8 +3,8 @@ CommonCrypto backend ==================== -The `CommonCrypto`_ C library provided by Apple on OS X and iOS. The CommonCrypto -backend is only supported on OS X versions 10.8 and above. +The `CommonCrypto`_ C library provided by Apple on OS X and iOS. The +CommonCrypto backend is only supported on OS X versions 10.8 and above. .. currentmodule:: cryptography.hazmat.backends.commoncrypto.backend diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 2f63f3e0..c1ce621a 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -6,8 +6,8 @@ Backend interfaces .. currentmodule:: cryptography.hazmat.backends.interfaces -Backend implementations may provide a number of interfaces to support operations -such as :doc:`/hazmat/primitives/symmetric-encryption`, +Backend implementations may provide a number of interfaces to support +operations such as :doc:`/hazmat/primitives/symmetric-encryption`, :doc:`/hazmat/primitives/cryptographic-hashes`, and :doc:`/hazmat/primitives/mac/hmac`. @@ -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 @@ -275,6 +295,14 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. + :return bytes: The decrypted data. + + :raises cryptography.exceptions.UnsupportedAlgorithm: If an unsupported + MGF, hash function, or padding is chosen. + + :raises ValueError: When decryption fails or key size does not match + ciphertext length. + .. method:: encrypt_rsa(public_key, plaintext, padding) :param public_key: An instance of an @@ -287,6 +315,12 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. + :return bytes: The encrypted data. + + :raises cryptography.exceptions.UnsupportedAlgorithm: If an unsupported + MGF, hash function, or padding is chosen. + + :raises ValueError: When plaintext is too long for the key size. .. class:: TraditionalOpenSSLSerializationBackend @@ -345,6 +379,55 @@ A specific ``backend`` may provide one or more of these interfaces. 1.0.0 and the key size is larger than 1024; older OpenSSL versions do not support keys larger than 1024 bits. + .. method:: create_dsa_signature_ctx(private_key, algorithm) + + :param private_key: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + + .. method:: create_dsa_verification_ctx(public_key, signature, algorithm) + + :param public_key: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` + provider. + + :param bytes signature: The signature to verify. DER encoded as + specified in :rfc:`6979`. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + + .. method:: dsa_hash_supported(algorithm): + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: ``True`` if the specified ``algorithm`` is supported by this + backend, otherwise ``False``. + + .. method:: dsa_parameters_supported(p, q, g): + + :param int p: The p value of a DSA key. + + :param int q: The q value of a DSA key. + + :param int g: The g value of a DSA key. + + :returns: ``True`` if the given values of ``p``, ``q``, and ``g`` are + supported by this backend, otherwise ``False``. + .. class:: CMACBackend @@ -371,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 43e5d8f3..e829798a 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -14,10 +14,14 @@ Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are It implements the following interfaces: * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + * :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` + * :class:`~cryptography.hazmat.backends.interfaces.DSABackend` * :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: @@ -44,9 +48,9 @@ where two different processes can return similar or identical keys and compromise the security of the system. The approach this project has chosen to mitigate this vulnerability is to -include an engine that replaces the OpenSSL default CSPRNG with one that sources -its entropy from ``/dev/urandom`` on UNIX-like operating systems and uses -``CryptGenRandom`` on Windows. This method of pulling from the system pool +include an engine that replaces the OpenSSL default CSPRNG with one that +sources its entropy from ``/dev/urandom`` on UNIX-like operating systems and +uses ``CryptGenRandom`` on Windows. This method of pulling from the system pool allows us to avoid potential issues with `initializing the RNG`_ as well as protecting us from the ``fork()`` weakness. @@ -68,8 +72,8 @@ On Windows the implementation of ``CryptGenRandom`` depends on which version of the operation system you are using. See the `Microsoft documentation`_ for more details. -Linux uses its own PRNG design. ``/dev/urandom`` is a non-blocking source seeded -from the same pool as ``/dev/random``. +Linux uses its own PRNG design. ``/dev/urandom`` is a non-blocking source +seeded from the same pool as ``/dev/random``. .. _`OpenSSL`: https://www.openssl.org/ |