From 18ca44bfef0fe2908d9da3b3008941325d04a971 Mon Sep 17 00:00:00 2001
From: Ayrx <terrycwk1994@gmail.com>
Date: Wed, 12 Feb 2014 18:38:28 +0800
Subject: Added documentation for HOTP implementation.

---
 docs/hazmat/oath/hotp.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst            |  1 +
 2 files changed, 47 insertions(+)
 create mode 100644 docs/hazmat/oath/hotp.rst

(limited to 'docs')

diff --git a/docs/hazmat/oath/hotp.rst b/docs/hazmat/oath/hotp.rst
new file mode 100644
index 00000000..d84f5bdf
--- /dev/null
+++ b/docs/hazmat/oath/hotp.rst
@@ -0,0 +1,46 @@
+.. hazmat::
+
+HMAC-Based One-Time Password Algorithm
+======================================
+
+.. currentmodule:: cryptography.hazmat.oath.hotp
+
+This module contains functions for generating and verifying one time password
+values based on Hash-based message authentication codes (HMAC).
+
+.. class:: HOTP(secret, length, backend)
+
+    HOTP objects take a ``secret`` and ``length`` parameter. The ``secret``
+    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 is recommended to be at least a 6 digit value.
+
+    This is an implementation of :rfc:`4226`.
+
+    .. doctest::
+
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> from cryptography.hazmat.oath.hotp import HOTP
+        >>> hotp = HOTP(secret, 6, backend=default_backend)
+        >>> hotp.generate(0)
+        958695
+        >>> hotp.verify("958695", 0)
+        True
+
+    :param secret: Secret key as ``bytes``.
+    :param length: Length of generated one time password as ``int``.
+    :param backend: A
+        :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+        provider.
+
+    .. method:: generate(counter)
+
+        :param counter: The counter value used to generate the one time password.
+        :return: A one time password value.
+
+    .. method:: verify(hotp, counter)
+
+        :param hotp: The one time password value to validate.
+        :param counter: The counter value to validate against.
+        :return: ``True`` if the one time password value is valid. ``False`` if otherwise.
+
diff --git a/docs/index.rst b/docs/index.rst
index 176405b5..7d6e618c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -75,6 +75,7 @@ The hazardous materials layer
     hazmat/primitives/index
     hazmat/backends/index
     hazmat/bindings/index
+    hazmat/oath/hotp
 
 The ``cryptography`` open source project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
cgit v1.2.3