Describe provisioning URI in the document.

1 files changed, 38 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst
index dd3e0250..dace6f7d 100644
--- a/docs/hazmat/primitives/twofactor.rst
+++ b/docs/hazmat/primitives/twofactor.rst
@@ -74,6 +74,14 @@ codes (HMAC).
         :raises cryptography.hazmat.primitives.twofactor.InvalidToken: This
              is raised when the supplied HOTP does not match the expected HOTP.
 
+    .. method:: get_provisioning_uri(account_name, counter, issuer=None)
+
+        :param str account_name: The display name of account, such as
+            ``'Alice Smith'`` or ``'alice@example.com'``.
+        :param str issuer: The optional display name of issuer.
+        :param int counter: The current value of counter.
+        :return str: An URI string.
+
 Throttling
 ~~~~~~~~~~
 
@@ -171,3 +179,33 @@ similar to the following code.
         :param int time: The time value to validate against.
         :raises cryptography.hazmat.primitives.twofactor.InvalidToken: This
              is raised when the supplied TOTP does not match the expected TOTP.
+
+    .. method:: get_provisioning_uri(account_name, issuer=None)
+
+        :param str account_name: The display name of account, such as
+            ``'Alice Smith'`` or ``'alice@example.com'``.
+        :param str issuer: The optional display name of issuer.
+        :return str: An URI string.
+
+Provisioning URI
+~~~~~~~~~~~~~~~~
+
+The provisioning URI of HOTP and TOTP is not actual the part of RFC 4226 and
+RFC 6238, but a `spec of Google Authenticator <http://git.io/vkvvY>`_. It is
+wide supported by web sites and mobile applications which using Two-Factor
+authentication.
+
+For generating a provisioning URI, you could use the ``get_provisioning_uri``
+method of HOTP/TOTP instances.
+
+.. code-block:: python
+
+    counter = 5
+    account_name = 'alice@example.com'
+    issuer_name = 'Example Inc'
+
+    hotp_uri = hotp.get_provisioning_uri(account_name, counter, issuer_name)
+    totp_uri = totp.get_provisioning_uri(account_name, issuer_name)
+
+A common usage is encoding the provisioning URI into QR code and guiding users
+to scan it with Two-Factor authentication applications in their mobile devices.