Skip to content

Commit 8782012

Browse files
marcelkliemannelmarcelkliemannel
committed
Improve README
1 parent 6e66e79 commit 8782012

File tree

1 file changed

+72
-39
lines changed

1 file changed

+72
-39
lines changed

‎README.md

+72-39
Original file line numberDiff line numberDiff line change
@@ -2,119 +2,152 @@
22

33
[![Build Status](https://travis-ci.org/marcelkliemannel/kotlin-onetimepassword.svg?branch=master)](https://travis-ci.org/marcelkliemannel/kotlin-onetimepassword)
44

5-
This is a Kotlin one-time password library to generate codes for:
6-
- Google Authenticator
7-
- Time-based One-time Password (TOTP)
8-
- HMAC-based One-time Password (HOTP)
5+
This is a Kotlin library to generate one-time password codes for:
6+
7+
* Google Authenticator
8+
* Time-Based One-Time Password (TOTP)
9+
* HMAC-Based One-Time Password (HOTP)
910

1011
The implementations are based on the RFCs:
11-
- RFC 4226 [HOTP: An HMAC-Based One-Time Password Algorithm](https://www.ietf.org/rfc/rfc4226.txt)
12-
- RFC 6238 [TOTP: Time-Based One-Time Password Algorithm](https://tools.ietf.org/html/rfc6238)
12+
13+
* [RFC 4226: "RFC 4226 HOTP: An HMAC-Based One-Time Password Algorithm"](https://www.ietf.org/rfc/rfc4226.txt)
14+
* [RFC 6238: "TOTP: Time-Based One-Time Password Algorithm"](https://tools.ietf.org/html/rfc6238)
1315

1416
## Dependency
1517

1618
The library is available at [Maven Central](https://mvnrepository.com/artifact/com.marcelkliemannel/kotlin-onetimepassword):
1719

1820
### Gradle
1921

20-
```gradle
21-
compile 'com.marcelkliemannel:kotlin-onetimepassword:1.0.0'
22+
```java
23+
// Groovy
24+
compile 'dev.turingcomplete:kotlin-onetimepassword:2.0.0'
25+
26+
// Kotlin
27+
compile("dev.turingcomplete:kotlin-onetimepassword:2.0.0")
2228
```
2329

24-
### Apache Maven
30+
### Maven
2531

2632
```xml
2733
<dependency>
28-
<groupId>com.marcelkliemannel</groupId>
34+
<groupId>dev.turingcomplete</groupId>
2935
<artifactId>kotlin-onetimepassword</artifactId>
30-
<version>1.0.0</version>
36+
<version>2.0.0</version>
3137
</dependency>
3238
```
3339

3440
## Usage
3541

36-
### Number of Code Digits
42+
### General Flow
43+
44+
```
45+
(1) Shared secret
46+
/‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾\
47+
User Server
48+
<------------- Challenge ------------ (2)
49+
(3) ----- One-time password (Code) ----->
50+
```
51+
52+
1. User and Server need a **shared secret**, which must be negotiated in advance and remains constant over a longer period of time.
53+
2. The user now wants to authenticate to the server. The user could send the shared secret directly to the server (like a normal password), but this could be captured by a [man-in-the-middle attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) and the attacker could simply login with the password. Instead, the server sends the user a **challenge** that the user can only solve if he actually has the correct shared secret. This step is optional if the generation of the challenge is known to both sides. For example, the Google authenticator generator always uses the unix time.
54+
3. The solution to the challenge is a numeric **code**. Because the challenge changes with each authentication attempt, the code is called a **one-time password** as it can only be used once. Even if an attacker captues the code, he can't use it a second time to login himself.
3755

38-
All three one-time password generators are creating a code value with a fixed length given by the ```codeDigits``` property in the configuration instance. To meet this requirement, the original computed code number gets zeros added to the beginning (and therefore it is represented as a string). The RFC 4226 requires a code digits value between 6 and 8, to assure a good security trade-off. However, this library does not set any requirement for this property. But notice that through the design of the algorithm the maximum code value is 2_147_483_647. Which means that a larger code digits value than 10 just adds more trailing zeros to the code (and in case of 10 digits the first number is 0, 1 or 2).
56+
#### Implementation
57+
58+
The client of the user and the server must use the same generator with the same configuration (e.g. number of code digits, hash algorithm).
59+
60+
If the one-time-password is used for a two-factor authentication, a possible HTTP flow could look like this (even if it does not follow an official standardization):
61+
62+
1. The client sends a HTTP request with the header for the normal login credentials ```Authorization: Basic Base64($username:$password)``` to the server.
63+
2. If there is a two-factor authentication activated for the user, the server answers with HTTP status code ```401 Unauthorized``` and the header ```WWW-Authenticate: authType="2fa"```. The value for ```authType``` can also be made more specific to tell the client which generator should be used (e.g. _HOTP_, _TOTP_ or _Google_). If the generation of the challenge is not known in advance, this value must be transferred by appending to the header value ```, challenge="$challenge"```.
64+
3. The client then sends again the normal login credentials header and the additonal header ```Authorization: 2FA $code``` (or a more specific generator name instead of "2FA").
65+
66+
#### Number of Code Digits
67+
68+
All three one-time password generators are creating a code value with a fixed length given by the ```codeDigits``` property in the configuration instance. To meet this requirement, the original computed code number gets zeros added at the _beginning_ and therefore it must be represented as a string. The RFC 4226 requires a code digits value between 6 and 8, to assure a good security trade-off. However, this library does not set any requirement for this property. But notice that through the design of the algorithm the maximum code value is `2,147,483,647`. Which means that a larger code digits value than 10 just adds more trailing zeros to the code (and in case of 10 digits the first number is always 0, 1 or 2).
3969

4070
### HMAC-based One-time Password (HOTP)
4171

42-
The HOTP generator is available through the class ```HmacOneTimePasswordGenerator```. The constructor takes the secret and a configuration instance of the class ```HmacOneTimePasswordConfig``` as arguments:
72+
The HOTP generator is available through the class ```HmacOneTimePasswordGenerator```. The constructor takes the shared secret and a configuration instance of the class ```HmacOneTimePasswordConfig``` as arguments:
4373

4474
```kotlin
4575
val secret = "Leia"
46-
val config = HmacOneTimePasswordConfig(codeDigits = 8, hmacAlgorithm = HmacAlgorithm.SHA1)
76+
val config = HmacOneTimePasswordConfig(codeDigits = 8,
77+
hmacAlgorithm = HmacAlgorithm.SHA1)
4778
val hmacOneTimePasswordGenerator = HmacOneTimePasswordGenerator(secret.toByteArray(), config)
4879
```
4980

50-
The configuration instance takes the number of code digits to be generated (see previous chapter) and the HMAC algorithm to be used (currently are *SHA1*, *SHA256* and *SHA512* available).
81+
The configuration instance takes the number of code digits to be generated (see previous chapter) and the HMAC algorithm to be used (*SHA1*, *SHA256* and *SHA512* available).
5182

52-
The method ```generate(counter: Int)``` can now be used on the generator instance to generate a HOTP code:
83+
The method ```generate(counter: Int)``` can now be used on an instance of the generator to generate a HOTP code:
5384

5485
```kotlin
55-
hmacOneTimePasswordGenerator.generate(counter = 0)
56-
hmacOneTimePasswordGenerator.generate(counter = 1)
57-
hmacOneTimePasswordGenerator.generate(counter = 2)
86+
var code0: String = hmacOneTimePasswordGenerator.generate(counter = 0)
87+
var code1: String = hmacOneTimePasswordGenerator.generate(counter = 1)
88+
var code2: String = hmacOneTimePasswordGenerator.generate(counter = 2)
5889
...
5990
```
6091

61-
There is also a helper method ```isValid(code: String, counter: Int)``` available on the generator instance, to make the validation of the received code possible in one line.
92+
There is also a helper method ```isValid(code: String, counter: Int)``` available in the instance of the generator, to make the validation of the received code possible in one line.
6293

6394
### Time-based One-time Password (TOTP)
6495

65-
The TOTP generator is available through the class ```TimeBasedOneTimePasswordGenerator```. The constructor takes the secret and a configuration instance of the class ```TimeBasedOneTimePasswordConfig``` as arguments:
96+
The TOTP generator is available through the class ```TimeBasedOneTimePasswordGenerator```. The constructor takes the shared secret and a configuration instance of the class ```TimeBasedOneTimePasswordConfig``` as arguments:
6697

6798
```kotlin
6899
val secret = "Leia"
69-
val config = TimeBasedOneTimePasswordConfig(codeDigits = 8, hmacAlgorithm = HmacAlgorithm.SHA1,
70-
timeStep = 30, timeStepUnit = TimeUnit.SECONDS)
100+
val config = TimeBasedOneTimePasswordConfig(codeDigits = 8,
101+
hmacAlgorithm = HmacAlgorithm.SHA1,
102+
timeStep = 30,
103+
timeStepUnit = TimeUnit.SECONDS)
71104
val timeBasedOneTimePasswordGenerator = TimeBasedOneTimePasswordGenerator(secret.toByteArray(), config)
72105
```
73106

74-
As well as the HOTP configuration, the TOTP configuration takes the number of code digits and the HMAC algorithm as arguments (see the previous chapter). Additionally, the time window in which the generated code is valid is represented through the arguments ```timeStep``` and ```timeStepUnit```.
107+
As well as the HOTP configuration, the TOTP configuration takes the number of code digits and the HMAC algorithm as arguments (see the previous chapter). Additionally, the time window in which the generated code is valid is represented through the arguments ```timeStep``` and ```timeStepUnit```. The defaul value of ```timestamp``` is the current system time
75108

76-
The method ```generate(timestamp: Date)``` can now be used on the generator instance to generate a TOTP code. The default timestamp value is the current system time.
109+
The method ```generate(timestamp: Date)``` can now be used on the generator instance to generate a TOTP code:
77110

78111
```kotlin
79-
timeBasedOneTimePasswordGenerator.generate() // Will use System.currentTimeMillis()
80-
timeBasedOneTimePasswordGenerator.generate(timestamp = Date(59))
81-
timeBasedOneTimePasswordGenerator.generate(timestamp = Date(1234567890))
112+
var code0: String = timeBasedOneTimePasswordGenerator.generate() // Will use System.currentTimeMillis()
113+
var code1: String = timeBasedOneTimePasswordGenerator.generate(timestamp = Date(59))
114+
var code2: String = timeBasedOneTimePasswordGenerator.generate(timestamp = Date(1234567890))
82115
...
83116
```
84117

85-
Again, there is a helper method ```isValid(code: String, timestamp: Date)``` available on the generator instance, to make the validation of the received code possible in one line.
118+
Again, there is a helper method ```isValid(code: String, timestamp: Date)``` available in the instance of the generator, to make the validation of the received code possible in one line.
86119

87120
### Google Authenticator
88121

89-
The Google Authenticator generator is available through the class ```GoogleAuthenticator```. It is a decorator for the TOTP generator with a fixed code digits value of 6, SHA1 as HMAC algorithm and a time window of 30 seconds. The constructor just takes the secret as an argument. **Notice that the secret must be Base32-encoded!**
122+
The Google Authenticator generator is available through the class ```GoogleAuthenticator```. It is a decorator for the TOTP generator with a fixed code digits value of 6, SHA1 as HMAC algorithm and a time window of 30 seconds. The constructor just takes the secret as an argument. **Note that the secret must be Base32-encoded!**
90123

91124
```kotlin
92125
val googleAuthenticator = GoogleAuthenticator(secret = "J52XEU3IMFZGKZCTMVRXEZLU") // "OurSharedSecret" Base32-encoded
126+
var code = googleAuthenticator.generate() // Will use System.currentTimeMillis()
93127
```
94128

95129
See the TOTP generator for the code generation ```generator(timestamp: Date)``` and validation ```isValid(code: String, timestamp: Date)``` methods.
96130

97-
There is also a helper method ```GoogleAuthenticator.createRandomSecret()``` which will return a 16-byte Base32-decoded random secret.
131+
There is also a helper method ```GoogleAuthenticator.createRandomSecret()``` that will return a 16-byte Base32-decoded random secret.
98132

99133
### Random Secret Generator
100134

101-
RFC 4226 recommends using a secret of the same size as the hash produced by the HMAC algorithm. To make this easy, there is a ```RandomSecretGenerator``` class, to generate secure random secrets with the given length:
135+
RFC 4226 recommends using a secret of the same length as the hash produced by the HMAC algorithm. The class ```RandomSecretGenerator``` can be used to generate such random shared secrets:
102136

103137
```kotlin
104138
val randomSecretGenerator = RandomSecretGenerator()
105139

106-
randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA1) // 20-byte secret
107-
randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA256) // 32-byte secret
108-
randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA512) // 64-byte secret
109-
110-
randomSecretGenerator.createRandomSecret(1234) // 1234 Bytes secret
140+
val secret0: ByteArray = randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA1) // 20-byte secret
141+
val secret1: ByteArray = randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA256) // 32-byte secret
142+
val secret2: ByteArray = randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA512) // 64-byte secret
143+
val secret3: ByteArray = randomSecretGenerator.createRandomSecret(1234) // 1234-byte secret
111144
```
112145

113146
## License
114147

115148
**MIT License**
116149

117-
> Copyright 2018 Marcel Kliemannel
150+
> Copyright 2019 Marcel Kliemannel
118151
>
119152
> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
120153
>

0 commit comments

Comments
 (0)