# `TOTP` Tutorial

## Overview

The `passlib.totp` module provides a set of classes for adding two-factor authentication (2FA) support into your application, using the widely supported TOTP specification (RFC 6238).

This module is based around the `TOTP` class, which supports a wide variety of use-cases, including:

> - Creating & transferring configured TOTP keys to client devices.

> - Generating & verifying tokens.

> - Securely storing configured TOTP keys.

See also

The `passlib.totp` API reference, which lists all details of all the classes and methods mentioned here.

## Walkthrough

There are a number of different ways to integrate TOTP support into a server application. The following is a general outline of one of way to do this. Some details and alternate choices are omitted for brevity, see the remaining sections of this tutorial for more detailed information about these steps.

### 1. Generate an Application Secret

First, generate a strong application secret to use when encrypting TOTP keys for storage. Passlib offers a `generate_secret()` method to help with this:

    >>> from passlib.totp import generate_secret
    >>> generate_secret()
    'pO7SwEFcUPvIDeAJr7INBj0TjsSZJr1d2ddsFL9r5eq'

This key should be assigned a numeric tag (e.g. “1”, a timestamp, or an iso date such as “2016-11-10”); and should be stored in a file separate from your application’s configuration. Ideally, after this file has been loaded by the TOTP constructor below, the application should give up access permissions to the file.

Example file contents:

    2016-11-10: pO7SwEFcUPvIDeAJr7INBj0TjsSZJr1d2ddsFL9r5eq

This key will be used in a later step to encrypt TOTP keys for storage in your database. The sequential tag is used so that if your database (or the application secrets) are ever compromised, you can add a new application secret (with a newer tag), and gracefully migrate the compromised TOTP keys.

See also

For more details see Application Secrets (below).

### 2. TOTP Factory Initialization

When your application is being initialized, create a TOTP factory which is configured for your application, and is set up to use the application secrets defined in step 1. You can also set a default issuer here, instead of having to provide one explicitly in step 4:

    >>> from passlib.totp import TOTP
    >>> TotpFactory = TOTP.using(secrets_path='/path/to/secret/file/in/step/1',
    ...                          issuer="myapp.example.org")

The `TotpFactory` object returned by `TOTP.using()` is actually a subclass of `TOTP` itself, and has the same methods and attributes. The main difference is that (because an application secret has been provided), the TOTP key will automatically be encrypted / decrypted when serializing the object to disk.

See also

For more details see Creating TOTP Instances (below).

### 3. Rate-Limiting & Cache Initialization

As part of your application initialization, it critically important to set up infrastructure to rate limit how many token verification attempts a user / ip address is allowed to make, otherwise TOTP can be bypassed.

See also

For more details see Why Rate-Limiting is Critical (below)

It’s also strongly recommended to set up a per-user cache which can store the last matched TOTP counter (an integer) for a period of a few minutes (e.g. using dogpile.cache, memcached, redis, etc). This cache is used by later steps to protect your application during a narrow window of time where TOTP would otherwise be vulnerable to a replay attack.

See also

For more details see Preventing Token Reuse (below)

### 4. Setting up TOTP for a User

To set up TOTP for a new user: create a new TOTP object and key using `TOTP.new()`. This can then be rendered into a provisioning URI, and transferred to the user’s TOTP client of choice.

Rendering to a provisioning URI using `TOTP.to_uri()` requires picking an “issuer” string to uniquely identify your application, and a “label” string to uniquely identify the user. The following example creates a new TOTP instance with a new key, and renders it to a URI, plugging in application-specific information.

Using the `TotpFactory` object set up in step 2:

    >>> totp = TotpFactory.new()
    >>> uri = totp.to_uri(issuer="myapp.example.org", label="username")
    >>> uri
    'otpauth://totp/username?secret=D6RZI4ROAUQKJNAWQKYPN7W7LNV43GOT&issuer=myapp.example.org'

This URI is generally passed to a QRCode renderer, though as fallback it’s recommended to also display the key using `TOTP.pretty_key()`.

See also

For more details, and more about QR Codes, see Configuring Clients (below).

### 5. Storing the TOTP object

Before enabling TOTP for the user’s account, it’s good practice to first have the user successfully verify a token (per step 6); thus confirming their client h as been correctly configured.

