diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 37 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/padding.rst | 22 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 89 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 18 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/cmac.rst | 107 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/hmac.rst (renamed from docs/hazmat/primitives/hmac.rst) | 0 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/index.rst | 10 | ||||
| -rw-r--r-- | docs/hazmat/primitives/padding.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 4 |
11 files changed, 274 insertions, 19 deletions
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 394d060b..11ff9305 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -9,7 +9,7 @@ Backend interfaces 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/hmac`. +:doc:`/hazmat/primitives/mac/hmac`. A specific ``backend`` may provide one or more of these interfaces. @@ -263,8 +263,20 @@ 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:: decrypt_rsa(private_key, ciphertext, padding) -.. class:: OpenSSLSerializationBackend + :param private_key: An instance of an + :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` + provider. + + :param bytes ciphertext: The ciphertext to decrypt. + + :param padding: An instance of an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + +.. class:: TraditionalOpenSSLSerializationBackend .. versionadded:: 0.3 @@ -278,8 +290,8 @@ A specific ``backend`` may provide one or more of these interfaces. :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 - :class:`~cryptography.hazmat.primitives.serialization.OpenSSLPrivateKey` + :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. @@ -295,12 +307,12 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: generate_dsa_parameters(key_size) - :param int key_size: The length of the modulus in bits. It should be - either "1024, 2048 or 3072". For keys generated in 2014 this should + :param int key_size: The length of the modulus in bits. It should be + either 1024, 2048 or 3072. For keys generated in 2014 this should be at least 2048. - Note that some applications (such as SSH) have not yet gained support - for larger key sizes specified in FIPS 186-3 and are still restricted - to only the 1024-bit keys specified in FIPS 186-2. + Note that some applications (such as SSH) have not yet gained + support for larger key sizes specified in FIPS 186-3 and are still + restricted to only the 1024-bit keys specified in FIPS 186-2. :return: A new instance of a :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` @@ -316,9 +328,10 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey` provider. - :raises ValueError: This is raised if the key size is not (1024 or 2048 or 3072) - or if the OpenSSL version is older than 1.0.0 and the key size is larger than 1024 - because older OpenSSL versions don't support a key size larger than 1024. + :raises ValueError: This is raised if the key size is not one of 1024, + 2048, or 3072. It is also raised when OpenSSL is older than version + 1.0.0 and the key size is larger than 1024; older OpenSSL versions + do not support keys larger than 1024 bits. .. class:: CMACBackend diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index fdfadf0b..43e5d8f3 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -73,6 +73,6 @@ from the same pool as ``/dev/random``. .. _`OpenSSL`: https://www.openssl.org/ -.. _`initializing the RNG`: http://en.wikipedia.org/wiki/OpenSSL#Vulnerability_in_the_Debian_implementation +.. _`initializing the RNG`: https://en.wikipedia.org/wiki/OpenSSL#Predictable_keys_.28Debian-specific.29 .. _`Yarrow`: http://en.wikipedia.org/wiki/Yarrow_algorithm .. _`Microsoft documentation`: http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 89af7eaa..40084799 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -19,7 +19,8 @@ Padding PSS (Probabilistic Signature Scheme) is a signature scheme defined in :rfc:`3447`. It is more complex than PKCS1 but possesses a `security proof`_. - This is the `recommended padding algorithm`_ for RSA signatures. + This is the `recommended padding algorithm`_ for RSA signatures. It cannot + be used with RSA encryption. :param mgf: A mask generation function object. At this time the only supported MGF is :class:`MGF1`. @@ -32,12 +33,28 @@ Padding Pass this attribute to ``salt_length`` to get the maximum salt length available. +.. class:: OAEP(mgf, label) + + .. versionadded:: 0.4 + + OAEP (Optimal Asymmetric Encryption Padding) is a padding scheme defined in + :rfc:`3447`. It provides probabilistic encryption and is `proven secure`_ + against several attack types. This is the `recommended padding algorithm`_ + for RSA encryption. It cannot be used with RSA signing. + + :param mgf: A mask generation function object. At this time the only + supported MGF is :class:`MGF1`. + + :param bytes label: A label to apply. This is a rarely used field and + should typically be set to ``None`` or ``b""``, which are equivalent. + .. class:: PKCS1v15() .. versionadded:: 0.3 PKCS1 v1.5 (also known as simply PKCS1) is a simple padding scheme - developed for use with RSA keys. It is defined in :rfc:`3447`. + developed for use with RSA keys. It is defined in :rfc:`3447`. This padding + can be used for signing and encryption. Mask generation functions ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -60,3 +77,4 @@ Mask generation functions .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ .. _`security proof`: http://eprint.iacr.org/2001/062.pdf .. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html +.. _`proven secure`: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 5074f1c5..862df635 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -116,6 +116,60 @@ RSA :raises ValueError: This is raised when the chosen hash algorithm is too large for the key size. + .. method:: decrypt(ciphertext, padding, backend) + + .. versionadded:: 0.4 + + Decrypt data that was encrypted with the public key. + + :param bytes ciphertext: The ciphertext to decrypt. + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :return bytes: Decrypted data. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` or if + the backend does not support the chosen hash or padding algorithm. + If the padding is + :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` + with the + :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` + mask generation function it may also refer to the ``MGF1`` hash + algorithm. + + :raises TypeError: This is raised when the padding is not an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :raises ValueError: This is raised when decryption fails or the data + is too large for the key size. If the padding is + :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` + it may also be raised for invalid label values. + + .. code-block:: python + + from cryptography.hazmat.backends import default_backend + from cryptography.hazmat.primitives import hashes + from cryptography.hazmat.primitives.asymmetric import padding + + plaintext = private_key.decrypt( + ciphertext, + padding.OAEP( + mgf=padding.MGF1(algorithm=hashes.SHA1()), + algorithm=hashes.SHA1(), + label=None + ), + default_backend() + ) + .. class:: RSAPublicKey(public_exponent, modulus) @@ -214,7 +268,42 @@ RSA too large for the key size. +Handling partial RSA private keys +--------------------------------- + +If you are trying to load RSA private keys yourself you may find that not all +parameters required by ``RSAPrivateKey`` are available. In particular the +`Chinese Remainder Theorem`_ (CRT) values ``dmp1``, ``dmq1``, ``iqmp`` may be +missing or present in a different form. For example `OpenPGP`_ does not include +the ``iqmp``, ``dmp1`` or ``dmq1`` parameters. + +The following functions are provided for users who want to work with keys like +this without having to do the math themselves. + +.. function:: rsa_crt_iqmp(p, q) + + .. versionadded:: 0.4 + + Generates the ``iqmp`` (also known as ``qInv``) parameter from the RSA + primes ``p`` and ``q``. + +.. function:: rsa_crt_dmp1(private_exponent, p) + + .. versionadded:: 0.4 + + Generates the ``dmp1`` parameter from the RSA private exponent and prime + ``p``. + +.. function:: rsa_crt_dmq1(private_exponent, q) + + .. versionadded:: 0.4 + + Generates the ``dmq1`` parameter from the RSA private exponent and prime + ``q``. + .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography .. _`use 65537`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html .. _`at least 2048`: http://www.ecrypt.eu.org/documents/D.SPA.20.pdf +.. _`OpenPGP`: https://en.wikipedia.org/wiki/Pretty_Good_Privacy +.. _`Chinese Remainder Theorem`: http://en.wikipedia.org/wiki/RSA_%28cryptosystem%29#Using_the_Chinese_remainder_algorithm diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 90deec8b..a9ab38a0 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -7,7 +7,7 @@ Primitives :maxdepth: 1 cryptographic-hashes - hmac + mac/index symmetric-encryption padding key-derivation-functions diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 95fd6f9f..3b837a0d 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -133,6 +133,24 @@ Asymmetric interfaces :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + .. method:: decrypt(ciphertext, padding, backend) + + .. versionadded:: 0.4 + + Decrypt data that was encrypted via the public key. + + :param bytes ciphertext: The ciphertext to decrypt. + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :return bytes: Decrypted data. + .. method:: public_key() :return: :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst new file mode 100644 index 00000000..a6b048b5 --- /dev/null +++ b/docs/hazmat/primitives/mac/cmac.rst @@ -0,0 +1,107 @@ +.. hazmat:: + +Cipher-based message authentication code +======================================== + +.. currentmodule:: cryptography.hazmat.primitives.cmac + +.. testsetup:: + + import binascii + key = binascii.unhexlify(b"0" * 32) + +`Cipher-based message authentication codes`_ (or CMACs) are a tool for calculating +message authentication codes using a block cipher coupled with a +secret key. You can use an CMAC to verify both the integrity and authenticity +of a message. + +A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. + +.. class:: CMAC(algorithm, backend) + + .. versionadded:: 0.4 + + CMAC objects take a + :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` provider. + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import cmac + >>> from cryptography.hazmat.primitives.ciphers import algorithms + >>> c = cmac.CMAC(algorithms.AES(key), backend=default_backend()) + >>> c.update(b"message to authenticate") + >>> c.finalize() + 'CT\x1d\xc8\x0e\x15\xbe4e\xdb\xb6\x84\xca\xd9Xk' + + If the backend doesn't support the requested ``algorithm`` an + :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be + raised. + + If the `algorithm`` isn't a + :class:`~cryptography.primitives.interfaces.BlockCipherAlgorithm` provider, + ``TypeError`` will be raised. + + To check that a given signature is correct use the :meth:`verify` method. + You will receive an exception if the signature is wrong: + + .. code-block:: pycon + + >>> c.verify(b"an incorrect signature") + Traceback (most recent call last): + ... + cryptography.exceptions.InvalidSignature: Signature did not match digest. + + :param algorithm: An + :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + provider. + :param backend: An + :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` + provider. + :raises TypeError: This is raised if the provided ``algorithm`` is not an instance of + :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` + + .. method:: update(data) + + :param bytes data: The bytes to hash and authenticate. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + + .. method:: copy() + + Copy this :class:`CMAC` instance, usually so that we may call + :meth:`finalize` to get an intermediate value while we continue + to call :meth:`update` on the original instance. + + :return: A new instance of :class:`CMAC` that can be updated + and finalized independently of the original instance. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + + .. method:: verify(signature) + + Finalize the current context and securely compare the MAC to + ``signature``. + + :param bytes signature: The bytes to compare the current CMAC + against. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises cryptography.exceptions.InvalidSignature: If signature does not + match digest + + .. method:: finalize() + + Finalize the current context and return the message authentication code + as bytes. + + After ``finalize`` has been called this object can no longer be used + and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize` + will raise an :class:`~cryptography.exceptions.AlreadyFinalized` + exception. + + :return bytes: The message authentication code as bytes. + :raises cryptography.exceptions.AlreadyFinalized: + + +.. _`Cipher-based message authentication codes`: https://en.wikipedia.org/wiki/CMAC diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst index 11b10735..11b10735 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/mac/hmac.rst diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst new file mode 100644 index 00000000..59fb8da2 --- /dev/null +++ b/docs/hazmat/primitives/mac/index.rst @@ -0,0 +1,10 @@ +.. hazmat:: + +Message Authentication Codes +============================ + +.. toctree:: + :maxdepth: 1 + + cmac + hmac diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index d23f31bb..3056eb92 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -5,7 +5,7 @@ Padding .. currentmodule:: cryptography.hazmat.primitives.padding -Padding is a way to take data that may or may not be be a multiple of the block +Padding is a way to take data that may or may not be a multiple of the block size for a cipher and extend it out so that it is. This is required for many block cipher modes as they require the data to be encrypted to be an exact multiple of the block size. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 1a4df222..c2692ae2 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -21,7 +21,7 @@ message but an attacker can create bogus messages and force the application to decrypt them. For this reason it is *strongly* recommended to combine encryption with a -message authentication code, such as :doc:`HMAC </hazmat/primitives/hmac>`, in +message authentication code, such as :doc:`HMAC </hazmat/primitives/mac/hmac>`, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. class:: Cipher(algorithm, mode, backend) @@ -289,7 +289,7 @@ Modes block cipher mode that simultaneously encrypts the message as well as authenticating it. Additional unencrypted data may also be authenticated. Additional means of verifying integrity such as - :doc:`HMAC </hazmat/primitives/hmac>` are not necessary. + :doc:`HMAC </hazmat/primitives/mac/hmac>` are not necessary. **This mode does not require padding.** |