diff options
Diffstat (limited to 'comm/third_party/botan/doc/api_ref/otp.rst')
-rw-r--r-- | comm/third_party/botan/doc/api_ref/otp.rst | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/comm/third_party/botan/doc/api_ref/otp.rst b/comm/third_party/botan/doc/api_ref/otp.rst new file mode 100644 index 0000000000..133201b4e6 --- /dev/null +++ b/comm/third_party/botan/doc/api_ref/otp.rst @@ -0,0 +1,98 @@ +One Time Passwords +======================== + +.. versionadded:: 2.2.0 + +One time password schemes are a user authentication method that relies on a +fixed secret key which is used to derive a sequence of short passwords, each of +which is accepted only once. Commonly this is used to implement two-factor +authentication (2FA), where the user authenticates using both a conventional +password (or a public key signature) and an OTP generated by a small device such +as a mobile phone. + +Botan implements the HOTP and TOTP schemes from RFC 4226 and 6238. + +Since the range of possible OTPs is quite small, applications must rate limit +OTP authentication attempts to some small number per second. Otherwise an attacker +could quickly try all 1000000 6-digit OTPs in a brief amount of time. + +HOTP +^^^^^^ + +HOTP generates OTPs that are a short numeric sequence, between 6 and 8 digits +(most applications use 6 digits), created using the HMAC of a 64-bit counter +value. If the counter ever repeats the OTP will also repeat, thus both parties +must assure the counter only increments and is never repeated or +decremented. Thus both client and server must keep track of the next counter +expected. + +Anyone with access to the client-specific secret key can authenticate as that +client, so it should be treated with the same security consideration as would be +given to any other symmetric key or plaintext password. + +.. cpp:class:: HOTP + + Implement counter-based OTP + + .. cpp:function:: HOTP(const SymmetricKey& key, const std::string& hash_algo = "SHA-1", size_t digits = 6) + + Initialize an HOTP instance with a secret key (specific to each client), + a hash algorithm (must be SHA-1, SHA-256, or SHA-512), and the number of + digits with each OTP (must be 6, 7, or 8). + + In RFC 4226, HOTP is only defined with SHA-1, but many HOTP + implementations support SHA-256 as an extension. The collision attacks + on SHA-1 do not have any known effect on HOTP's security. + + .. cpp:function:: uint32_t generate_hotp(uint64_t counter) + + Return the OTP associated with a specific counter value. + + .. cpp:function:: std::pair<bool,uint64_t> verify_hotp(uint32_t otp, \ + uint64_t starting_counter, size_t resync_range = 0) + + Check if a provided OTP matches the one that should be generated for + the specified counter. + + The *starting_counter* should be the counter of the last successful + authentication plus 1. If *resync_resync* is greater than 0, some number + of counter values above *starting_counter* will also be checked if + necessary. This is useful for instance when a client mistypes an OTP on + entry; the authentication will fail so the server will not update its + counter, but the client device will subsequently show the OTP for the + next counter. Depending on the environment a *resync_range* of 3 to 10 + might be appropriate. + + Returns a pair of (is_valid,next_counter_to_use). If the OTP is invalid + then always returns (false,starting_counter), since the last successful + authentication counter has not changed. + + +TOTP +^^^^^^^^^^ + +TOTP is based on the same algorithm as HOTP, but instead of a counter a +timestamp is used. + +.. cpp:class:: TOTP + + .. cpp:function:: TOTP(const SymmetricKey& key, const std::string& hash_algo = "SHA-1", \ + size_t digits = 6, size_t time_step = 30) + + Setup to perform TOTP authentication using secret key *key*. + + .. cpp:function:: uint32_t generate_totp(std::chrono::system_clock::time_point time_point) + + .. cpp:function:: uint32_t generate_totp(uint64_t unix_time) + + Generate and return a TOTP code based on a timestamp. + + .. cpp:function:: bool verify_totp(uint32_t otp, std::chrono::system_clock::time_point time, \ + size_t clock_drift_accepted = 0) + + .. cpp:function:: bool verify_totp(uint32_t otp, uint64_t unix_time, \ + size_t clock_drift_accepted = 0) + + Return true if the provided OTP code is correct for the provided + timestamp. If required, use *clock_drift_accepted* to deal with + the client and server having slightly different clocks. |