diff options
Diffstat (limited to 'docs/hazmat/primitives/asymmetric')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 68 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/padding.rst | 36 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 72 |
4 files changed, 175 insertions, 4 deletions
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst new file mode 100644 index 00000000..69e8d58e --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -0,0 +1,68 @@ +.. hazmat:: + +DSA +=== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.dsa + +`DSA`_ is a `public-key`_ algorithm for signing messages. + +.. class:: DSAParameters(modulus, subgroup_order, generator) + + .. versionadded:: 0.4 + + DSA Parameters are required for generating a DSA private key. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``, or ``generator`` do + not match the bounds specified in `FIPS 186-4`_. + + +.. class:: DSAPrivateKey(modulus, subgroup_order, generator, x, y) + + .. versionadded:: 0.4 + + A DSA private key is required for signing messages. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``, or ``generator`` do + not match the bounds specified in `FIPS 186-4`_. + + +.. class:: DSAPublicKey(modulus, subgroup_order, generator, y) + + .. versionadded:: 0.4 + + A DSA public key is required for verifying messages. + + Normally you do not need to directly construct public keys because you'll + be loading them from a file, generating them automatically or receiving + them from a 3rd party. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``,``generator``, or ``y`` + do not match the bounds specified in `FIPS 186-4`_. + + +.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm +.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography +.. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf + diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 10319fad..ca048d11 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -1,10 +1,11 @@ .. hazmat:: -Asymmetric Algorithms +Asymmetric algorithms ===================== .. toctree:: :maxdepth: 1 + dsa rsa padding diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 7aec3bd3..2a5de3c7 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -10,6 +10,17 @@ Padding correct padding signatures can be forged, messages decrypted, and private keys compromised. +.. class:: PSS(mgf) + + .. versionadded:: 0.3 + + 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. + + :param mgf: A mask generation function object. At this time the only + supported MGF is :class:`MGF1`. + .. class:: PKCS1v15() .. versionadded:: 0.3 @@ -17,4 +28,29 @@ Padding 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`. +Mask generation functions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: MGF1(algorithm, salt_length) + + .. versionadded:: 0.3 + + MGF1 (Mask Generation Function 1) is used as the mask generation function + in :class:`PSS` padding. It takes a hash algorithm and a salt length. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param int salt_length: The length of the salt. It is recommended that this + be set to ``MGF1.MAX_LENGTH``. + + .. attribute:: MAX_LENGTH + + Pass this attribute to ``salt_length`` to get the maximum salt length + available. + + .. _`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 diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 7943981e..182e35d2 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -50,6 +50,11 @@ RSA provider. :return: A new instance of ``RSAPrivateKey``. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + + .. method:: signer(padding, algorithm, backend) .. versionadded:: 0.3 @@ -67,7 +72,12 @@ RSA ... backend=default_backend() ... ) >>> signer = private_key.signer( - ... padding.PKCS1v15(), + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), ... hashes.SHA256(), ... default_backend() ... ) @@ -90,6 +100,24 @@ RSA :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + :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.PSS` + 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 the chosen hash algorithm is + too large for the key size. + .. class:: RSAPublicKey(public_exponent, modulus) @@ -128,12 +156,31 @@ RSA ... key_size=2048, ... backend=default_backend() ... ) - >>> signer = private_key.signer(padding.PKCS1v15(), hashes.SHA256(), default_backend()) + >>> signer = private_key.signer( + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), + ... hashes.SHA256(), + ... default_backend() + ... ) >>> data= b"this is some data I'd like to sign" >>> signer.update(data) >>> signature = signer.finalize() >>> public_key = private_key.public_key() - >>> verifier = public_key.verifier(signature, padding.PKCS1v15(), hashes.SHA256(), default_backend()) + >>> verifier = public_key.verifier( + ... signature, + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), + ... hashes.SHA256(), + ... default_backend() + ... ) >>> verifier.update(data) >>> verifier.verify() @@ -154,6 +201,25 @@ RSA :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + :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.PSS` + 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 the chosen hash algorithm is + too large for the key size. + + .. _`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 |