Once this is done, you can store the TOTP object in your database. This can be done via the `TOTP.to_json()` method:

    >>> totp.to_json()
    '{"enckey":{"c":14,"k":"FLEQC3VO6SIT3T7GN2GIG6ONPXADG5CZ","s":"UL2J4MZG4SONHOWXLKFQ","t":"1","v":1},"type":"totp","v":1}'

Note that if there is no application secret configured, the key will not be encrypted, and instead look like this:

    >>> totp.to_json()
    '{"key":"D6RZI4ROAUQKJNAWQKYPN7W7LNV43GOT","type":"totp","v":1}'

To ensure you always save an encrypted token, you can use `totp.to_json(encrypted=True)`.

See also

For more details see Storing TOTP instances

### 6. Verifying a Token

Whenever attempting to verify a token provided by the user, first load the serialized TOTP object from the database (stored step 5), as well as the last counter value from the cache (set up in step 3). You should use these values to call the `TOTP.verify()` method.

If verify() succeeds, it will return a `TotpMatch` object. This object contains information about the match, including `TotpMatch.counter` (a time-dependant integer tied to this token), and `TotpMatch.cache_seconds` (minimum time this counter should be cached).

If verify() fails, it will raise one of the `passlib.exc.TokenError` subclasses indicating what went wrong. This will be one of three cases: the token was malformed (e.g. too few digits), the token was invalid (didn’t match), or a recent token was reused.

A skeleton example of how this should function:

    >>> from passlib.exc import TokenError, MalformedTokenError

    >>> # pull information from your application
    >>> token = # ... token string provided by user ...
    >>> source = # ... load totp json string from database ...
    >>> last_counter = # ... load counter value from cache ...

    >>> # ... check attempt rate limit for this account / address (per step 3 above) ...

    >>> # using the TotpFactory object defined in step 2, invoke verify
    >>> try:
    ...     match = TotpFactory.verify(token, source, last_counter=last_counter)
    ... except MalformedTokenError as err:
    ...     # --- malformed token ---
    ...     # * inform user, e.g. by displaying str(err)
    ... except TokenError as err:
    ...     # --- invalid or reused token ---
    ...     # * add to rate limit counter
    ...     # * inform user, e.g. by displaying str(err)
    ... else:
    ...     # --- successful match ---
    ...     # * reset rate-limit counter
    ...     # * store 'match.counter' in per-user cache for at least 'match.cache_seconds'

See also

For more details see Verifying Tokens (below)

#### Alternate Caching Strategy

As an alternative to storing `match.counter` in the cache, applications using a cache such as memcached may wish to simply set a key based on `user + token` for `match.cache_seconds`, and reject any tokens coming in for that user who are marked in the cache.

In that case, they should run the tokens through `TOTP.normalize_token()` first, to make sure the token strings are normalized before comparison. In this case, the skeleton example can be amended to:

    >>> # pull information from your application
    >>> token = # ... token string provided by user ...
    >>> source = # ... load totp json string from database ...
    >>> user_id = # ... user identifier for cache

    >>> # ... check attempt rate limit for this account / address (per step 3 above) ...

    >>> # check token format
    >>> try:
    ...     token = TotpFactory.normalize_token(token)
    ... except MalformedTokenError as err:
    ...     # --- malformed token ---
    ...     # * inform user, e.g. by displaying str(err)
    ...     return

    >>> # check if token has been used, using app-defined present_in_cache() helper
    >>> cache_key = "totp-token-%s-%s" % (user_id, token)
    >>> if present_in_cache(cache_key):
    ...     # * add to rate limit counter
    ...     # * present 'token already used' message
    ...     return

    >>> # using the TotpFactory object defined in step 2, invoke verify
    >>> try:
    ...     match = TotpFactory.verify(token, source)
    ... except TokenError as err:
    ...     # --- invalid token ---
    ...     # * add to rate limit counter
    ...     # * inform user, e.g. by displaying str(err)
    ... else:
    ...     # --- successful match ---
    ...     # * reset rate-limit counter
    ...     # * set 'cache_key' in per-user cache for at least 'match.cache_seconds'

### 7. Reserializing Existing Objects

An organization’s security policy may require that a developer periodically change the application secret key used to decrypt/encrypt TOTP objects. Alternately, the application secret may become compromised.

In either case, a new application secret will need to be created, and a new tag assigned (per step 1). Any deprecated secret(s) will need to be retained in the collection passed to the `TotpFactory`, in order to be able to decrypt existing TOTP objects.

Note

You can verify which secret is will be used to encrypt new keys by inspecting `tag = TotpFactory.wallet.default_tag`.

