Danger
This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.
This module contains algorithms related to two-factor authentication.
Currently, it contains an algorithm for generating and verifying one time password values based on Hash-based message authentication codes (HMAC).
This is raised when the verify method of a one time password function’s computed token does not match the expected token.
New in version 0.3.
HOTP objects take a key, length and algorithm parameter. The key 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 must be >= 6 and <= 8.
This is an implementation of RFC 4226.
>>> import os
>>> 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(20)
>>> hotp = HOTP(key, 6, SHA1(), backend=default_backend())
>>> hotp_value = hotp.generate(0)
>>> hotp.verify(hotp_value, 0)
Parameters: |
|
---|---|
Raises: |
|
Parameters: | counter (int) – The counter value used to generate the one time password. |
---|---|
Return bytes: | A one time password value. |
Parameters: |
|
---|---|
Raises cryptography.hazmat.primitives.twofactor.InvalidToken: | |
This is raised when the supplied HOTP does not match the expected HOTP. |
New in version 1.0.
Parameters: | |
---|---|
Returns: | A URI string. |
Due to the fact that the HOTP algorithm generates rather short tokens that are 6 - 8 digits long, brute force attacks are possible. It is highly recommended that the server that validates the token implement a throttling scheme that locks out the account for a period of time after a number of failed attempts. The number of allowed attempts should be as low as possible while still ensuring that usability is not significantly impacted.
The server’s counter value should only be incremented on a successful HOTP authentication. However, the counter on the client is incremented every time a new HOTP value is requested. This can lead to the counter value being out of synchronization between the client and server.
Due to this, it is highly recommended that the server sets a look-ahead window that allows the server to calculate the next x HOTP values and check them against the supplied HOTP value. This can be accomplished with something similar to the following code.
def verify(hotp, counter, look_ahead):
assert look_ahead >= 0
correct_counter = None
otp = HOTP(key, 6, default_backend())
for count in range(counter, counter + look_ahead):
try:
otp.verify(hotp, count)
correct_counter = count
except InvalidToken:
pass
return correct_counter
TOTP objects take a key, length, algorithm and time_step parameter. The key should be randomly generated bytes and is recommended to be as long as your hash function’s output (e.g 256-bit for SHA256). The length parameter controls the length of the generated one time password and must be >= 6 and <= 8.
This is an implementation of RFC 6238.
>>> import os
>>> import time
>>> 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(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)
Parameters: |
|
---|---|
Raises: |
|
Parameters: | time (int) – The time value used to generate the one time password. |
---|---|
Return bytes: | A one time password value. |
Parameters: |
|
---|---|
Raises cryptography.hazmat.primitives.twofactor.InvalidToken: | |
This is raised when the supplied TOTP does not match the expected TOTP. |
New in version 1.0.
Parameters: |
|
---|---|
Type: | |
Returns: | A URI string. |
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.
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.