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/twofactor.rst | 94 ++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 docs/hazmat/primitives/twofactor.rst (limited to 'docs/hazmat/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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/primitives/twofactor.rst') 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