Once the new secret has been added, you will need to update all the serialized TOTP objects in the database, decrypting them using the old secret, and encrypting them with the new one.

This can be done in a few ways. The following skeleton example gives a simple loop that can be used, which would ideally be run in a process that’s separate from your normal application:

    >>> # presuming query_user_totp() queries your database for all user rows,
    >>> # and update_user_totp() updates a specific row.
    >>> for user_id, totp_source in query_user_totp():
    >>>     totp = TotpFactory.from_source(totp_source)
    >>>     if totp.changed:
    >>>         update_user_totp(user_id, totp.to_json())

This uses the `TOTP.changed` attribute, which is set to `True` if `TOTP.from_source()` (or other constructor) detects the source data is encrypted with an old secret, is using outdated encryption settings, or is stored in deprecated serialization format.

Some refinements that may need to be made for specific situations:

- For applications with a large number of users, it may be faster to accumulate `(user_id, totp.to_json())` pairs in a buffer, and do a bulk SQL update once every 100-1000 rows.

- Depending on the dbapi layer in use, it may take care of JSON serialization for you, in which case you’ll need to use `totp.to_dict()` instead of `totp.to_json()`.

Once all references to a deprecated secret have been replaced, it can be removed from the secrets file.

See also

For more details see Step 1 (above), or Application Secrets (below)

## Creating TOTP Instances

### Direct Creation

Creating TOTP instances is straightforward: The `TOTP` class can be called directly to constructor a TOTP instance from it’s component configuration:

    >>> from passlib.totp import TOTP
    >>> totp = TOTP(key='GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM', digits=9)
    >>> totp.generate()
    '29387414'

You can also use a number of the alternate constructors, such as `TOTP.new()` or `TOTP.from_source()`:

    >>> # create new instance w/ automatically generated key
    >>> totp = TOTP.new()

    >>> # or deserializing it from a string (e.g. the output of TOTP.to_json)
    >>> totp = TOTP.from_source('{"key":"D6RZI4ROAUQKJNAWQKYPN7W7LNV43GOT","type":"totp","v":1}')

Once created, you can inspect the object for it’s configuration and key:

    >>> otp.base32_key
    'GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM'
    >>> otp.alg
    "sha1"
    >>> otp.period
    30

If you want a non-standard alg or period, you can specify it via the constructor. You can also create TOTP instances from an existing key (see the `TOTP` constructor’s `key` and `format` options for more details):

    >>> otp2 = TOTP(new=True, period=60, alg="sha256")
    >>> otp2.alg
    'sha256'
    >>> otp2.period
    60

    >>> otp3 = TOTP(key='GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM')

### Using a Factory

Most applications will have some default configuration which they want all TOTP instances to have. This includes application secrets (for encrypting TOTP keys for storage), or setting a default issuer label (for rendering URIs).

Instead of having to call the `TOTP` constructor each time and provide all these options, you can use the `TOTP.using()` method. This method takes in a number of the same options as the TOTP constructor, and returns a `TOTP` subclass which has these options pre-programmed in as defaults:

    >>> # here we create a TOTP factory with a random encryption secret and a default issuer
    >>> from passlib.totp import TOTP, generate_secret
    >>> TotpFactory = TOTP.using(issuer="myapp.example.org", secrets={"1": generate_secret()})

Since this object is a subclass of `TOTP`, you can use all it’s normal methods. The difference is that it will integrate the information provided by using():

    >>> totp = TotpFactory.new()
    >>> totp.issuer
    'myapp.example.org'

    >>> totp.to_json()
    '{"enckey":{"c":14,"k":"FLEQC3VO6SIT3T7GN2GIG6ONPXADG5CZ","s":"UL2J4MZG4SONHOWXLKFQ","t":"1","v":1},"type":"totp","v":1}'

In typical usage, a server application will want to create a TotpFactory as part of it’s initialization, and then use that class for all operations, instead of referencing `TOTP` directly.

See also

- Configuring Clients for details about the `issuer` option

- Storing TOTP instances for details about storage and key encryption

## Configuring Clients

Once a TOTP instance & key has been generated on the server, it needs to be transferred to the client TOTP program for installation. This can be done by having the user manually type the key into their TOTP client, but an easier method is to render the TOTP configuration to a URI stored in a QR Code.

### Rendering URIs

The KeyUriFormat is a de facto standard for encoding TOTP keys & configuration information into a string. Once the URI is rendered as a QR Code, it can easily be imported into many smartphone clients (such as Authy and Google Authenticator) via the smartphone’s camera.

