← Back to branch summary

~ubuntu-branches/debian/sid/botan/sid

« back to all changes in this revision

Viewing changes to doc/manual/otp.rst

  • Committer: Package Import Robot
  • Author(s): Laszlo Boszormenyi (GCS)
  • Date: 2018-03-01 22:23:25 UTC
  • mfrom: (1.2.2)
  • Revision ID: package-import@ubuntu.com-20180301222325-7p7vc45gu3hta34d
Tags: 2.4.0-2
* Don't remove .doctrees from the manual if it doesn't exist.
* Don't specify parallel to debhelper.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/manual/otp.rst
 
1
One Time Passwords
 
2
========================
 
3
 
 
4
One time password schemes are a user authentication method that relies on a
 
5
fixed secret key which is used to derive a sequence of short passwords, each of
 
6
which is accepted only once. Commonly this is used to implement two-factor
 
7
authentication (2FA), where the user authenticates using both a conventional
 
8
password (or a public key signature) and an OTP generated by a small device such
 
9
as a mobile phone.
 
10
 
 
11
Botan implements the HOTP and TOTP schemes from RFC 4226 and 6238.
 
12
 
 
13
Since the range of possible OTPs is quite small, applications must rate limit
 
14
OTP authentication attempts to some small number per second. Otherwise an attacker
 
15
could quickly try all 1000000 6-digit OTPs in a brief amount of time.
 
16
 
 
17
HOTP
 
18
^^^^^^
 
19
 
 
20
HOTP generates OTPs that are a short numeric sequence, between 6 and 8 digits
 
21
(most applications use 6 digits), created using the HMAC of a 64-bit counter
 
22
value. If the counter ever repeats the OTP will also repeat, thus both parties
 
23
must assure the counter only increments and is never repeated or
 
24
decremented. Thus both client and server must keep track of the next counter
 
25
expected.
 
26
 
 
27
Anyone with access to the client-specific secret key can authenticate as that
 
28
client, so it should be treated with the same security consideration as would be
 
29
given to any other symmetric key or plaintext password.
 
30
 
 
31
.. cpp:class:: HOTP
 
32
 
 
33
    Implement counter-based OTP
 
34
 
 
35
    .. cpp:function:: HOTP(const SymmetricKey& key, const std::string& hash_algo = "SHA-1", size_t digits = 6)
 
36
 
 
37
       Initialize an HOTP instance with a secret key (specific to each client),
 
38
       a hash algorithm (must be SHA-1, SHA-256, or SHA-512), and the number of
 
39
       digits with each OTP (must be 6, 7, or 8).
 
40
 
 
41
       In RFC 4226, HOTP is only defined with SHA-1, but many HOTP
 
42
       implementations support SHA-256 as an extension. The collision attacks
 
43
       on SHA-1 do not have any known effect on HOTP's security.
 
44
 
 
45
    .. cpp:function:: uint32_t generate_hotp(uint64_t counter)
 
46
 
 
47
       Return the OTP assosciated with a specific counter value.
 
48
 
 
49
    .. cpp:function:: std::pair<bool,uint64_t> verify_hotp(uint32_t otp, \
 
50
                      uint64_t starting_counter, size_t resync_range = 0)
 
51
 
 
52
       Check if a provided OTP matches the one that should be generated for
 
53
       the specified counter.
 
54
 
 
55
       The *starting_counter* should be the counter of the last successful
 
56
       authentication plus 1. If *resync_resync* is greater than 0, some number
 
57
       of counter values above *starting_counter* will also be checked if
 
58
       necessary. This is useful for instance when a client mistypes an OTP on
 
59
       entry; the authentication will fail so the server will not update its
 
60
       counter, but the client device will subsequently show the OTP for the
 
61
       next counter. Depending on the environment a *resync_range* of 3 to 10
 
62
       might be appropriate.
 
63
 
 
64
       Returns a pair of (is_valid,next_counter_to_use). If the OTP is invalid
 
65
       then always returns (false,starting_counter), since the last successful
 
66
       authentication counter has not changed.
 
67