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.