When transferring the TOTP configuration this way, you will need to provide unique identifiers for both your application, and the user’s account. This allows TOTP clients to distinguish this key from the others in it’s database. This can be done via the `issuer` and `label` parameters of the `TOTP.to_uri()` method.

The `issuer` string should be a globally unique label for your application (e.g. it’s domain name). Since the issuer string shouldn’t change across users, you can create a customized TOTP factory, and provide it with a default issuer. (If you skip this step, the issuer will need to be provided at every `TOTP.to_uri()` call):

    >>> from passlib.totp import TOTP
    >>> TotpFactory = TOTP.using(issuer="myapp.example.org")

Once this is done, rendering to a provisioning URI just requires picking a `label` for the URI. This label should identify the user within your application (e.g. their login or their email):

    >>> # assume an existing TOTP instance has been created
    >>> totp = TotpFactory.new()

    >>> # serialize the object to a URI, along with label for user
    >>> uri = totp.to_uri(label="demo-user")
    >>> uri
    'otpauth://totp/demo-user?secret=GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM&issuer=myapp.example.org'

### Rendering QR Codes

This URI can then be encoded as a QR Code, using various python & javascript qrcode libraries. As an example, the following uses PyQrCode to render the URI to the console as a text-based QR code:

    >>> import pyqrcode
    >>> uri = totp.to_uri(label="demo-user")
    >>> print(pyqrcode.create(uri).terminal(quiet_zone=1))
    ... very large ascii-art qrcode here...

As a fallback to the QR Code, it’s recommended to alternately / also display the key itself, so that users with camera-less TOTP clients can still enter it. The `TOTP.pretty_key()` method is provided to help with this:

    >>> totp.pretty_key()
    'D6RZ-I4RO-AUQK-JNAW-QKYP-N7W7-LNV4-3GOT'

Note that if you use a non-default `alg`, `digits`, or `period` values, these should also be displayed next to the key.

### Parsing URIs

On the client side, passlib offers the `TOTP.from_uri()` constructor creating a TOTP object from a provisioning URI. This can also be useful for testing URI encoding & output during development:

    >>> # create new TOTP instance from a provisioning uri:
    >>> from passlib.totp import TOTP
    >>> totp = TOTP.from_uri('otpauth://totp/demo-user?secret=GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM&issuer=myapp.example.org')
    >>> otp.base32_key
    'GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM'
    >>> otp.alg
    "sha1"
    >>> otp.period
    30
    >>> otp.generate().token
    '897453'

## Storing TOTP instances

Once a TOTP object has been created, it inevitably needs to be stored in a database. Using `to_uri()` to serialize it to a URI has a few disadvantages - it always includes an issuer & a label (wasting storage space), and it stores the key in an unencrypted format.

### JSON Serialization

To help with this passlib offers a way to serialize TOTP objects to and from a simple JSON format, which can optionally encrypt the keys for storage.

To serialize a TOTP object to a string, use `TOTP.to_json()`:

    >>> from passlib.totp import TOTP
    >>> totp = TOTP.new()
    >>> data = totp.to_json()
    >>> data
    '{"key":"GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM","type":"totp","v":1}'

This string can be stored in a database, and then deserialized as needed using the `TOTP.from_json()` constructor:

    >>> totp2 = TOTP.from_json(data)
    >>> totp2.base32_key
    'GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM'

There are also corresponding `TOTP.to_dict()` and `TOTP.from_dict()` methods for applications that want to serialize the object without converting it all the way into a JSON string.

Caution

The above procedure should only be used for development purposes, as it will NOT encrypt the keys; and the IETF strongly recommends encrypting the keys for storage (RFC-6238 sec 5.1). Encrypting the keys is covered below.

### Application Secrets

The one thing lacking about the example above is that the resulting data contained the plaintext key. If the server were compromised, the TOTP keys could be used directly to impersonate the user. To solve this, Passlib offers a method for providing an application-wide secret that `TOTP.to_json()` will use to encrypt keys.

Per Step 1 of the walkthrough (above), applications can use the `generate_secret()` helper to create new secrets. All existing secrets (the current one, and any deprecated / compromised ones) should be assigned an identifying tag, and stored in a dict or file.

