diff options
Diffstat (limited to 'docs/hazmat/primitives/twofactor.rst')
| -rw-r--r-- | docs/hazmat/primitives/twofactor.rst | 75 |
1 files changed, 51 insertions, 24 deletions
diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index df70a58a..51625dfc 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -18,14 +18,15 @@ codes (HMAC). .. currentmodule:: cryptography.hazmat.primitives.twofactor.hotp -.. class:: HOTP(key, length, algorithm, backend) +.. class:: HOTP(key, length, algorithm, backend, enforce_key_length=True) .. versionadded:: 0.3 HOTP objects take a ``key``, ``length`` and ``algorithm`` parameter. The ``key`` should be :doc:`randomly generated bytes </random-numbers>` 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. + recommended to be 160 :term:`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`. @@ -35,23 +36,34 @@ codes (HMAC). >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives.twofactor.hotp import HOTP >>> from cryptography.hazmat.primitives.hashes import SHA1 - >>> key = os.urandom(16) + >>> key = os.urandom(20) >>> hotp = HOTP(key, 6, SHA1(), backend=default_backend()) >>> hotp_value = hotp.generate(0) >>> hotp.verify(hotp_value, 0) - :param bytes key: Per-user secret key. This value must be kept secret - and be at least 128 bits. It is recommended that the - key be 160 bits. + :param key: Per-user secret key. This value must be kept secret + and be at least 128 :term:`bits`. It is recommended that + the key be 160 bits. + :type key: :term:`bytes-like` :param int length: Length of generated one time password as ``int``. :param cryptography.hazmat.primitives.hashes.HashAlgorithm algorithm: A :class:`~cryptography.hazmat.primitives.hashes` - provider. + instance. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` - provider. + instance. + :param enforce_key_length: A boolean flag defaulting to True that toggles + whether a minimum key length of 128 :term:`bits` is enforced. This + exists to work around the fact that as documented in `Issue #2915`_, + the Google Authenticator PAM module by default generates 80 bit keys. + If this flag is set to False, the application develop should implement + additional checks of the key length before passing it into + :class:`~cryptography.hazmat.primitives.twofactor.hotp.HOTP`. + + .. versionadded:: 1.5 + :raises ValueError: This is raised if the provided ``key`` is shorter than - 128 bits or if the ``length`` parameter is not 6, 7 or 8. + 128 :term:`bits` or if the ``length`` parameter is not 6, 7 or 8. :raises TypeError: This is raised if the provided ``algorithm`` is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or @@ -76,6 +88,8 @@ codes (HMAC). .. method:: get_provisioning_uri(account_name, counter, issuer) + .. versionadded:: 1.0 + :param account_name: The display name of account, such as ``'Alice Smith'`` or ``'alice@example.com'``. :type account_name: :term:`text` @@ -127,7 +141,7 @@ similar to the following code. .. currentmodule:: cryptography.hazmat.primitives.twofactor.totp -.. class:: TOTP(key, length, algorithm, time_step, backend) +.. class:: TOTP(key, length, algorithm, time_step, backend, enforce_key_length=True) TOTP objects take a ``key``, ``length``, ``algorithm`` and ``time_step`` parameter. The ``key`` should be :doc:`randomly generated bytes @@ -144,25 +158,35 @@ similar to the following code. >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives.twofactor.totp import TOTP >>> from cryptography.hazmat.primitives.hashes import SHA1 - >>> key = os.urandom(16) + >>> key = os.urandom(20) >>> totp = TOTP(key, 8, SHA1(), 30, backend=default_backend()) >>> time_value = time.time() >>> totp_value = totp.generate(time_value) >>> totp.verify(totp_value, time_value) - :param bytes key: Per-user secret key. This value must be kept secret - and be at least 128 bits. It is recommended that the - key be 160 bits. + :param key: Per-user secret key. This value must be kept secret + and be at least 128 :term:`bits`. It is recommended that the + key be 160 bits. + :type key: :term:`bytes-like` :param int length: Length of generated one time password as ``int``. :param cryptography.hazmat.primitives.hashes.HashAlgorithm algorithm: A :class:`~cryptography.hazmat.primitives.hashes` - provider. + instance. :param int time_step: The time step size. The recommended size is 30. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` - provider. + instance. + :param enforce_key_length: A boolean flag defaulting to True that toggles + whether a minimum key length of 128 :term:`bits` is enforced. This exists to + work around the fact that as documented in `Issue #2915`_, the + Google Authenticator PAM module by default generates 80 bit keys. If + this flag is set to False, the application develop should implement + additional checks of the key length before passing it into + :class:`~cryptography.hazmat.primitives.twofactor.totp.TOTP`. + + .. versionadded:: 1.5 :raises ValueError: This is raised if the provided ``key`` is shorter than - 128 bits or if the ``length`` parameter is not 6, 7 or 8. + 128 :term:`bits` or if the ``length`` parameter is not 6, 7 or 8. :raises TypeError: This is raised if the provided ``algorithm`` is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or @@ -186,9 +210,11 @@ similar to the following code. .. method:: get_provisioning_uri(account_name, issuer) + .. versionadded:: 1.0 + :param account_name: The display name of account, such as ``'Alice Smith'`` or ``'alice@example.com'``. - :type: :term:`text` + :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. @@ -198,11 +224,11 @@ similar to the following code. 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. +The provisioning URI of HOTP and TOTP is a `feature of Google Authenticator`_ +and not actually part of the HOTP or TOTP RFCs. However, 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`` +For generating a provisioning URI you can use the ``get_provisioning_uri`` method of HOTP/TOTP instances. .. code-block:: python @@ -217,4 +243,5 @@ method of HOTP/TOTP instances. 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 +.. _`feature of Google Authenticator`: https://github.com/google/google-authenticator/wiki/Key-Uri-Format +.. _`Issue #2915`: https://github.com/pyca/cryptography/issues/2915 |