Added documentation for TOTP.

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
+        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()``.
+
+

tests/hazmat/primitives/twofactor/test_totp.py

@@ -22,6 +22,7 @@ from tests.utils import load_vectors_from_file, load_nist_vectors
 vectors = load_vectors_from_file(
     "twofactor/rfc-6238.txt", load_nist_vectors)
 
+
 @pytest.mark.hmac
 class TestTOTP(object):