Ideally, these secrets should be stored in a location which the application’s process does not have access to once it has been initialized. Once this data is loaded, applications can create a factory function using `TOTP.using()`, and provide these secrets as part of it’s arguments. This can take the form of a file path, a loaded string, or a dictionary:

    >>> # load from dict
    >>> from passlib.totp import TOTP
    >>> TotpFactory = TOTP.using(secrets={"1": "'pO7SwEFcUPvIDeAJr7INBj0TjsSZJr1d2ddsFL9r5eq'"})

    >>> # load from filepath
    >>> TotpFactory = TOTP.using(secrets_path="/path/to/secret/file")

The `secrets` and `secrets_path` values can be anything accepted by the `AppWallet` constructor (the internal class that’s used to load & store the application secrets in memory). An instance of this object is accessible for inspection from the `TOTP.wallet` attribute of each factory:

    >>> TotpFactory.wallet
    <passlib.totp.AppWallet at 0x2ba5310>

### Encrypting Keys

Once you have a TOTP factory configured with one or more application secrets, any objects you create through the factory will automatically have access to the application secrets, and will use them to encrypt the key when serializing to json.

Assuming `TotpFactory` is set up from the previous step, contrast the output of this with the plain JSON serialization example above:

    >>> totp = TotpFactory.new()
    >>> data = totp.to_json()
    >>> data
    '{"enckey":{"c":14,"k":"FLEQC3VO6SIT3T7GN2GIG6ONPXADG5CZ","s":"UL2J4MZG4SONHOWXLKFQ","t":"1","v":1},"type":"totp","v":1}'

This data can be stored in the database like normal, but will require access to the application secret in order to decrypt:

    >>> data = '{"enckey":{"c":14,"k":"FLEQC3VO6SIT3T7GN2GIG6ONPXADG5CZ","s":"UL2J4MZG4SONHOWXLKFQ","t":"1","v":1},"type":"totp","v":1}'
    >>> totp = TotpFactory.from_source(data)
    >>> totp.base32_key
    'FLEQC3VO6SIT3T7GN2GIG6ONPXADG5CZ'

Whereas trying to decode without a secret configured will result in:

    >>> totp = TOTP.from_source(data)
    ...
    TypeError: no application secrets present, can't decrypt TOTP key

Note that when loading TOTP objects this way, you can check the `TOTP.changed` attr to see if the object needs to be re-serialized (e.g. deprecated secret, too few encryption rounds, deprecated serialization format).

## Generating Tokens (Client-Side Only)

Finally, the whole point of TOTP: generating and verifying tokens. The TOTP protocol generates a new time & key -dependant token every <period> seconds (usually 30).

Generating a totp token is done with the `TOTP.generate()` method, which returns a `TotpToken` instance. This object looks and acts like a tuple of `(token, expire_time)`, but offers some additional informational attributes:

    >>> from passlib import totp
    >>> otp = TOTP(key='GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM')

    >>> # generate a TOTP token for the current timestamp
    >>> # (your output will vary based on system time)
    >>> otp.generate()
    <TotpToken token='589720' expire_time=1475342400>

    >>> # to get just the token, not the TotpToken instance...
    >>> otp.generate().token
    '359275'

    >>> # you can generate a token for a specific time as well...
    >>> otp.generate(time=1475338840).token
    '359275'

See also

For more details, see the `TOTP.generate()` method.

## Verifying Tokens

In order for successful authentication, the user must generate the token on the client, and provide it to your server before the `TOTP.period` ends.

Since this there will always be a little transmission delay (and sometimes client clock drift) TOTP verification usually uses a small verification window, allowing a user to enter a token a few seconds after the period has ended. This window is usually kept as small as possible, and in passlib defaults to 30 seconds.

### Match & Verify

To verify a token a user has provided, you can use the `TOTP.match()` method. If unsuccessful, a `passlib.exc.TokenError` subclass will be raised. If successful, this will return a `TotpMatch` instance, with details about the match. This object acts like a tuple of `(counter, timestamp)`, but offers some additional informational attributes:

    >>> # NOTE: all of the following was done at a fixed time, to make these
    >>> #       examples repeatable. in real-world use, you would omit the 'time' parameter
    >>> #       from all these calls.

    >>> # assuming TOTP key & config was deserialized from database store
    >>> from passlib import totp
    >>> otp = TOTP(key='GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM')

    >>> # user provides malformed token:
    >>> otp.match('359', time=1475338840)
    ...
    MalformedTokenError: Token must have exactly 6 digits

    >>> # user provides token that isn't valid w/in time window:
    >>> otp.match('123456', time=1475338840)
    ...
    InvalidTokenError: Token did not match

    >>> # user provides correct token
    >>> otp.match('359275', time=1475338840)
    <TotpMatch counter=49177961 time=1475338840 cache_seconds=60>

