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