Merge pull request #1990 from tonyseek/key-uri

Add "get_provisioning_uri" utility for HOTP/TOTP.

1 files changed, 41 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst
index dd3e0250..f49d02f9 100644
--- a/docs/hazmat/primitives/twofactor.rst
+++ b/docs/hazmat/primitives/twofactor.rst
@@ -74,6 +74,15 @@ 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)
+
+        :param str account_name: The display name of account, such as
+            ``'Alice Smith'`` or ``'alice@example.com'``.
+        :param issuer: The optional display name of issuer.
+        :type issuer: `string` or `None`
+        :param int counter: The current value of counter.
+        :return str: An URI string.
+
 Throttling
 ~~~~~~~~~~
 
@@ -171,3 +180,35 @@ 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)
+
+        :param str account_name: The display name of account, such as
+            ``'Alice Smith'`` or ``'alice@example.com'``.
+        :param issuer: The optional display name of issuer.
+        :type issuer: `string` or `None`
+        :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`_. It is widely supported by web
+sites and mobile applications which are 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.
+
+.. _`spec of Google Authenticator`: https://github.com/google/google-authenticator/wiki/Key-Uri-Format