diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/primitives/twofactor.rst | 65 |
1 files changed, 55 insertions, 10 deletions
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()``. + + |