Document the notion of time-steps

[vemv]

Hi Suvash,

first of all thanks for the library! Kudos for the great work.

I'm wondering what the :time-step option does.

Actually, I got a rough idea:

one-time.totp> (counter-since-epoch (Date.) 40)
38697200
one-time.totp> (counter-since-epoch (Date.) 20)
77394401
one-time.totp> (counter-since-epoch (Date.) 30)
51596267

So, it divides the time in chunks.

But I don't know the purpose of this? What would be a use case for setting a :time-step value other than 30? And what's the current effect of the default value of 30?

Thanks - Victor

[suvash]

Hi Victor,
Thanks for the question.

For the TOTP based password, each "time step" is a period of time where the server and client calculate the tokens(password). Once the period passes, it steps into a new period and now a new token need to be calculated/compared.

For eg. if the period(time step) was of 1 second, the tokens would have to calculated each new second. This would be too short of a time for the user to enter the password on the client and have it compared on the server.

The idea is to have a long enough period(time step) so that the client+user+server+network+etc. have enough time to compare the tokens without recalculations happening. As of now, it's an industry wide standard to use 30 seconds for this (though, not a requirement as long as your client is not hardcoded to 30 secs). Thus, new tokens are generated/calculated every 30 seconds.
Of course, If your use case requires a longer waiting time, you are free to customize it.

Another thing to remember is that since TOTP is based on time, and clocks on various devices are not necessarily in sync, it's all fairly popular to calculate 1 time step prior and 1 time step after to allow for this deviation. That way you have 3 tokens (1 from current time-step t, 1 from t-1, 1 from t+1)

Hope that clarifies.