1 files changed, 59 insertions, 0 deletions
diff --git a/docs/hazmat/oath.rst b/docs/hazmat/oath.rst
new file mode 100644
index 00000000..b936f0e5
--- /dev/null
+++ b/docs/hazmat/oath.rst
@@ -0,0 +1,59 @@
+.. hazmat::
+
+OATH
+====
+
+.. currentmodule:: cryptography.hazmat.oath
+
+This module contains algorithms under the umbrella of the
+Initiative for Open Authentication (OATH).
+
+Currently, it contains an algorithm for generating and verifying
+one time password values based on Hash-based message authentication
+codes (HMAC).
+
+.. currentmodule:: cryptography.hazmat.oath.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.oath.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.