diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 13 | ||||
| -rw-r--r-- | docs/hazmat/primitives/twofactor.rst | 47 |
2 files changed, 53 insertions, 7 deletions
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 47486895..309c6fd0 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -240,7 +240,7 @@ Modes **This mode does not require padding.** - :param bytes nonce: Should be :doc:`random bytes </random-numbers>`. It is + :param bytes nonce: Should be unique, a :term:`nonce`. It is critical to never reuse a ``nonce`` with a given key. Any reuse of a nonce with the same key compromises the security of every message encrypted with that key. Must be the same number of bytes as the @@ -305,12 +305,11 @@ Modes **This mode does not require padding.** - :param bytes initialization_vector: Must be :doc:`random bytes - </random-numbers>`. They do not need to be kept secret and they can be - included in a transmitted message. NIST `recommends a 96-bit IV - length`_ for performance critical situations but it can be up to - 2\ :sup:`64` - 1 bits. Do not reuse an ``initialization_vector`` with a - given ``key``. + :param bytes initialization_vector: Must be unique, a :term:`nonce`. + They do not need to be kept secret and they can be included in a + transmitted message. NIST `recommends a 96-bit IV length`_ for + performance critical situations but it can be up to 2\ :sup:`64` - 1 + bits. Do not reuse an ``initialization_vector`` with a given ``key``. .. note:: diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index dd3e0250..df70a58a 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -74,6 +74,18 @@ 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 account_name: The display name of account, such as + ``'Alice Smith'`` or ``'alice@example.com'``. + :type account_name: :term:`text` + :param issuer: The optional display name of issuer. This is typically + the provider or service the user wants to access using the OTP + token. + :type issuer: :term:`text` or `None` + :param int counter: The current value of counter. + :return: A URI string. + Throttling ~~~~~~~~~~ @@ -171,3 +183,38 @@ 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 account_name: The display name of account, such as + ``'Alice Smith'`` or ``'alice@example.com'``. + :type: :term:`text` + :param issuer: The optional display name of issuer. This is typically + the provider or service the user wants to access using the OTP + token. + :type issuer: :term:`text` or `None` + :return: A 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 |