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') 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') 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') 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') 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') 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') 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') 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') 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