As a further optimization, the `TOTP.verify()` method allows deserializing and matching a token in a single step. Not only does this save a little code, it has a signature much more similar to that of Passlib’s `passlib.ifc.PasswordHash.verify()`.

Typically applications will provide the TOTP key in whatever format it’s stored by the server. This will usually be a JSON string (as output by `TOTP.to_json()`), but can be any format accepted by `TOTP.from_source()`. As an example:

    >>> # application loads json-serialized TOTP key
    >>> from passlib.totp import TOTP
    >>> totp_source = '{"v": 1, "type": "totp", "key": "otxl2f5cctbprpzx"}'

    >>> # parse & match the token in a single call
    >>> match = TOTP.verify('123456', totp_source)

See also

For more details, see the `TOTP.match()` and `TOTP.verify()` methods.

### Preventing Token Reuse

Even if an attacker is able to observe a user entering a TOTP token, it will do them no good once `period + window` seconds have passed (typically 60). This is because the current time will now have advanced far enough that `TOTP.match()` will never match against the stolen token.

However, this leaves a small window in which the attacker can observe and replay a token, successfully impersonating the user. To prevent this, applications are strongly encouraged to record the latest `TotpMatch.counter` value that’s returned by the `TOTP.match()` method.

This value should be stored per-user in a temporary cache for at least `period + window` seconds. (This is typically 60 seconds, but for an exact value, applications may check the `TotpMatch.cache_seconds` value returned by the `TOTP.match()` method).

Any subsequent calls to verify should check this cache, and pass in that value to `TOTP.match()`’s “last_counter” parameter (or `None` if no value found). Doing so will ensure that tokens can only be used once, preventing replay attacks.

As an example:

    >>> # NOTE: all of the following was done at a fixed time, to make these
    >>> #       examples repeatable. in real-world use, you would omit the 'time' parameter
    >>> #       from all these calls.

    >>> # assuming TOTP key & config was deserialized from database store
    >>> from passlib.totp import TOTP
    >>> otp = TOTP(key='GVDOQ7NP6XPJWE4CWCLFFSXZH6DTAZWM')

    >>> # retrieve per-user counter from cache
    >>> last_counter = ...consult application cache...

    >>> # if user provides valid value, a TotpMatch object will be returned.
    >>> # (if they provide an invalid value, a TokenError will be raised).
    >>> match = otp.match('359275', last_counter=last_counter, time=1475338830)
    >>> match.counter
    49177961
    >>> match.cache_seconds
    60

    >>> # application should now cache the new 'match.counter' value
    >>> # for at least 'match.cache_seconds'.

    >>> # now that last_counter has been properly updated: say that
    >>> # 10 seconds later attacker attempts to re-use token user just entered:
    >>> last_counter = 49177961
    >>> match = otp.match('359275', last_counter=last_counter, time=1475338840)
    ...
    UsedTokenError: Token has already been used, please wait for another.

See also

For more details, see the `TOTP.match()` method; for more examples, see Step 6 above.

### Why Rate-Limiting is Critical

The `TOTP.match()` method offers a `window` parameter, expanding the search range to account for the client getting slightly out of sync.

While it’s tempting to be user-friendly, and make this window as large as possible, there is a security downside: Since any token within the window will be treated as valid, the larger you make the window, the more likely it is that an attacker will be able to guess the correct token by random luck.

Because of this, it’s critical for applications implementing OTP to rate-limit the number of attempts on an account, since an unlimited number of attempts guarantees an attacker will be able to guess any given token.

The Gory Details

For TOTP, the formula is `odds = guesses * (1 + 2 * window / period) / 10**digits`; where `window` in this case is the `TOTP.match()` window (measured in seconds), and `period` is the number of seconds before the token is rotated.

This formula can be inverted to give the maximum window we want to allow for a given configuration, rate limit, and desired odds: `max_window = floor((odds * 10**digits / guesses - 1) * period / 2)`.

For example (assuming TOTP with 7 digits and 30 second period), if you want an attacker’s odds to be no better than 1 in 10000, and plan to lock an account after 4 failed attempts – the maximum window you should use would be `floor((1/10000 * 10**6 / 4 - 1) * 30 / 2)` or 360 seconds.