From 87bc4045b44c515b61b45c2d51c2e38fd1bf43e9 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 17 Feb 2014 11:34:26 -0800 Subject: Fixed some sphinx linkification issues --- docs/hazmat/primitives/rsa.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/rsa.rst b/docs/hazmat/primitives/rsa.rst index e7ec4749..4e1f8e49 100644 --- a/docs/hazmat/primitives/rsa.rst +++ b/docs/hazmat/primitives/rsa.rst @@ -7,16 +7,13 @@ RSA `RSA`_ is a `public-key`_ algorithm for encrypting and signing messages. -.. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, - public_exponent, modulus) +.. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, public_exponent, modulus) .. versionadded:: 0.2 An RSA private key is required for decryption and signing of messages. - You should use - :meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey.generate` - to generate new keys. + You should use :meth:`~generate` to generate new keys. .. warning:: This method only checks a limited set of properties of its arguments. @@ -53,6 +50,7 @@ RSA provider. :return: A new instance of ``RSAPrivateKey``. + .. class:: RSAPublicKey(public_exponent, modulus) .. versionadded:: 0.2 -- cgit v1.2.3 From 2b3f0fc4d6641d040056466adc6dca7cfc75d3d5 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 17 Feb 2014 19:20:14 -0600 Subject: add docs for sign/verify ctx creation interface --- docs/hazmat/backends/interfaces.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index e6bf8f69..72b64910 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -212,3 +212,39 @@ A specific ``backend`` may provide one or more of these interfaces. provider. :raises ValueError: If the public_exponent is not valid. + + .. method:: create_rsa_sign_ctx(private_key, padding, algorithm) + + :param private_key: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` + provider. + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignContext` + + .. method:: create_rsa_verify_ctx(public_key, signature, padding, algorithm) + + :param public_key: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` + provider. + + :param bytes signature: The signature to verify. + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerifyContext` -- cgit v1.2.3 From e0f0f34c0c86f1fb729404bb87d637de9a4795ce Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 17 Feb 2014 19:20:51 -0600 Subject: + docs for AsymmetricSignContext, AsymmetricVerifyContext, AsymmetricPadding --- docs/hazmat/primitives/interfaces.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index df17e59d..c0ddd79c 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -231,6 +231,39 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +.. class:: AsymmetricSignContext + + .. versionadded:: 0.2 + + .. method:: update(data) + + :param bytes data: The data you wish to pass into the context. + + .. method:: finalize() + + :return bytes signature: The signature. + + +.. class:: AsymmetricVerifyContext + + .. versionadded:: 0.2 + + .. method:: update(data) + + :param bytes data: The data you wish to pass into the context. + + .. method:: finalize() + + :raises cryptography.exceptions.InvalidSignature: If signature does not + validate. + + +.. class:: AsymmetricPadding + + A named asymmetric padding. + + .. attribute:: name + Hash Algorithms ~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 19f32d5502ec938047d3d46dc440d8fe9481caa8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 17 Feb 2014 19:23:06 -0600 Subject: add versionadded to AsymmetricPadding --- docs/hazmat/primitives/interfaces.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index c0ddd79c..e4ae3e93 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -260,7 +260,7 @@ Asymmetric Interfaces .. class:: AsymmetricPadding - A named asymmetric padding. + .. versionadded:: 0.2 .. attribute:: name -- cgit v1.2.3 From 3292c994ba0516c59cc3e003f910a9f3c2bc0c54 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 17 Feb 2014 21:12:38 -0600 Subject: create_rsa_sign_ctx->create_rsa_signature_ctx --- docs/hazmat/backends/interfaces.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 72b64910..1879336f 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -213,7 +213,7 @@ A specific ``backend`` may provide one or more of these interfaces. :raises ValueError: If the public_exponent is not valid. - .. method:: create_rsa_sign_ctx(private_key, padding, algorithm) + .. method:: create_rsa_signature_ctx(private_key, padding, algorithm) :param private_key: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` -- cgit v1.2.3 From eda558ce9ffca610ee628884041832da4afb7645 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 17 Feb 2014 21:18:13 -0600 Subject: more renaming --- docs/hazmat/primitives/interfaces.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index e4ae3e93..e97f40f4 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -231,13 +231,13 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. -.. class:: AsymmetricSignContext +.. class:: AsymmetricSignatureContext .. versionadded:: 0.2 .. method:: update(data) - :param bytes data: The data you wish to pass into the context. + :param bytes data: The data you want to sign. .. method:: finalize() @@ -250,7 +250,7 @@ Asymmetric Interfaces .. method:: update(data) - :param bytes data: The data you wish to pass into the context. + :param bytes data: The data you wish to verify using the signature. .. method:: finalize() -- cgit v1.2.3 From dd3780a0e516b2c07e02f5b3afc02a79bfe44c6f Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 18 Feb 2014 13:17:53 -0600 Subject: some grammar fixes, rename a method or two --- docs/hazmat/backends/interfaces.rst | 10 +++++----- docs/hazmat/primitives/interfaces.rst | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 1879336f..c54340b6 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -215,11 +215,11 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_rsa_signature_ctx(private_key, padding, algorithm) - :param private_key: An instance of a + :param private_key: An instance of an :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` provider. - :param padding: An instance of a + :param padding: An instance of an :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. @@ -228,9 +228,9 @@ A specific ``backend`` may provide one or more of these interfaces. provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignContext` + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` - .. method:: create_rsa_verify_ctx(public_key, signature, padding, algorithm) + .. method:: create_rsa_verification_ctx(public_key, signature, padding, algorithm) :param public_key: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` @@ -238,7 +238,7 @@ A specific ``backend`` may provide one or more of these interfaces. :param bytes signature: The signature to verify. - :param padding: An instance of a + :param padding: An instance of an :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index e97f40f4..6fbc61b0 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -252,7 +252,7 @@ Asymmetric Interfaces :param bytes data: The data you wish to verify using the signature. - .. method:: finalize() + .. method:: verify() :raises cryptography.exceptions.InvalidSignature: If signature does not validate. -- cgit v1.2.3 From 430202dfba9a3c97abc80955752e5b9e4d430911 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 18 Feb 2014 13:36:53 -0600 Subject: let's try renaming everything I said I'd rename --- docs/hazmat/backends/interfaces.rst | 2 +- docs/hazmat/primitives/interfaces.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index c54340b6..bd38ed50 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -247,4 +247,4 @@ A specific ``backend`` may provide one or more of these interfaces. provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerifyContext` + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 6fbc61b0..5be3dd95 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -244,7 +244,7 @@ Asymmetric Interfaces :return bytes signature: The signature. -.. class:: AsymmetricVerifyContext +.. class:: AsymmetricVerificationContext .. versionadded:: 0.2 -- cgit v1.2.3 From 2fb76a3d39ae3ab189bb08336fc4eb42950771a6 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Sat, 15 Feb 2014 11:10:57 +0000 Subject: OpenSSL "traditional" key format loading... Backend interface only. --- docs/hazmat/backends/interfaces.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index bd38ed50..af19fbc6 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -248,3 +248,26 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + + +.. class:: OpenSSLSerializationBackend + + .. versionadded:: 0.3 + + A backend with methods for working with OpenSSL's "traditional" PKCS #1 + style key serialization. + + .. method:: load_openssl_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 + :class:`~cryptography.hazmat.primitives.serialization.OpenSSLPrivateKey` + + :raises ValueError: If the data could not be deserialized correctly. + + :raises cryptography.exceptions.UnsupportedAlgorithm: If the data is + encrypted with an unsupported algorithm. -- cgit v1.2.3 From 18ca44bfef0fe2908d9da3b3008941325d04a971 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Wed, 12 Feb 2014 18:38:28 +0800 Subject: Added documentation for HOTP implementation. --- docs/hazmat/oath/hotp.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/hazmat/oath/hotp.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/oath/hotp.rst b/docs/hazmat/oath/hotp.rst new file mode 100644 index 00000000..d84f5bdf --- /dev/null +++ b/docs/hazmat/oath/hotp.rst @@ -0,0 +1,46 @@ +.. hazmat:: + +HMAC-Based One-Time Password Algorithm +====================================== + +.. currentmodule:: cryptography.hazmat.oath.hotp + +This module contains functions for generating and verifying one time password +values based on Hash-based message authentication codes (HMAC). + +.. class:: HOTP(secret, length, backend) + + HOTP objects take a ``secret`` and ``length`` parameter. The ``secret`` + should be randomly generated bytes and is recommended to be 160 bits in + length. The ``length`` parameter controls the length of the generated + one time password and is recommended to be at least a 6 digit value. + + This is an implementation of :rfc:`4226`. + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.oath.hotp import HOTP + >>> hotp = HOTP(secret, 6, backend=default_backend) + >>> hotp.generate(0) + 958695 + >>> hotp.verify("958695", 0) + True + + :param secret: Secret key as ``bytes``. + :param length: Length of generated one time password as ``int``. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + provider. + + .. method:: generate(counter) + + :param counter: The counter value used to generate the one time password. + :return: A one time password value. + + .. method:: verify(hotp, counter) + + :param hotp: The one time password value to validate. + :param counter: The counter value to validate against. + :return: ``True`` if the one time password value is valid. ``False`` if otherwise. + -- cgit v1.2.3 From b2ee044298caf5772fb8774dc691add3afe8cdc1 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Wed, 12 Feb 2014 22:22:01 +0800 Subject: Minor changes for python3 compat and documentation changes --- docs/hazmat/oath/hotp.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/oath/hotp.rst b/docs/hazmat/oath/hotp.rst index d84f5bdf..614933f9 100644 --- a/docs/hazmat/oath/hotp.rst +++ b/docs/hazmat/oath/hotp.rst @@ -17,7 +17,7 @@ values based on Hash-based message authentication codes (HMAC). This is an implementation of :rfc:`4226`. - .. doctest:: + .. code-block:: python >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.oath.hotp import HOTP @@ -35,12 +35,11 @@ values based on Hash-based message authentication codes (HMAC). .. method:: generate(counter) - :param counter: The counter value used to generate the one time password. + :param int counter: The counter value used to generate the one time password. :return: A one time password value. .. method:: verify(hotp, counter) - :param hotp: The one time password value to validate. - :param counter: The counter value to validate against. + :param bytes hotp: The one time password value to validate. + :param bytes counter: The counter value to validate against. :return: ``True`` if the one time password value is valid. ``False`` if otherwise. - -- cgit v1.2.3 From a7769110ef8f575105847f84cadf6bb5b9aa5fba Mon Sep 17 00:00:00 2001 From: Ayrx Date: Thu, 13 Feb 2014 12:27:56 +0800 Subject: Updated according to code review feedback. --- docs/hazmat/oath/hotp.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/oath/hotp.rst b/docs/hazmat/oath/hotp.rst index 614933f9..1dee26b0 100644 --- a/docs/hazmat/oath/hotp.rst +++ b/docs/hazmat/oath/hotp.rst @@ -17,18 +17,20 @@ values based on Hash-based message authentication codes (HMAC). This is an implementation of :rfc:`4226`. - .. code-block:: python + .. doctest:: + >>> import os >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.oath.hotp import HOTP - >>> hotp = HOTP(secret, 6, backend=default_backend) + + >>> key = "12345678901234567890" + >>> hotp = HOTP(key, 6, backend=default_backend()) >>> hotp.generate(0) - 958695 - >>> hotp.verify("958695", 0) - True + '755224' + >>> hotp.verify("755224", 0) - :param secret: Secret key as ``bytes``. - :param length: Length of generated one time password as ``int``. + :param bytes secret: Secret key as ``bytes``. + :param int length: Length of generated one time password as ``int``. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. @@ -36,7 +38,7 @@ values based on Hash-based message authentication codes (HMAC). .. method:: generate(counter) :param int counter: The counter value used to generate the one time password. - :return: A one time password value. + :return bytes: A one time password value. .. method:: verify(hotp, counter) -- cgit v1.2.3 From 25b1d21b40f531450877bcfbee55406b28111dca Mon Sep 17 00:00:00 2001 From: Ayrx Date: Thu, 13 Feb 2014 15:30:20 +0800 Subject: Updated documentation. --- docs/hazmat/oath/hotp.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/oath/hotp.rst b/docs/hazmat/oath/hotp.rst index 1dee26b0..7aff330f 100644 --- a/docs/hazmat/oath/hotp.rst +++ b/docs/hazmat/oath/hotp.rst @@ -8,12 +8,12 @@ HMAC-Based One-Time Password Algorithm This module contains functions for generating and verifying one time password values based on Hash-based message authentication codes (HMAC). -.. class:: HOTP(secret, length, backend) +.. class:: HOTP(key, length, backend) - HOTP objects take a ``secret`` and ``length`` parameter. The ``secret`` + HOTP objects take a ``key`` and ``length`` parameter. The ``key`` should be randomly generated bytes and is recommended to be 160 bits in length. The ``length`` parameter controls the length of the generated - one time password and is recommended to be at least a 6 digit value. + one time password and must be >= 6. This is an implementation of :rfc:`4226`. @@ -23,17 +23,22 @@ values based on Hash-based message authentication codes (HMAC). >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.oath.hotp import HOTP - >>> key = "12345678901234567890" + >>> key = b"12345678901234567890" >>> hotp = HOTP(key, 6, backend=default_backend()) >>> hotp.generate(0) '755224' - >>> hotp.verify("755224", 0) + >>> hotp.verify(b"755224", 0) - :param bytes secret: Secret key as ``bytes``. + :param bytes key: Secret key as ``bytes``. This value must be generated in a + cryptographically secure fashion and be at least 128 bits. + It is recommended that the key be 160 bits. :param int length: Length of generated one time password as ``int``. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. + :raises ValueError: This is raised if the provided ``key`` or ``length`` + parameters are shorter than required. + .. method:: generate(counter) @@ -44,4 +49,5 @@ values based on Hash-based message authentication codes (HMAC). :param bytes hotp: The one time password value to validate. :param bytes counter: The counter value to validate against. - :return: ``True`` if the one time password value is valid. ``False`` if otherwise. + :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP + does not match the expected HOTP. -- cgit v1.2.3 From b5189afaf1dd1c06edd0efe3d6791ea7c40e31c7 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Thu, 13 Feb 2014 18:52:31 +0800 Subject: Added a max limit of 8 on length parameter. Updated documentation. --- docs/hazmat/oath.rst | 59 +++++++++++++++++++++++++++++++++++++++++++++++ docs/hazmat/oath/hotp.rst | 53 ------------------------------------------ 2 files changed, 59 insertions(+), 53 deletions(-) create mode 100644 docs/hazmat/oath.rst delete mode 100644 docs/hazmat/oath/hotp.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/oath.rst b/docs/hazmat/oath.rst new file mode 100644 index 00000000..b936f0e5 --- /dev/null +++ b/docs/hazmat/oath.rst @@ -0,0 +1,59 @@ +.. hazmat:: + +OATH +==== + +.. currentmodule:: cryptography.hazmat.oath + +This module contains algorithms under the umbrella of the +Initiative for Open Authentication (OATH). + +Currently, it contains an algorithm for generating and verifying +one time password values based on Hash-based message authentication +codes (HMAC). + +.. currentmodule:: cryptography.hazmat.oath.hotp + +.. class:: HOTP(key, length, backend) + + HOTP objects take a ``key`` and ``length`` parameter. The ``key`` + should be randomly generated bytes and is recommended to be 160 bits in + length. The ``length`` parameter controls the length of the generated + one time password and must be >= 6 and <= 8. + + This is an implementation of :rfc:`4226`. + + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.oath.hotp import HOTP + + >>> key = b"12345678901234567890" + >>> hotp = HOTP(key, 6, backend=default_backend()) + >>> hotp.generate(0) + '755224' + >>> hotp.verify(b"755224", 0) + + :param bytes key: Secret key as ``bytes``. This value must be generated in a + cryptographically secure fashion and be at least 128 bits. + It is recommended that the key be 160 bits. + :param int length: Length of generated one time password as ``int``. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + provider. + :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits + or if the ``length`` parameter is not between 6 to 8. + + + .. method:: generate(counter) + + :param int counter: The counter value used to generate the one time password. + :return bytes: A one time password value. + + .. method:: verify(hotp, counter) + + :param bytes hotp: The one time password value to validate. + :param bytes counter: The counter value to validate against. + :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP + does not match the expected HOTP. diff --git a/docs/hazmat/oath/hotp.rst b/docs/hazmat/oath/hotp.rst deleted file mode 100644 index 7aff330f..00000000 --- a/docs/hazmat/oath/hotp.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. hazmat:: - -HMAC-Based One-Time Password Algorithm -====================================== - -.. currentmodule:: cryptography.hazmat.oath.hotp - -This module contains functions for generating and verifying one time password -values based on Hash-based message authentication codes (HMAC). - -.. class:: HOTP(key, length, backend) - - HOTP objects take a ``key`` and ``length`` parameter. The ``key`` - should be randomly generated bytes and is recommended to be 160 bits in - length. The ``length`` parameter controls the length of the generated - one time password and must be >= 6. - - This is an implementation of :rfc:`4226`. - - .. doctest:: - - >>> import os - >>> from cryptography.hazmat.backends import default_backend - >>> from cryptography.hazmat.oath.hotp import HOTP - - >>> key = b"12345678901234567890" - >>> hotp = HOTP(key, 6, backend=default_backend()) - >>> hotp.generate(0) - '755224' - >>> hotp.verify(b"755224", 0) - - :param bytes key: Secret key as ``bytes``. This value must be generated in a - cryptographically secure fashion and be at least 128 bits. - It is recommended that the key be 160 bits. - :param int length: Length of generated one time password as ``int``. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` - provider. - :raises ValueError: This is raised if the provided ``key`` or ``length`` - parameters are shorter than required. - - - .. method:: generate(counter) - - :param int counter: The counter value used to generate the one time password. - :return bytes: A one time password value. - - .. method:: verify(hotp, counter) - - :param bytes hotp: The one time password value to validate. - :param bytes counter: The counter value to validate against. - :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP - does not match the expected HOTP. -- cgit v1.2.3 From ebadb6b293748786c45fb34685b25000be4df2e7 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Sat, 15 Feb 2014 20:32:07 +0800 Subject: Updated docs with notes on throttling and resynchronization. --- docs/hazmat/oath.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/oath.rst b/docs/hazmat/oath.rst index b936f0e5..91c23566 100644 --- a/docs/hazmat/oath.rst +++ b/docs/hazmat/oath.rst @@ -57,3 +57,39 @@ codes (HMAC). :param bytes counter: The counter value to validate against. :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP does not match the expected HOTP. + +Throttling +---------- + +Due to the fact that the HOTP algorithm generates rather short tokens that are 6 - 8 digits +long, brute force attacks are possible. It is highly recommended that the server that +validates the token implement a throttling scheme that locks out the account for a period of +time after a number of failed attempts. The number of allowed attempts should be as low as +possible while still ensuring that usability is not significantly impacted. + +Re-synchronization of the Counter +--------------------------------- + +The server's counter value should only be incremented on a successful HOTP authentication. +However, the counter on the client is incremented every time a new HOTP value is requested. +This can lead to the counter value being out of synchronization between the client and server. + +Due to this, it is highly recommended that the server sets a look-ahead window that allows the +server to calculate the next ``x`` HOTP values and check them against the supplied HOTP value. +This can be accomplished with something similar to the following code. + +.. code-block:: python + + def verify(hotp, counter, look_ahead): + assert look_ahead >= 0 + correct_counter = None + + otp = HOTP(key, 6, default_backend()) + for count in range(counter, counter+look_ahead): + try: + otp.verify(hotp, count) + correct_counter = count + except InvalidToken: + pass + + return correct_counter \ No newline at end of file -- cgit v1.2.3 From 26d276f2a9f7b1ca155cb7cced139b2d15baf272 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Mon, 17 Feb 2014 12:40:30 +0800 Subject: Updated documentation. --- docs/hazmat/oath.rst | 95 ---------------------------------------- docs/hazmat/primitives/index.rst | 1 + docs/hazmat/primitives/otp.rst | 95 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 96 insertions(+), 95 deletions(-) delete mode 100644 docs/hazmat/oath.rst create mode 100644 docs/hazmat/primitives/otp.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/oath.rst b/docs/hazmat/oath.rst deleted file mode 100644 index 91c23566..00000000 --- a/docs/hazmat/oath.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. hazmat:: - -OATH -==== - -.. currentmodule:: cryptography.hazmat.oath - -This module contains algorithms under the umbrella of the -Initiative for Open Authentication (OATH). - -Currently, it contains an algorithm for generating and verifying -one time password values based on Hash-based message authentication -codes (HMAC). - -.. currentmodule:: cryptography.hazmat.oath.hotp - -.. class:: HOTP(key, length, backend) - - HOTP objects take a ``key`` and ``length`` parameter. The ``key`` - should be randomly generated bytes and is recommended to be 160 bits in - length. The ``length`` parameter controls the length of the generated - one time password and must be >= 6 and <= 8. - - This is an implementation of :rfc:`4226`. - - .. doctest:: - - >>> import os - >>> from cryptography.hazmat.backends import default_backend - >>> from cryptography.hazmat.oath.hotp import HOTP - - >>> key = b"12345678901234567890" - >>> hotp = HOTP(key, 6, backend=default_backend()) - >>> hotp.generate(0) - '755224' - >>> hotp.verify(b"755224", 0) - - :param bytes key: Secret key as ``bytes``. This value must be generated in a - cryptographically secure fashion and be at least 128 bits. - It is recommended that the key be 160 bits. - :param int length: Length of generated one time password as ``int``. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` - provider. - :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits - or if the ``length`` parameter is not between 6 to 8. - - - .. method:: generate(counter) - - :param int counter: The counter value used to generate the one time password. - :return bytes: A one time password value. - - .. method:: verify(hotp, counter) - - :param bytes hotp: The one time password value to validate. - :param bytes counter: The counter value to validate against. - :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP - does not match the expected HOTP. - -Throttling ----------- - -Due to the fact that the HOTP algorithm generates rather short tokens that are 6 - 8 digits -long, brute force attacks are possible. It is highly recommended that the server that -validates the token implement a throttling scheme that locks out the account for a period of -time after a number of failed attempts. The number of allowed attempts should be as low as -possible while still ensuring that usability is not significantly impacted. - -Re-synchronization of the Counter ---------------------------------- - -The server's counter value should only be incremented on a successful HOTP authentication. -However, the counter on the client is incremented every time a new HOTP value is requested. -This can lead to the counter value being out of synchronization between the client and server. - -Due to this, it is highly recommended that the server sets a look-ahead window that allows the -server to calculate the next ``x`` HOTP values and check them against the supplied HOTP value. -This can be accomplished with something similar to the following code. - -.. code-block:: python - - def verify(hotp, counter, look_ahead): - assert look_ahead >= 0 - correct_counter = None - - otp = HOTP(key, 6, default_backend()) - for count in range(counter, counter+look_ahead): - try: - otp.verify(hotp, count) - correct_counter = count - except InvalidToken: - pass - - return correct_counter \ No newline at end of file diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 38ed24c9..9121d156 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -14,3 +14,4 @@ Primitives rsa constant-time interfaces + otp diff --git a/docs/hazmat/primitives/otp.rst b/docs/hazmat/primitives/otp.rst new file mode 100644 index 00000000..ad2c856a --- /dev/null +++ b/docs/hazmat/primitives/otp.rst @@ -0,0 +1,95 @@ +.. hazmat:: + +One Time Password +================= + +.. currentmodule:: cryptography.hazmat.primitives.otp + +This module contains algorithms for generating and verifying one +time passwords. + +Currently, it contains an algorithm for generating and verifying +one time password values based on Hash-based message authentication +codes (HMAC). + +.. currentmodule:: cryptography.hazmat.primitives.otp.hotp + +.. class:: HOTP(key, length, backend) + + HOTP objects take a ``key`` and ``length`` parameter. The ``key`` + should be randomly generated bytes and is recommended to be 160 bits in + length. The ``length`` parameter controls the length of the generated + one time password and must be >= 6 and <= 8. + + This is an implementation of :rfc:`4226`. + + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives.otp.hotp import HOTP + + >>> key = b"12345678901234567890" + >>> hotp = HOTP(key, 6, backend=default_backend()) + >>> hotp.generate(0) + '755224' + >>> hotp.verify(b"755224", 0) + + :param bytes key: Secret key as ``bytes``. This value must be generated in a + cryptographically secure fashion and be at least 128 bits. + It is recommended that the key be 160 bits. + :param int length: Length of generated one time password as ``int``. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + provider. + :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits + or if the ``length`` parameter is not between 6 to 8. + + + .. method:: generate(counter) + + :param int counter: The counter value used to generate the one time password. + :return bytes: A one time password value. + + .. method:: verify(hotp, counter) + + :param bytes hotp: The one time password value to validate. + :param bytes counter: The counter value to validate against. + :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP + does not match the expected HOTP. + +Throttling +---------- + +Due to the fact that the HOTP algorithm generates rather short tokens that are 6 - 8 digits +long, brute force attacks are possible. It is highly recommended that the server that +validates the token implement a throttling scheme that locks out the account for a period of +time after a number of failed attempts. The number of allowed attempts should be as low as +possible while still ensuring that usability is not significantly impacted. + +Re-synchronization of the Counter +--------------------------------- + +The server's counter value should only be incremented on a successful HOTP authentication. +However, the counter on the client is incremented every time a new HOTP value is requested. +This can lead to the counter value being out of synchronization between the client and server. + +Due to this, it is highly recommended that the server sets a look-ahead window that allows the +server to calculate the next ``x`` HOTP values and check them against the supplied HOTP value. +This can be accomplished with something similar to the following code. + +.. code-block:: python + + def verify(hotp, counter, look_ahead): + assert look_ahead >= 0 + correct_counter = None + + otp = HOTP(key, 6, default_backend()) + for count in range(counter, counter+look_ahead): + try: + otp.verify(hotp, count) + correct_counter = count + except InvalidToken: + pass + + return correct_counter \ No newline at end of file -- cgit v1.2.3 From 8c1ad596b02f89cde6040e8626e07ca352182130 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Tue, 18 Feb 2014 12:33:55 +0800 Subject: Changed module name from otp to twofactor. --- docs/hazmat/primitives/index.rst | 2 +- docs/hazmat/primitives/otp.rst | 95 ------------------------------------ docs/hazmat/primitives/twofactor.rst | 94 +++++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+), 96 deletions(-) delete mode 100644 docs/hazmat/primitives/otp.rst create mode 100644 docs/hazmat/primitives/twofactor.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 9121d156..5199d493 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -14,4 +14,4 @@ Primitives rsa constant-time interfaces - otp + twofactor diff --git a/docs/hazmat/primitives/otp.rst b/docs/hazmat/primitives/otp.rst deleted file mode 100644 index ad2c856a..00000000 --- a/docs/hazmat/primitives/otp.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. hazmat:: - -One Time Password -================= - -.. currentmodule:: cryptography.hazmat.primitives.otp - -This module contains algorithms for generating and verifying one -time passwords. - -Currently, it contains an algorithm for generating and verifying -one time password values based on Hash-based message authentication -codes (HMAC). - -.. currentmodule:: cryptography.hazmat.primitives.otp.hotp - -.. class:: HOTP(key, length, backend) - - HOTP objects take a ``key`` and ``length`` parameter. The ``key`` - should be randomly generated bytes and is recommended to be 160 bits in - length. The ``length`` parameter controls the length of the generated - one time password and must be >= 6 and <= 8. - - This is an implementation of :rfc:`4226`. - - .. doctest:: - - >>> import os - >>> from cryptography.hazmat.backends import default_backend - >>> from cryptography.hazmat.primitives.otp.hotp import HOTP - - >>> key = b"12345678901234567890" - >>> hotp = HOTP(key, 6, backend=default_backend()) - >>> hotp.generate(0) - '755224' - >>> hotp.verify(b"755224", 0) - - :param bytes key: Secret key as ``bytes``. This value must be generated in a - cryptographically secure fashion and be at least 128 bits. - It is recommended that the key be 160 bits. - :param int length: Length of generated one time password as ``int``. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` - provider. - :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits - or if the ``length`` parameter is not between 6 to 8. - - - .. method:: generate(counter) - - :param int counter: The counter value used to generate the one time password. - :return bytes: A one time password value. - - .. method:: verify(hotp, counter) - - :param bytes hotp: The one time password value to validate. - :param bytes counter: The counter value to validate against. - :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP - does not match the expected HOTP. - -Throttling ----------- - -Due to the fact that the HOTP algorithm generates rather short tokens that are 6 - 8 digits -long, brute force attacks are possible. It is highly recommended that the server that -validates the token implement a throttling scheme that locks out the account for a period of -time after a number of failed attempts. The number of allowed attempts should be as low as -possible while still ensuring that usability is not significantly impacted. - -Re-synchronization of the Counter ---------------------------------- - -The server's counter value should only be incremented on a successful HOTP authentication. -However, the counter on the client is incremented every time a new HOTP value is requested. -This can lead to the counter value being out of synchronization between the client and server. - -Due to this, it is highly recommended that the server sets a look-ahead window that allows the -server to calculate the next ``x`` HOTP values and check them against the supplied HOTP value. -This can be accomplished with something similar to the following code. - -.. code-block:: python - - def verify(hotp, counter, look_ahead): - assert look_ahead >= 0 - correct_counter = None - - otp = HOTP(key, 6, default_backend()) - for count in range(counter, counter+look_ahead): - try: - otp.verify(hotp, count) - correct_counter = count - except InvalidToken: - pass - - return correct_counter \ No newline at end of file diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst new file mode 100644 index 00000000..2b811e1e --- /dev/null +++ b/docs/hazmat/primitives/twofactor.rst @@ -0,0 +1,94 @@ +.. hazmat:: + +Two-factor Authentication +========================= + +.. currentmodule:: cryptography.hazmat.primitives.twofactor + +This module contains algorithms related to two-factor authentication. + +Currently, it contains an algorithm for generating and verifying +one time password values based on Hash-based message authentication +codes (HMAC). + +.. currentmodule:: cryptography.hazmat.primitives.twofactor.hotp + +.. class:: HOTP(key, length, backend) + + HOTP objects take a ``key`` and ``length`` parameter. The ``key`` + should be randomly generated bytes and is recommended to be 160 bits in + length. The ``length`` parameter controls the length of the generated + one time password and must be >= 6 and <= 8. + + This is an implementation of :rfc:`4226`. + + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives.twofactor.hotp import HOTP + + >>> key = b"12345678901234567890" + >>> hotp = HOTP(key, 6, backend=default_backend()) + >>> hotp.generate(0) + '755224' + >>> hotp.verify(b"755224", 0) + + :param bytes key: Secret key as ``bytes``. This value must be generated in a + cryptographically secure fashion and be at least 128 bits. + It is recommended that the key be 160 bits. + :param int length: Length of generated one time password as ``int``. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + provider. + :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits + or if the ``length`` parameter is not between 6 to 8. + + + .. method:: generate(counter) + + :param int counter: The counter value used to generate the one time password. + :return bytes: A one time password value. + + .. method:: verify(hotp, counter) + + :param bytes hotp: The one time password value to validate. + :param bytes counter: The counter value to validate against. + :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP + does not match the expected HOTP. + +Throttling +---------- + +Due to the fact that the HOTP algorithm generates rather short tokens that are 6 - 8 digits +long, brute force attacks are possible. It is highly recommended that the server that +validates the token implement a throttling scheme that locks out the account for a period of +time after a number of failed attempts. The number of allowed attempts should be as low as +possible while still ensuring that usability is not significantly impacted. + +Re-synchronization of the Counter +--------------------------------- + +The server's counter value should only be incremented on a successful HOTP authentication. +However, the counter on the client is incremented every time a new HOTP value is requested. +This can lead to the counter value being out of synchronization between the client and server. + +Due to this, it is highly recommended that the server sets a look-ahead window that allows the +server to calculate the next ``x`` HOTP values and check them against the supplied HOTP value. +This can be accomplished with something similar to the following code. + +.. code-block:: python + + def verify(hotp, counter, look_ahead): + assert look_ahead >= 0 + correct_counter = None + + otp = HOTP(key, 6, default_backend()) + for count in range(counter, counter+look_ahead): + try: + otp.verify(hotp, count) + correct_counter = count + except InvalidToken: + pass + + return correct_counter \ No newline at end of file -- cgit v1.2.3 From 94c73592a8433b4b9567f0c57c9bedadc0e927f7 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Fri, 21 Feb 2014 10:59:05 +0800 Subject: Added "version added" to docs --- docs/hazmat/primitives/twofactor.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 2b811e1e..9d661612 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -15,6 +15,8 @@ codes (HMAC). .. class:: HOTP(key, length, backend) + .. versionadded:: 0.3 + HOTP objects take a ``key`` and ``length`` parameter. The ``key`` should be randomly generated bytes and is recommended to be 160 bits in length. The ``length`` parameter controls the length of the generated -- cgit v1.2.3 From 4ccceaf4484dce24c5f0994b52079293a5fdb37c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 23 Feb 2014 11:26:37 -0600 Subject: add RSA PKCS1 signing (and structure for PSS + verification) --- docs/hazmat/primitives/asymmetric/index.rst | 10 +++ docs/hazmat/primitives/asymmetric/padding.rst | 20 +++++ docs/hazmat/primitives/asymmetric/rsa.rst | 107 ++++++++++++++++++++++++++ docs/hazmat/primitives/index.rst | 2 +- docs/hazmat/primitives/rsa.rst | 77 ------------------ 5 files changed, 138 insertions(+), 78 deletions(-) create mode 100644 docs/hazmat/primitives/asymmetric/index.rst create mode 100644 docs/hazmat/primitives/asymmetric/padding.rst create mode 100644 docs/hazmat/primitives/asymmetric/rsa.rst delete mode 100644 docs/hazmat/primitives/rsa.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst new file mode 100644 index 00000000..10319fad --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -0,0 +1,10 @@ +.. hazmat:: + +Asymmetric Algorithms +===================== + +.. toctree:: + :maxdepth: 1 + + rsa + padding diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst new file mode 100644 index 00000000..d3f713ae --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -0,0 +1,20 @@ +.. hazmat:: + +Padding +======= + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.padding + +.. warning:: + `Padding is critical`_ when signing or encrypting data using RSA. Without + correct padding signatures can be forged, messages decrypted, and private + keys compromised. + +.. class:: PKCS1() + + .. versionadded:: 0.3 + + PKCS1 (also known as PKCS1 v1.5) is a simple padding scheme developed for + use with RSA keys. It is also defined in :rfc:`3447`. + +.. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst new file mode 100644 index 00000000..82cf3528 --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -0,0 +1,107 @@ +.. hazmat:: + +RSA +=== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.rsa + +`RSA`_ is a `public-key`_ algorithm for encrypting and signing messages. + +.. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, public_exponent, modulus) + + .. versionadded:: 0.2 + + An RSA private key is required for decryption and signing of messages. + + You should use :meth:`~generate` to generate new keys. + + .. warning:: + This method only checks a limited set of properties of its arguments. + Using an RSA private key that you do not trust or with incorrect + parameters may lead to insecure operation, crashes, and other undefined + behavior. We recommend that you only ever load private keys that were + generated with software you trust. + + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``p``, ``q``, + ``private_exponent``, ``public_exponent``, or + ``modulus`` do not match the bounds specified in + :rfc:`3447`. + + .. classmethod:: generate(public_exponent, key_size, backend) + + Generate a new ``RSAPrivateKey`` instance using ``backend``. + + :param int public_exponent: The public exponent of the new key. + Usually one of the small Fermat primes 3, 5, 17, 257, 65537. If in + doubt you should `use 65537`_. + :param int key_size: The length of the modulus in bits. For keys + generated in 2014 this should be `at least 2048`_. (See page 41.) + Must be at least 512. Some backends may have additional + limitations. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + :return: A new instance of ``RSAPrivateKey``. + + .. method:: signer(padding, algorithm, backend) + + .. versionadded:: 0.3 + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding + >>> private_key = rsa.RSAPrivateKey.generate(65537, 2048, default_backend()) + >>> signer = private_key.signer(padding.PKCS1(), hashes.SHA256(), default_backend()) + >>> signer.update(b"this is some data I'd like") + >>> signer.update(b" to sign") + >>> signature = signer.finalize() + + +.. class:: RSAPublicKey(public_exponent, modulus) + + .. versionadded:: 0.2 + + An RSA public key is required for encryption and verification of 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.RSAPublicKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``public_exponent`` + or ``modulus`` do not match the bounds specified in + :rfc:`3447`. + +.. _`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 diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 5199d493..90deec8b 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -11,7 +11,7 @@ Primitives symmetric-encryption padding key-derivation-functions - rsa + asymmetric/index constant-time interfaces twofactor diff --git a/docs/hazmat/primitives/rsa.rst b/docs/hazmat/primitives/rsa.rst deleted file mode 100644 index 4e1f8e49..00000000 --- a/docs/hazmat/primitives/rsa.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. hazmat:: - -RSA -=== - -.. currentmodule:: cryptography.hazmat.primitives.asymmetric.rsa - -`RSA`_ is a `public-key`_ algorithm for encrypting and signing messages. - -.. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, public_exponent, modulus) - - .. versionadded:: 0.2 - - An RSA private key is required for decryption and signing of messages. - - You should use :meth:`~generate` to generate new keys. - - .. warning:: - This method only checks a limited set of properties of its arguments. - Using an RSA private key that you do not trust or with incorrect - parameters may lead to insecure operation, crashes, and other undefined - behavior. We recommend that you only ever load private keys that were - generated with software you trust. - - - This class conforms to the - :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` - interface. - - :raises TypeError: This is raised when the arguments are not all integers. - - :raises ValueError: This is raised when the values of ``p``, ``q``, - ``private_exponent``, ``public_exponent``, or - ``modulus`` do not match the bounds specified in - :rfc:`3447`. - - .. classmethod:: generate(public_exponent, key_size, backend) - - Generate a new ``RSAPrivateKey`` instance using ``backend``. - - :param int public_exponent: The public exponent of the new key. - Usually one of the small Fermat primes 3, 5, 17, 257, 65537. If in - doubt you should `use 65537`_. - :param int key_size: The length of the modulus in bits. For keys - generated in 2014 this should be `at least 2048`_. (See page 41.) - Must be at least 512. Some backends may have additional - limitations. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - :return: A new instance of ``RSAPrivateKey``. - - -.. class:: RSAPublicKey(public_exponent, modulus) - - .. versionadded:: 0.2 - - An RSA public key is required for encryption and verification of 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.RSAPublicKey` - interface. - - :raises TypeError: This is raised when the arguments are not all integers. - - :raises ValueError: This is raised when the values of ``public_exponent`` - or ``modulus`` do not match the bounds specified in - :rfc:`3447`. - -.. _`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 -- cgit v1.2.3 From 8dd9713ae2a69a3e870275c088df08ce2a50dce9 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 23 Feb 2014 19:26:05 -0600 Subject: incorporate review feedback. kwarg! --- docs/hazmat/primitives/asymmetric/rsa.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 82cf3528..5e71c7c8 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -74,7 +74,11 @@ RSA >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding - >>> private_key = rsa.RSAPrivateKey.generate(65537, 2048, default_backend()) + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) >>> signer = private_key.signer(padding.PKCS1(), hashes.SHA256(), default_backend()) >>> signer.update(b"this is some data I'd like") >>> signer.update(b" to sign") -- cgit v1.2.3 From 0377f5a78de949f2f1e719ac89cf8b98b910bf81 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 24 Feb 2014 19:04:46 -0600 Subject: rename PKCS1->PKCS1v15 & UnsupportedAsymmetricPadding->UnsupportedPadding --- docs/hazmat/primitives/asymmetric/padding.rst | 6 +++--- docs/hazmat/primitives/asymmetric/rsa.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index d3f713ae..7aec3bd3 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -10,11 +10,11 @@ Padding correct padding signatures can be forged, messages decrypted, and private keys compromised. -.. class:: PKCS1() +.. class:: PKCS1v15() .. versionadded:: 0.3 - PKCS1 (also known as PKCS1 v1.5) is a simple padding scheme developed for - use with RSA keys. It is also defined in :rfc:`3447`. + 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`. .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 5e71c7c8..64928878 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -79,7 +79,7 @@ RSA ... key_size=2048, ... backend=default_backend() ... ) - >>> signer = private_key.signer(padding.PKCS1(), hashes.SHA256(), default_backend()) + >>> signer = private_key.signer(padding.PKCS1v15(), hashes.SHA256(), default_backend()) >>> signer.update(b"this is some data I'd like") >>> signer.update(b" to sign") >>> signature = signer.finalize() -- cgit v1.2.3 From 7ea36ed7b7ae6b608d35dfea06aff8ca974940f2 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Tue, 18 Feb 2014 15:22:52 +0800 Subject: Added documentation for TOTP. --- docs/hazmat/primitives/twofactor.rst | 65 ++++++++++++++++++++++++++++++------ 1 file changed, 55 insertions(+), 10 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 9d661612..12277c8f 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -13,13 +13,13 @@ codes (HMAC). .. currentmodule:: cryptography.hazmat.primitives.twofactor.hotp -.. class:: HOTP(key, length, backend) +.. class:: HOTP(key, length, algorithm, backend) .. versionadded:: 0.3 - HOTP objects take a ``key`` and ``length`` parameter. The ``key`` - should be randomly generated bytes and is recommended to be 160 bits in - length. The ``length`` parameter controls the length of the generated + HOTP objects take a ``key``, ``length`` and ``algorithm`` parameter. The + ``key`` should be randomly generated bytes and is recommended to be 160 + bits in length. The ``length`` parameter controls the length of the generated one time password and must be >= 6 and <= 8. This is an implementation of :rfc:`4226`. @@ -29,9 +29,9 @@ codes (HMAC). >>> import os >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives.twofactor.hotp import HOTP - + >>> from cryptography.hazmat.primitives.hashes import SHA1 >>> key = b"12345678901234567890" - >>> hotp = HOTP(key, 6, backend=default_backend()) + >>> hotp = HOTP(key, 6, SHA1(), backend=default_backend()) >>> hotp.generate(0) '755224' >>> hotp.verify(b"755224", 0) @@ -40,12 +40,16 @@ codes (HMAC). cryptographically secure fashion and be at least 128 bits. It is recommended that the key be 160 bits. :param int length: Length of generated one time password as ``int``. + :param algorithm: A + :class:`~cryptography.hazmat.primitives.hashes` + provider. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits or if the ``length`` parameter is not between 6 to 8. - + :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not + ``SHA1()``, ``SHA256()`` or ``SHA512()``. .. method:: generate(counter) @@ -60,7 +64,7 @@ codes (HMAC). does not match the expected HOTP. Throttling ----------- +~~~~~~~~~~ Due to the fact that the HOTP algorithm generates rather short tokens that are 6 - 8 digits long, brute force attacks are possible. It is highly recommended that the server that @@ -69,7 +73,7 @@ time after a number of failed attempts. The number of allowed attempts should be possible while still ensuring that usability is not significantly impacted. Re-synchronization of the Counter ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The server's counter value should only be incremented on a successful HOTP authentication. However, the counter on the client is incremented every time a new HOTP value is requested. @@ -93,4 +97,45 @@ This can be accomplished with something similar to the following code. except InvalidToken: pass - return correct_counter \ No newline at end of file + return correct_counter + +.. currentmodule:: cryptography.hazmat.primitives.twofactor.totp + +.. class:: TOTP(key, length, algorithm, time_step, backend) + + TOTP objects take a ``key``, ``length``, ``algorithm`` and ``time_step`` + parameter. The ``key`` should be randomly generated bytes and is recommended + to be 160 bits in length. The ``length`` parameter controls the length of the + generated one time password and must be >= 6 and <= 8. + + This is an implementation of :rfc:`6238`. + + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives.twofactor.totp import TOTP + >>> from cryptography.hazmat.primitives.hashes import SHA1 + >>> key = b"12345678901234567890" + >>> totp = TOTP(key, 8, SHA1(), 30, backend=default_backend()) + >>> totp.generate(59) + '94287082' + >>> totp.verify(b"94287082", 59) + + :param bytes key: Secret key as ``bytes``. This value must be generated in a + cryptographically secure fashion and be at least 128 bits. + It is recommended that the key be 160 bits. + :param int length: Length of generated one time password as ``int``. + :param algorithm: A + :class:`~cryptography.hazmat.primitives.hashes` + provider. + :param int time_step: The time step size. The default should be 30. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + provider. + :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits + or if the ``length`` parameter is not between 6 to 8. + :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not + ``SHA1()``, ``SHA256()`` or ``SHA512()``. + + -- cgit v1.2.3 From f39716de33ad0b387f829bc111c8490d57ad6cf6 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Fri, 21 Feb 2014 14:38:30 +0800 Subject: Small fixes --- docs/hazmat/primitives/twofactor.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 12277c8f..120beb06 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -105,8 +105,9 @@ This can be accomplished with something similar to the following code. TOTP objects take a ``key``, ``length``, ``algorithm`` and ``time_step`` parameter. The ``key`` should be randomly generated bytes and is recommended - to be 160 bits in length. The ``length`` parameter controls the length of the - generated one time password and must be >= 6 and <= 8. + to be as long as your hash function's output (e.g 256-bit for SHA256). + The ``length`` parameter controls the length of the generated one time + password and must be >= 6 and <= 8. This is an implementation of :rfc:`6238`. @@ -123,8 +124,8 @@ This can be accomplished with something similar to the following code. >>> totp.verify(b"94287082", 59) :param bytes key: Secret key as ``bytes``. This value must be generated in a - cryptographically secure fashion and be at least 128 bits. - It is recommended that the key be 160 bits. + cryptographically secure fashion and be as long as your hash + function's output (e.g 256-bit for SHA256). :param int length: Length of generated one time password as ``int``. :param algorithm: A :class:`~cryptography.hazmat.primitives.hashes` @@ -137,5 +138,3 @@ This can be accomplished with something similar to the following code. or if the ``length`` parameter is not between 6 to 8. :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not ``SHA1()``, ``SHA256()`` or ``SHA512()``. - - -- cgit v1.2.3 From 341399d1ed7237568d3a2a7016e671700be9d627 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Sat, 22 Feb 2014 14:50:24 +0800 Subject: Fixed documentation based on alexs' comments. --- docs/hazmat/primitives/twofactor.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 120beb06..18bf4c01 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -30,13 +30,13 @@ codes (HMAC). >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives.twofactor.hotp import HOTP >>> from cryptography.hazmat.primitives.hashes import SHA1 - >>> key = b"12345678901234567890" + >>> key = os.urandom(16) >>> hotp = HOTP(key, 6, SHA1(), backend=default_backend()) - >>> hotp.generate(0) + >>> hotp.generate(0) # doctest: +SKIP '755224' - >>> hotp.verify(b"755224", 0) + >>> hotp.verify(b"755224", 0) # doctest: +SKIP - :param bytes key: Secret key as ``bytes``. This value must be generated in a + :param bytes key: Secret key. This value must be generated in a cryptographically secure fashion and be at least 128 bits. It is recommended that the key be 160 bits. :param int length: Length of generated one time password as ``int``. @@ -46,8 +46,8 @@ codes (HMAC). :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. - :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits - or if the ``length`` parameter is not between 6 to 8. + :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits + or if the ``length`` parameter is not 6, 7 or 8. :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not ``SHA1()``, ``SHA256()`` or ``SHA512()``. @@ -114,27 +114,28 @@ This can be accomplished with something similar to the following code. .. doctest:: >>> import os + >>> import time >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives.twofactor.totp import TOTP >>> from cryptography.hazmat.primitives.hashes import SHA1 - >>> key = b"12345678901234567890" + >>> key = os.urandom(16) >>> totp = TOTP(key, 8, SHA1(), 30, backend=default_backend()) - >>> totp.generate(59) + >>> totp.generate(time.time()) # doctest: +SKIP '94287082' - >>> totp.verify(b"94287082", 59) + >>> totp.verify(b"94287082", 59) # doctest: +SKIP - :param bytes key: Secret key as ``bytes``. This value must be generated in a + :param bytes key: Secret key. This value must be generated in a cryptographically secure fashion and be as long as your hash function's output (e.g 256-bit for SHA256). :param int length: Length of generated one time password as ``int``. :param algorithm: A :class:`~cryptography.hazmat.primitives.hashes` provider. - :param int time_step: The time step size. The default should be 30. + :param int time_step: The time step size. The recommended size is 30. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. - :raises ValueError: This is raised if the provided ``key`` is shorter 128 bits - or if the ``length`` parameter is not between 6 to 8. + :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits + or if the ``length`` parameter is not 6, 7 or 8. :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not ``SHA1()``, ``SHA256()`` or ``SHA512()``. -- cgit v1.2.3 From cec584caa9b857da35b8e8a8f0b1f7295ddf661f Mon Sep 17 00:00:00 2001 From: Ayrx Date: Sat, 22 Feb 2014 19:11:35 +0800 Subject: Updated secret key description --- docs/hazmat/primitives/twofactor.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 18bf4c01..3951a1cc 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -36,9 +36,9 @@ codes (HMAC). '755224' >>> hotp.verify(b"755224", 0) # doctest: +SKIP - :param bytes key: Secret key. This value must be generated in a - cryptographically secure fashion and be at least 128 bits. - It is recommended that the key be 160 bits. + :param bytes key: Per-user secret key. This value must be kept secret + and be at least 128 bits. It is recommended that the + key be 160 bits. :param int length: Length of generated one time password as ``int``. :param algorithm: A :class:`~cryptography.hazmat.primitives.hashes` @@ -124,9 +124,9 @@ This can be accomplished with something similar to the following code. '94287082' >>> totp.verify(b"94287082", 59) # doctest: +SKIP - :param bytes key: Secret key. This value must be generated in a - cryptographically secure fashion and be as long as your hash - function's output (e.g 256-bit for SHA256). + :param bytes key: Per-user secret key. This value must be kept secret + and be at least 128 bits. It is recommended that the + key be 160 bits. :param int length: Length of generated one time password as ``int``. :param algorithm: A :class:`~cryptography.hazmat.primitives.hashes` -- cgit v1.2.3 From 52e1e930880456e69b9a0fdd371337225fc3511b Mon Sep 17 00:00:00 2001 From: Ayrx Date: Sun, 23 Feb 2014 00:23:55 +0800 Subject: Added method definitions to TOTP documentation. --- docs/hazmat/primitives/twofactor.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 3951a1cc..2e170b85 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -59,7 +59,7 @@ codes (HMAC). .. method:: verify(hotp, counter) :param bytes hotp: The one time password value to validate. - :param bytes counter: The counter value to validate against. + :param int counter: The counter value to validate against. :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP does not match the expected HOTP. @@ -139,3 +139,15 @@ This can be accomplished with something similar to the following code. or if the ``length`` parameter is not 6, 7 or 8. :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not ``SHA1()``, ``SHA256()`` or ``SHA512()``. + + .. method:: generate(time) + + :param int counter: The time value used to generate the one time password. + :return bytes: A one time password value. + + .. method:: verify(totp, time) + + :param bytes hotp: The one time password value to validate. + :param int time: The time value to validate against. + :raises cryptography.exceptions.InvalidToken: This is raised when the supplied TOTP + does not match the expected TOTP. -- cgit v1.2.3 From 3b6423dc2a10320d739554e88c1384a8e8a068c2 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Sun, 23 Feb 2014 12:40:13 +0800 Subject: Updated HOTP and TOTP doctests --- docs/hazmat/primitives/twofactor.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 2e170b85..ca18c50b 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -32,9 +32,8 @@ codes (HMAC). >>> from cryptography.hazmat.primitives.hashes import SHA1 >>> key = os.urandom(16) >>> hotp = HOTP(key, 6, SHA1(), backend=default_backend()) - >>> hotp.generate(0) # doctest: +SKIP - '755224' - >>> hotp.verify(b"755224", 0) # doctest: +SKIP + >>> hotp_value = hotp.generate(0) + >>> hotp.verify(hotp_value, 0) :param bytes key: Per-user secret key. This value must be kept secret and be at least 128 bits. It is recommended that the @@ -120,9 +119,9 @@ This can be accomplished with something similar to the following code. >>> from cryptography.hazmat.primitives.hashes import SHA1 >>> key = os.urandom(16) >>> totp = TOTP(key, 8, SHA1(), 30, backend=default_backend()) - >>> totp.generate(time.time()) # doctest: +SKIP - '94287082' - >>> totp.verify(b"94287082", 59) # doctest: +SKIP + >>> time_value = time.time() + >>> totp_value = totp.generate(time_value) + >>> totp.verify(totp_value, time_value) :param bytes key: Per-user secret key. This value must be kept secret and be at least 128 bits. It is recommended that the -- cgit v1.2.3 From 1f8a1e801196280c4f7708a65e582f7e599b78c0 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Mon, 24 Feb 2014 16:24:12 +0800 Subject: Fixed documentation --- docs/hazmat/primitives/twofactor.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index ca18c50b..4160a17a 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -39,7 +39,7 @@ codes (HMAC). and be at least 128 bits. It is recommended that the key be 160 bits. :param int length: Length of generated one time password as ``int``. - :param algorithm: A + :param HashAlgorithm algorithm: A :class:`~cryptography.hazmat.primitives.hashes` provider. :param backend: A @@ -48,7 +48,9 @@ codes (HMAC). :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not - ``SHA1()``, ``SHA256()`` or ``SHA512()``. + :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :class:`~cryptography.hazmat.primitives.hashes.SHA256()` + or :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. .. method:: generate(counter) @@ -127,7 +129,7 @@ This can be accomplished with something similar to the following code. and be at least 128 bits. It is recommended that the key be 160 bits. :param int length: Length of generated one time password as ``int``. - :param algorithm: A + :param HashAlgorithm algorithm: A :class:`~cryptography.hazmat.primitives.hashes` provider. :param int time_step: The time step size. The recommended size is 30. @@ -137,7 +139,9 @@ This can be accomplished with something similar to the following code. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not - ``SHA1()``, ``SHA256()`` or ``SHA512()``. + :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :class:`~cryptography.hazmat.primitives.hashes.SHA256()` + or :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. .. method:: generate(time) @@ -146,7 +150,7 @@ This can be accomplished with something similar to the following code. .. method:: verify(totp, time) - :param bytes hotp: The one time password value to validate. + :param bytes totp: The one time password value to validate. :param int time: The time value to validate against. :raises cryptography.exceptions.InvalidToken: This is raised when the supplied TOTP does not match the expected TOTP. -- cgit v1.2.3 From 72e7477089995e848c9b6f809104babb9379b16f Mon Sep 17 00:00:00 2001 From: Ayrx Date: Tue, 25 Feb 2014 11:43:48 +0800 Subject: Fixed wrong param naming in totp documentation --- docs/hazmat/primitives/twofactor.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 4160a17a..06be151e 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -145,7 +145,7 @@ This can be accomplished with something similar to the following code. .. method:: generate(time) - :param int counter: The time value used to generate the one time password. + :param int time: The time value used to generate the one time password. :return bytes: A one time password value. .. method:: verify(totp, time) -- cgit v1.2.3 From 7c49d18006fd15401f3f4651b6b441d4cac42d42 Mon Sep 17 00:00:00 2001 From: David Reid Date: Tue, 25 Feb 2014 11:05:46 -0800 Subject: Do some nitpicking cleanup of the twofactor code and documentation. --- docs/hazmat/primitives/twofactor.rst | 66 +++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 31 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 06be151e..3df1a147 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -19,8 +19,8 @@ codes (HMAC). HOTP objects take a ``key``, ``length`` and ``algorithm`` parameter. The ``key`` should be randomly generated bytes and is recommended to be 160 - bits in length. The ``length`` parameter controls the length of the generated - one time password and must be >= 6 and <= 8. + bits in length. The ``length`` parameter controls the length of the + generated one time password and must be >= 6 and <= 8. This is an implementation of :rfc:`4226`. @@ -45,44 +45,48 @@ codes (HMAC). :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. - :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits - or if the ``length`` parameter is not 6, 7 or 8. - :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not - :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, - :class:`~cryptography.hazmat.primitives.hashes.SHA256()` - or :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. + :raises ValueError: This is raised if the provided ``key`` is shorter than + 128 bits or if the ``length`` parameter is not 6, 7 or 8. + :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` + is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or + :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. .. method:: generate(counter) - :param int counter: The counter value used to generate the one time password. + :param int counter: The counter value used to generate the one time + password. :return bytes: A one time password value. .. method:: verify(hotp, counter) :param bytes hotp: The one time password value to validate. :param int counter: The counter value to validate against. - :raises cryptography.exceptions.InvalidToken: This is raised when the supplied HOTP - does not match the expected HOTP. + :raises cryptography.exceptions.InvalidToken: This is raised when the + supplied HOTP does not match the expected HOTP. Throttling ~~~~~~~~~~ -Due to the fact that the HOTP algorithm generates rather short tokens that are 6 - 8 digits -long, brute force attacks are possible. It is highly recommended that the server that -validates the token implement a throttling scheme that locks out the account for a period of -time after a number of failed attempts. The number of allowed attempts should be as low as -possible while still ensuring that usability is not significantly impacted. +Due to the fact that the HOTP algorithm generates rather short tokens that are +6 - 8 digits long, brute force attacks are possible. It is highly recommended +that the server that validates the token implement a throttling scheme that +locks out the account for a period of time after a number of failed attempts. +The number of allowed attempts should be as low as possible while still +ensuring that usability is not significantly impacted. Re-synchronization of the Counter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The server's counter value should only be incremented on a successful HOTP authentication. -However, the counter on the client is incremented every time a new HOTP value is requested. -This can lead to the counter value being out of synchronization between the client and server. +The server's counter value should only be incremented on a successful HOTP +authentication. However, the counter on the client is incremented every time a +new HOTP value is requested. This can lead to the counter value being out of +synchronization between the client and server. -Due to this, it is highly recommended that the server sets a look-ahead window that allows the -server to calculate the next ``x`` HOTP values and check them against the supplied HOTP value. -This can be accomplished with something similar to the following code. +Due to this, it is highly recommended that the server sets a look-ahead window +that allows the server to calculate the next ``x`` HOTP values and check them +against the supplied HOTP value. This can be accomplished with something +similar to the following code. .. code-block:: python @@ -91,7 +95,7 @@ This can be accomplished with something similar to the following code. correct_counter = None otp = HOTP(key, 6, default_backend()) - for count in range(counter, counter+look_ahead): + for count in range(counter, counter + look_ahead): try: otp.verify(hotp, count) correct_counter = count @@ -136,12 +140,12 @@ This can be accomplished with something similar to the following code. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. - :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits - or if the ``length`` parameter is not 6, 7 or 8. - :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` is not - :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, - :class:`~cryptography.hazmat.primitives.hashes.SHA256()` - or :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. + :raises ValueError: This is raised if the provided ``key`` is shorter than + 128 bits or if the ``length`` parameter is not 6, 7 or 8. + :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` + is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or + :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. .. method:: generate(time) @@ -152,5 +156,5 @@ This can be accomplished with something similar to the following code. :param bytes totp: The one time password value to validate. :param int time: The time value to validate against. - :raises cryptography.exceptions.InvalidToken: This is raised when the supplied TOTP - does not match the expected TOTP. + :raises cryptography.exceptions.InvalidToken: This is raised when the + supplied TOTP does not match the expected TOTP. -- cgit v1.2.3 From fb843aa91df65aaedb562974d1c350482ebf8777 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 25 Feb 2014 11:37:36 -0800 Subject: Re-linewrap the symmetric encryption doc source --- docs/hazmat/primitives/symmetric-encryption.rst | 88 ++++++++++--------------- 1 file changed, 35 insertions(+), 53 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index d91dde9d..2306c5b7 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -88,7 +88,7 @@ Algorithms choice for encryption. :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. - This must be kept secret. + This must be kept secret. .. class:: Camellia(key) @@ -97,7 +97,7 @@ Algorithms is not as widely studied or deployed. :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. - This must be kept secret. + This must be kept secret. .. class:: TripleDES(key) @@ -108,12 +108,11 @@ Algorithms is incredibly slow; old applications should consider moving away from it. :param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits - (note that DES functionally uses ``56``, ``112``, or - ``168`` bits of the key, there is a parity byte in each - component of the key), in some materials these are - referred to as being up to three separate keys (each - ``56`` bits long), they can simply be concatenated to - produce the full key. This must be kept secret. + (note that DES functionally uses ``56``, ``112``, or ``168`` bits of + the key, there is a parity byte in each component of the key), in some + materials these are referred to as being up to three separate keys + (each ``56`` bits long), they can simply be concatenated to produce the + full key. This must be kept secret. .. class:: CAST5(key) @@ -124,7 +123,7 @@ Algorithms a variable key length cipher and supports keys from 40-128 bits in length. :param bytes key: The secret key, 40-128 bits in length (in increments of - 8). This must be kept secret. + 8). This must be kept secret. Weak Ciphers ------------ @@ -142,7 +141,7 @@ Weak Ciphers that users of Blowfish move to newer algorithms, such as :class:`AES`. :param bytes key: The secret key, 32-448 bits in length (in increments of - 8). This must be kept secret. + 8). This must be kept secret. .. class:: ARC4(key) @@ -151,8 +150,7 @@ Weak Ciphers mode constructions. :param bytes key: The secret key, ``40``, ``56``, ``64``, ``80``, ``128``, - ``192``, or ``256`` bits in length. This must be kept - secret. + ``192``, or ``256`` bits in length. This must be kept secret. .. doctest:: @@ -182,17 +180,12 @@ Modes **Padding is required when using this mode.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included - in a transmitted message). Must be the - same number of bytes as the - ``block_size`` of the cipher. Each time - something is encrypted a new - ``initialization_vector`` should be - generated. Do not reuse an - ``initialization_vector`` with - a given ``key``, and particularly do - not use a constant - ``initialization_vector``. + to be kept secret (they can be included in a transmitted message). Must + be the same number of bytes as the ``block_size`` of the cipher. Each + time something is encrypted a new ``initialization_vector`` should be + generated. Do not reuse an ``initialization_vector`` with a given + ``key``, and particularly do not use a constant + ``initialization_vector``. A good construction looks like: @@ -226,12 +219,11 @@ Modes **This mode does not require padding.** :param bytes nonce: Should be random bytes. It is critical to never reuse a - ``nonce`` with a given key. Any reuse of a nonce - with the same key compromises the security of every - message encrypted with that key. Must be the same - number of bytes as the ``block_size`` of the cipher - with a given key. The nonce does not need to be kept - secret and may be included alongside the ciphertext. + ``nonce`` with a given key. Any reuse of a nonce with the same key + compromises the security of every message encrypted with that key. Must + be the same number of bytes as the ``block_size`` of the cipher with a + given key. The nonce does not need to be kept secret and may be + included alongside the ciphertext. .. class:: OFB(initialization_vector) @@ -241,12 +233,9 @@ Modes **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included - in a transmitted message). Must be the - same number of bytes as the - ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with - a given ``key``. + to be kept secret (they can be included in a transmitted message). Must + be the same number of bytes as the ``block_size`` of the cipher. Do not + reuse an ``initialization_vector`` with a given ``key``. .. class:: CFB(initialization_vector) @@ -256,12 +245,9 @@ Modes **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included - in a transmitted message). Must be the - same number of bytes as the - ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with - a given ``key``. + to be kept secret (they can be included in a transmitted message). Must + be the same number of bytes as the ``block_size`` of the cipher. Do not + reuse an ``initialization_vector`` with a given ``key``. .. class:: GCM(initialization_vector, tag=None) @@ -282,13 +268,10 @@ Modes **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included - in a transmitted message). NIST - `recommends 96-bit IV length`_ for - performance critical situations, but it - can be up to 2\ :sup:`64` - 1 bits. - Do not reuse an ``initialization_vector`` - with a given ``key``. + to be kept secret (they can be included in a transmitted message). NIST + `recommends 96-bit IV length`_ for performance critical situations, but + it can be up to 2\ :sup:`64` - 1 bits. Do not reuse an + ``initialization_vector`` with a given ``key``. .. note:: @@ -300,8 +283,8 @@ Modes (32-bits). Applications **must** verify the tag is the expected length to guarantee the expected security margin. - :param bytes tag: The tag bytes to verify during decryption. When encrypting - this must be None. + :param bytes tag: The tag bytes to verify during decryption. When + encrypting this must be ``None``. .. testcode:: @@ -428,8 +411,7 @@ Interfaces :return bytes: Returns the remainder of the data. :raises ValueError: This is raised when the data provided isn't - correctly padded to be a multiple of the - algorithm's block size. + correctly padded to be a multiple of the algorithm's block size. Once ``finalize`` is called this object can no longer be used and :meth:`update` and :meth:`finalize` will raise @@ -473,7 +455,7 @@ Interfaces :return bytes: Returns the tag value as bytes. :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called - before the context is finalized. + before the context is finalized. .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html -- cgit v1.2.3 From 62a9217aa3f6cf34d4cafcd1d147082bc7c7918c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 25 Feb 2014 13:56:53 -0600 Subject: reorganize docs slightly --- docs/hazmat/primitives/asymmetric/rsa.rst | 36 ++++++++++++++++++------------- 1 file changed, 21 insertions(+), 15 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 64928878..682820b3 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -54,20 +54,7 @@ RSA .. versionadded:: 0.3 - :param padding: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` - provider. - - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` - provider. - - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - - :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + Sign data which can be verified later by others using the public key. .. doctest:: @@ -79,11 +66,30 @@ RSA ... key_size=2048, ... backend=default_backend() ... ) - >>> signer = private_key.signer(padding.PKCS1v15(), hashes.SHA256(), default_backend()) + >>> signer = private_key.signer( + ... padding.PKCS1v15(), + ... hashes.SHA256(), + ... default_backend() + ... ) >>> signer.update(b"this is some data I'd like") >>> signer.update(b" to sign") >>> signature = signer.finalize() + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + .. class:: RSAPublicKey(public_exponent, modulus) -- cgit v1.2.3 From 42b3713eede3f5b417b0ce123fdcc9c4c24009d3 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 23 Feb 2014 19:13:19 -0600 Subject: add RSA verification support --- docs/hazmat/primitives/asymmetric/rsa.rst | 36 +++++++++++++++++++++++++++++++ docs/hazmat/primitives/interfaces.rst | 4 ++-- 2 files changed, 38 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 682820b3..528b5324 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -111,6 +111,42 @@ RSA or ``modulus`` do not match the bounds specified in :rfc:`3447`. + .. method:: verifier(signature, padding, algorithm, backend) + + .. versionadded:: 0.3 + + :param bytes signature: The signature to verify. + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding + >>> private_key = rsa.RSAPrivateKey.generate(65537, 2048, default_backend()) + >>> signer = private_key.signer(padding.PKCS1(), 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.PKCS1(), hashes.SHA256(), default_backend()) + >>> verifier.update(data) + >>> verifier.verify() + .. _`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 diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 5be3dd95..53113223 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -254,8 +254,8 @@ Asymmetric Interfaces .. method:: verify() - :raises cryptography.exceptions.InvalidSignature: If signature does not - validate. + :raises :class:`~cryptography.exceptions.InvalidAsymmetricSignature`: If + the signature does not validate. .. class:: AsymmetricPadding -- cgit v1.2.3 From 4c0b4a99982138c4ab83dfffb19975a91c57d1ab Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 23 Feb 2014 19:28:44 -0600 Subject: more kwargs --- docs/hazmat/primitives/asymmetric/rsa.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 528b5324..198ed7a3 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -137,7 +137,11 @@ RSA >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding - >>> private_key = rsa.RSAPrivateKey.generate(65537, 2048, default_backend()) + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) >>> signer = private_key.signer(padding.PKCS1(), hashes.SHA256(), default_backend()) >>> data= b"this is some data I'd like to sign" >>> signer.update(data) -- cgit v1.2.3 From a0c157f467536b556481f7c2ee950612f4f8f7e7 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 25 Feb 2014 23:05:54 -0600 Subject: fix docs, port some review comments forward to the new PR --- docs/hazmat/primitives/asymmetric/rsa.rst | 39 +++++++++++++++++-------------- 1 file changed, 21 insertions(+), 18 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 198ed7a3..b3119440 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -115,22 +115,8 @@ RSA .. versionadded:: 0.3 - :param bytes signature: The signature to verify. - - :param padding: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` - provider. - - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` - provider. - - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - - :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + Verify data was signed by the private key associated with the public + key. .. doctest:: @@ -142,15 +128,32 @@ RSA ... key_size=2048, ... backend=default_backend() ... ) - >>> signer = private_key.signer(padding.PKCS1(), hashes.SHA256(), default_backend()) + >>> signer = private_key.signer(padding.PKCS1v15(), 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.PKCS1(), hashes.SHA256(), default_backend()) + >>> verifier = public_key.verifier(signature, padding.PKCS1v15(), hashes.SHA256(), default_backend()) >>> verifier.update(data) >>> verifier.verify() + :param bytes signature: The signature to verify. + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + .. _`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 -- cgit v1.2.3 From fef1fbd1187b7fc80589553fb192210dd15a3a1c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 26 Feb 2014 23:39:37 -0400 Subject: address some review comments --- docs/hazmat/primitives/interfaces.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 53113223..15ad1d1b 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -254,8 +254,8 @@ Asymmetric Interfaces .. method:: verify() - :raises :class:`~cryptography.exceptions.InvalidAsymmetricSignature`: If - the signature does not validate. + :raises cryptography.exceptions.InvalidSignature: If the signature does + not validate. .. class:: AsymmetricPadding -- cgit v1.2.3 From adba07a814626d1e409cd06d6a0774dae69a2c33 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 26 Feb 2014 23:55:51 -0400 Subject: docs language improvement --- docs/hazmat/primitives/asymmetric/rsa.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index b3119440..7943981e 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -115,7 +115,7 @@ RSA .. versionadded:: 0.3 - Verify data was signed by the private key associated with the public + Verify data was signed by the private key associated with this public key. .. doctest:: -- cgit v1.2.3 From d63cbd0a7686fef6fffacad626cbf3bdbd3bb058 Mon Sep 17 00:00:00 2001 From: Wouter Bolsterlee Date: Sat, 1 Mar 2014 00:45:31 +0100 Subject: Fix ":param:" syntax in KDF docs --- docs/hazmat/primitives/key-derivation-functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index d8a0e241..851dbb0b 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -179,7 +179,7 @@ Different KDFs are suitable for different tasks such as: :param bytes info: Application specific context information. If ``None`` is explicitly passed an empty byte string will be used. - :params backend: A + :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. -- cgit v1.2.3 From 58ee8c55acc585fb90a99f6102fa4a7d56072b27 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 1 Mar 2014 09:50:14 -0800 Subject: Docs as well --- docs/hazmat/primitives/twofactor.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 3df1a147..784b8ed1 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -47,8 +47,8 @@ codes (HMAC). provider. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. - :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` - is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :raises ValueError: This is raised if the provided ``algorithm`` is not + :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. @@ -142,8 +142,8 @@ similar to the following code. provider. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. - :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` - is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :raises ValueError: This is raised if the provided ``algorithm`` is not + :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. -- cgit v1.2.3 From 9b1a82e42bdd546220225430aa06e3b732fb0155 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 1 Mar 2014 09:57:25 -0800 Subject: Switch to TypeError --- docs/hazmat/primitives/twofactor.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 784b8ed1..0e781439 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -47,7 +47,7 @@ codes (HMAC). provider. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. - :raises ValueError: This is raised if the provided ``algorithm`` is not + :raises TypeError: This is raised if the provided ``algorithm`` is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. @@ -142,7 +142,7 @@ similar to the following code. provider. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. - :raises ValueError: This is raised if the provided ``algorithm`` is not + :raises TypeError: This is raised if the provided ``algorithm`` is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. -- cgit v1.2.3 From 9ab901df604177ea331b59b94d513af50af8f8e1 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Tue, 4 Mar 2014 01:12:07 +0800 Subject: Updated documentation for HOTP and TOTP TypeError --- docs/hazmat/primitives/twofactor.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 0e781439..3912d483 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -50,7 +50,8 @@ codes (HMAC). :raises TypeError: This is raised if the provided ``algorithm`` is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or - :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. + :class:`~cryptography.hazmat.primitives.hashes.SHA512()` or if the + ``length`` parameter is not an integer. .. method:: generate(counter) @@ -145,7 +146,8 @@ similar to the following code. :raises TypeError: This is raised if the provided ``algorithm`` is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or - :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. + :class:`~cryptography.hazmat.primitives.hashes.SHA512()` or if the + ``length`` parameter is not an integer. .. method:: generate(time) -- cgit v1.2.3 From b416715b8ee96c445587d444a4684bc7817e4638 Mon Sep 17 00:00:00 2001 From: Mohammed Attia Date: Tue, 4 Mar 2014 03:29:56 +0200 Subject: Added documentation for the DSA interfaces --- docs/hazmat/primitives/interfaces.rst | 107 ++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 15ad1d1b..b119bc5b 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -231,6 +231,113 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +.. class:: DSAParams + + .. versionadded:: 0.3 + + `DSA`_ parameters. + + .. attribute:: modulus + + :type: int + + The prime modulus that's used in generating the DSA keypair and used + in the DSA signing and verification processes. + + .. attribute:: subgroup_order + + :type: int + + The subgroup order that's used in generating the DSA keypair + by the generator and used in the DSA signing and verification + processes. + + .. attribute:: generator + + :type: int + + The generator that is used in generating the DSA keypair and used + in the DSA signing and verification processes." + + .. attribute:: p + + :type: int + + The prime modulus that's used in generating the DSA keypair and used + in the DSA signing and verification processes. Alias for modulus. + + .. attribute:: q + + :type: int + + The subgroup order that's used in generating the DSA keypair + by the generator and used in the DSA signing and verification + processes. Alias for subgroup_order. + + .. attribute:: g + + :type: int + + The generator that is used in generating the DSA keypair and used + in the DSA signing and verification processes. Alias for generator. + + +.. class:: DSAPrivateKey + + .. versionadded:: 0.3 + + An `DSA`_ private key. + + .. method:: public_key() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` + + An DSA public key object corresponding to the values of the private key. + + .. method:: parameters() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParams` + + The DSAParams object associated with this private key. + + .. attribute:: key_size + + :type: int + + The bit length of the modulus. + + .. attribute:: x + + :type: int + + The private key. + + .. attribute:: y + + :type: int + + The public key. + + +.. class:: DSAPublicKey + + .. versionadded:: 0.3 + + An `DSA`_ private key. + + .. method:: parameters() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParams` + + The DSAParams object associated with this public key. + + .. attribute:: y + + :type: int + + The public key. + + .. class:: AsymmetricSignatureContext .. versionadded:: 0.2 -- cgit v1.2.3 From 7032451fb442f3e4c5dd590c54aa7532b1197f5c Mon Sep 17 00:00:00 2001 From: Mohammed Attia Date: Tue, 4 Mar 2014 03:34:39 +0200 Subject: Annotate aliases in the DSA documentation --- docs/hazmat/primitives/interfaces.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index b119bc5b..bbaeb5e7 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -264,7 +264,7 @@ Asymmetric Interfaces :type: int The prime modulus that's used in generating the DSA keypair and used - in the DSA signing and verification processes. Alias for modulus. + in the DSA signing and verification processes. Alias for :attr:`modulus`. .. attribute:: q @@ -272,14 +272,14 @@ Asymmetric Interfaces The subgroup order that's used in generating the DSA keypair by the generator and used in the DSA signing and verification - processes. Alias for subgroup_order. + processes. Alias for :attr:`subgroup_order`. .. attribute:: g :type: int The generator that is used in generating the DSA keypair and used - in the DSA signing and verification processes. Alias for generator. + in the DSA signing and verification processes. Alias for :attr:`generator`. .. class:: DSAPrivateKey -- cgit v1.2.3 From 604c78f75ca1c0a5b6a340dd5067182487f1b65d Mon Sep 17 00:00:00 2001 From: Mohammed Attia Date: Tue, 4 Mar 2014 03:56:08 +0200 Subject: Define DSA in the documentation --- docs/hazmat/primitives/interfaces.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index bbaeb5e7..2ea4b583 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -442,3 +442,4 @@ Key Derivation Functions .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) .. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem +.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm -- cgit v1.2.3 From cb9a6c24ea2165b25e4129a440871ce7bcab3de4 Mon Sep 17 00:00:00 2001 From: Mohammed Attia Date: Tue, 4 Mar 2014 04:16:35 +0200 Subject: Change keypair to key pair to pass the sphinx spelling test --- docs/hazmat/primitives/interfaces.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 2ea4b583..c1a2d23a 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -241,14 +241,14 @@ Asymmetric Interfaces :type: int - The prime modulus that's used in generating the DSA keypair and used + The prime modulus that's used in generating the DSA key pair and used in the DSA signing and verification processes. .. attribute:: subgroup_order :type: int - The subgroup order that's used in generating the DSA keypair + The subgroup order that's used in generating the DSA key pair by the generator and used in the DSA signing and verification processes. @@ -256,21 +256,21 @@ Asymmetric Interfaces :type: int - The generator that is used in generating the DSA keypair and used + The generator that is used in generating the DSA key pair and used in the DSA signing and verification processes." .. attribute:: p :type: int - The prime modulus that's used in generating the DSA keypair and used + The prime modulus that's used in generating the DSA key pair and used in the DSA signing and verification processes. Alias for :attr:`modulus`. .. attribute:: q :type: int - The subgroup order that's used in generating the DSA keypair + The subgroup order that's used in generating the DSA key pair by the generator and used in the DSA signing and verification processes. Alias for :attr:`subgroup_order`. @@ -278,7 +278,7 @@ Asymmetric Interfaces :type: int - The generator that is used in generating the DSA keypair and used + The generator that is used in generating the DSA key pair and used in the DSA signing and verification processes. Alias for :attr:`generator`. -- cgit v1.2.3 From 7a1738a1b8b3da2a215f2ea3aff73a67eaaab406 Mon Sep 17 00:00:00 2001 From: Mohammed Attia Date: Tue, 4 Mar 2014 19:17:24 +0200 Subject: Typo fixes --- docs/hazmat/primitives/interfaces.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index c1a2d23a..d94aee83 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -241,14 +241,14 @@ Asymmetric Interfaces :type: int - The prime modulus that's used in generating the DSA key pair and used + The prime modulus that is used in generating the DSA key pair and used in the DSA signing and verification processes. .. attribute:: subgroup_order :type: int - The subgroup order that's used in generating the DSA key pair + The subgroup order that is used in generating the DSA key pair by the generator and used in the DSA signing and verification processes. @@ -257,20 +257,20 @@ Asymmetric Interfaces :type: int The generator that is used in generating the DSA key pair and used - in the DSA signing and verification processes." + in the DSA signing and verification processes. .. attribute:: p :type: int - The prime modulus that's used in generating the DSA key pair and used + The prime modulus that is used in generating the DSA key pair and used in the DSA signing and verification processes. Alias for :attr:`modulus`. .. attribute:: q :type: int - The subgroup order that's used in generating the DSA key pair + The subgroup order that is used in generating the DSA key pair by the generator and used in the DSA signing and verification processes. Alias for :attr:`subgroup_order`. @@ -286,7 +286,7 @@ Asymmetric Interfaces .. versionadded:: 0.3 - An `DSA`_ private key. + A `DSA`_ private key. .. method:: public_key() @@ -323,7 +323,7 @@ Asymmetric Interfaces .. versionadded:: 0.3 - An `DSA`_ private key. + A `DSA`_ private key. .. method:: parameters() -- cgit v1.2.3 From 71acc67e71013f8660a16d78520da22ec379e259 Mon Sep 17 00:00:00 2001 From: Mohammed Attia Date: Tue, 4 Mar 2014 19:20:45 +0200 Subject: Change DSAParams to DSAParameters --- docs/hazmat/primitives/interfaces.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index d94aee83..cc2a3000 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -231,7 +231,7 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. -.. class:: DSAParams +.. class:: DSAParameters .. versionadded:: 0.3 @@ -296,9 +296,9 @@ Asymmetric Interfaces .. method:: parameters() - :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParams` + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` - The DSAParams object associated with this private key. + The DSAParameters object associated with this private key. .. attribute:: key_size @@ -327,9 +327,9 @@ Asymmetric Interfaces .. method:: parameters() - :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParams` + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` - The DSAParams object associated with this public key. + The DSAParameters object associated with this public key. .. attribute:: y -- cgit v1.2.3 From c6a6f317fca2aa368943870ecc3854bb53399f06 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 6 Mar 2014 14:22:56 -0800 Subject: Convert stuff --- docs/hazmat/backends/interfaces.rst | 2 +- docs/hazmat/primitives/cryptographic-hashes.rst | 2 +- docs/hazmat/primitives/hmac.rst | 2 +- docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index af19fbc6..a7a9661b 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -258,7 +258,7 @@ A specific ``backend`` may provide one or more of these interfaces. style key serialization. .. method:: load_openssl_pem_private_key(data, password) - + :param bytes data: PEM data to deserialize. :param bytes password: The password to use if this data is encrypted. diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 6c56acad..86b85852 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -29,7 +29,7 @@ Message Digests 'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' If the backend doesn't support the requested ``algorithm`` an - :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + :class:`~cryptography.exceptions.UnsupportedHash` will be raised. Keep in mind that attacks against cryptographic hashes only get stronger with time, and that often algorithms that were once thought to be strong, diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 0118be78..1a2838f7 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -35,7 +35,7 @@ message. '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' If the backend doesn't support the requested ``algorithm`` an - :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + :class:`~cryptography.exceptions.UnsupportedHash` 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: diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 2306c5b7..2bc25c50 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -61,7 +61,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. provider. If the backend doesn't support the requested combination of ``cipher`` - and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` + and ``mode`` an :class:`~cryptography.exceptions.UnsupportedCipher` will be raised. .. method:: decryptor() @@ -71,7 +71,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. provider. If the backend doesn't support the requested combination of ``cipher`` - and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + and ``mode`` an :class:`cryptography.exceptions.UnsupportedCipher` will be raised. .. _symmetric-encryption-algorithms: -- cgit v1.2.3