Visit the documentation at: https://robinohs.github.io/totp-kt/
Native Kotlin library for time-based TOTP and HMAC-based HOTP one-time passwords. Enables the developer to:
- validate and generate TOTP (RFC 6238) and HOTP (RFC 4226) one-time passwords,
- generate randomly secure secrets to use with authenticators,
- generate randomly secure recovery codes.
Add the dependency:
//build.gradle.kts
dependencies {
implementation("dev.robinohs:totp-kt:v1.0.1")
}Add the dependency:
<!--pom.xml-->
<dependency>
<groupId>dev.robinohs</groupId>
<artifactId>totp-kt</artifactId>
<version>1.0.1</version>
</dependency>Add the dependency:
//build.gradle
dependencies {
implementation 'dev.robinohs:totp-kt:v1.0.1'
}If you are using Jitpack as a repository, you can follow one of the following sections to install using with your favorite package manager such as gradle or maven.
Add Jitpack to repositories:
//build.gradle.kts
repositories {
mavenCentral()
maven { url = uri("https://jitpack.io") }
}Add the dependency:
//build.gradle.kts
dependencies {
implementation("com.github.robinohs:totp-kt:v1.0.1")
}Add Jitpack to repositories:
<!--pom.xml-->
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>Add the dependency:
<!--pom.xml-->
<dependency>
<groupId>com.github.robinohs</groupId>
<artifactId>totp-kt</artifactId>
<version>v1.0.1</version>
</dependency>Add Jitpack to repositories:
//build.gradle
allprojects {
repositories {
//...
maven { url 'https://jitpack.io' }
}
}Add the dependency:
//build.gradle
dependencies {
implementation 'com.github.robinohs:totp-kt:v1.0.1'
}The time-based one-time password method, generates one-time passwords by using a shared secret in combination with a time window as the source of uniqueness. The TOTP algorithm is an extension of HOTP. The algorithm is used by commonly known authenticator apps, e.g. Google Authenticator, Mircrosoft Authenticator and others.
sequenceDiagram
participant Client
participant Server
Client -> Server: shared secret
Client ->> Server: login (name: xy, password: xy)
Server ->> Client : 401 TOTP required
Client ->> Client: Client generates TOTP
Client ->> Server: login (name: xy, password: xy, totp: 564867)
Server ->> Server: Server generates TOTP
Server ->> Server: Is client TOTP the same?
Server -->> Client: If equal: JWT (session, ...)
Server -->> Client: If different: 401, BadCredentials
You can create an instance of the TotpGenerator in the following way:
val totpGenerator = TotpGenerator()After you created the totpGenerator instance you can generate a one-time password by calling the generatore code method with the secret as an argument. Optionally, if you want to specify a specific time and not have the generator to take the current time itself, you can pass a time as an argument.
val secret = some_base32_encoded_secret_as_bytearray
val code = totpGenerator.generateCode(secret)If one would like to specify a time:
// with millis
totpGenerator.generateCode(secret, 1656459878681)
// with Instant
totpGenerator.generateCode(secret, Instant())
// with Date
totpGenerator.generateCode(secret, Date())There is a helper function to compare a currently generated code with a given code. Optionally, you can also use generateCode yourself and compare the resulting string to the client's code.
val secret = some_base32_encoded_secret_as_bytearray
val clientCode = given_client_code
totpGenerator.isCodeValid(secret, clientCode)If one would like to specify a time:
// with millis
totpGenerator.isCodeValid(secret, 1656459878681, clientCode)
// with Instant
totpGenerator.isCodeValid(secret, Instant(), clientCode)
// with Date
totpGenerator.isCodeValid(secret, Date(), clientCode)Compares a generated code to a given code using a counter derived from the current timestamp and a given secret. In addition, the method considers a tolerance and also checks the given code against a number of previous tokens equal to the tolerance. Returns true if the given code matches any of these tokens.
val secret = some_base32_encoded_secret_as_bytearray
val clientCode = given_client_code
totpGenerator.isCodeValidWithTolerance(secret, clientCode)If one would like to specify a time:
// with millis
totpGenerator.isCodeValidWithTolerance(secret, 1656459878681, clientCode)
// with Instant
totpGenerator.isCodeValidWithTolerance(secret, Instant(), clientCode)
// with Date
totpGenerator.isCodeValidWithTolerance(secret, Date(), clientCode)Calculates the start timestamp of the time slot in which the actual or given timestamp lies.
// takes actual timestamp from clock, returns millis
totpGenerator.calculateTimeslotBeginning()If one would like to specify a time:
// with millis, returns millis
totpGenerator.calculateTimeslotBeginning(1656459878681, clientCode)
// with Instant, returns Instant
totpGenerator.calculateTimeslotBeginning(Instant(), clientCode)
// with Date, returns Date
totpGenerator.calculateTimeslotBeginning(Date(), clientCode)Calculates the remaining duration of the time slot in which the actual or given timestamp lies.
// takes actual timestamp from clock
totpGenerator.calculateRemainingTime()If one would like to specify a time:
// with millis
totpGenerator.calculateRemainingTime(1656459878681)
// with Instant
totpGenerator.calculateRemainingTime(Instant())
// with Date
totpGenerator.calculateRemainingTime(Date())It is possible to customize the properties of the generator, either by setters or applying them in the constructor.
The clock is the time source for the generator if no time is passed as an argument to the generateCode or validateCode method.
val totpGenerator = TotpGenerator(clock = Clock.systemUTC())
// or
totpGenerator.clock = Clock.systemUTC()For testing purposes, one could assign a Clock.fixed that always returns the same timestamp and thus the same TOTP code.
The time period is the duration of every time step in which the generated code is the same. This is needed as due to delays (e.g., network delay) the server will not generate the code with the same timestamp as the client. As a compromise between security and usability the default time step is set as 30 seconds.
A time period of 30 seconds is used by the Google or Mircrosoft Authenticator app.
The tolerance specifies a number of previous tokens that are also accepted as valid tokens in addition to the current valid token.
A tolerance of 1 token is set as default. In RFC6238#5.2 a time step is recommended to compensate for delays such as network delay.
The code length specifies how long a generated code will be. If the code length is changed, it is necessary that the user's authenticator app supports this as well.
A length of 6 digits is used by the Google or Microsoft Authenticator app.
The HMAC-based one-time password method generates one-time passwords by using a shared secret in combination with a counter as the source of uniqueness. The major problem of this approach is the synchronization of the counter between the client and the server. Synchronization is out of scope for this library and therefore needs to be implemented by the consumer. A method for re-synchronization is described in the specification RFC4226#7.4.
sequenceDiagram
participant Client
participant Server
Client -> Server: shared secret + counter
Client ->> Server: login (name: xy, password: xy)
Server ->> Client : 401 HOTP required
Client ->> Client: Client generates HOTP with counter
Client ->> Server: login (name: xy, password: xy, hotp: 564867)
Server ->> Server: Server generates HOTP with counter
Server ->> Server: Is client HOTP the same?
Server -->> Client: If equal: JWT (session, ...)
Server -->> Client: If different: 401, BadCredentials
You can create an instance of the HotpGenerator in the following way:
val hotpGenerator = HotpGenerator()After you created the hotpGenerator instance you can generate a one-time password by calling the generatore code method with the secret and the counter as arguments.
val secret = some_base32_encoded_secret_as_bytearray
val counter = some_number
val code = hotpGenerator.generateCode(secret, counter)There is a helper function to compare a generated code with a given code. Optionally, you could also use generateCode yourself and compare the resulting string to the client's code.
val secret = some_base32_encoded_secret_as_bytearray
val counter = some_number
val clientCode = given_client_code
totpGenerator.isCodeValid(secret, counter, clientCode)It is possible to customize the properties of the generator, either by setters or applying them in the constructor.
The code length specifies how long a generated code will be. If the code length is changed, it is necessary that the user's authenticator app supports this as well.
The secret generator can be used to generate base32 encoded secrets as strings and bytearrays.
You can create an instance of the SecretGenerator in the following way:
val secretGenerator = SecretGenerator()If you want to generate a secret that can be used as a shared secret between the client and the server, there is the generateSecret function. The default behavior of the function is to generate a 10 character secret and convert it to a Base32Secret instance. Optionally you can specify the length of the plain input to the base32 encoding secret.
val base32Secret: Base32Secret = secretGenerator.generateSecret()The Base32Secret data class contains a secret in the form of a bytearray and a string.
val base32Secret: Base32Secret = secretGenerator.generateSecret()
val (secretAsString, secretAsByteArray) = base32SecretIt is possible to customize the properties of the generator, either by setters or applying them in the constructor.
The RandomGenerator instance used internally to generate random strings.
This generator can be used to create a randomly generated string in block form.
You can create an instance of the RecoveryCodeGenerator in the following way:
val recoveryCodeGenerator = RecoveryCodeGenerator()This method generates a single recovery-code.
val recoveryCode = recoveryCodeGenerator.generateRecoveryCode()
println(recoveryCode)
"AAAA-BBBB-CCCC-DDDD"This method generates a list of recovery-codes.
val recoveryCodes = recoveryCodeGenerator.generateRecoveryCodes(3)
println(recoveryCodes)
["AAAA-BBBB-CCCC-DDDD", "BBBB-AAAA-CCCC-DDDD", "BBBB-AAAA-DDDD-CCCC"]It is possible to customize the properties of the generator, either by setters or applying them in the constructor.
Specifies the number of blocks that make up each recovery code.
Specifies the length of each block in each recovery code.
The RandomGenerator instance used internally to generate random strings.
The random generator is internally used by the SecretGenerator and RecoveryCodeGenerator to create randomly secure strings.
It is possible to customize the properties of the generator, either by setters or applying them in the constructor.
The generator accepts any class implementing the java random interface.
The default is the SecureRandom implementation and should not be changed unless you know what you are doing!
The char pool specifies the list of characters that can be used to generate the string.
If the char pool gets too small, the security is weakend. For example a 10-character long password with the default charset of the library has the following properties:$$ Combinations: 62^{10} = 8.3929937e^{17}\ Entropy: log_2(62^{10}) = 59.542 $$ Passwords with a entropy >50 are considered to be secure.
Instead of creating a new instance of a generator each time a token is checked, it is also possible to create a bean within Spring. This allows to configure the generator once and this configuration is maintained each time the bean is injected into a component.
@Bean
fun totpGenerator(): TotpGenerator {
val generator = TotpGenerator()
generator.codeLength = 9
generator.timePeriod = Duration.ofSeconds(20)
return generator
}
@Bean
fun recoveryCodeGenerator(): RecoveryCodeGenerator {
val generator = RecoveryCodeGenerator()
generator.blockLength = 5
return generator
}This bean can then be injected in the constructor of any class marked with @Component (@Service, ...).
@Component
class CustomComponent(
private val totpGenerator: TotpGenerator,
private val recoveryCodeGenerator: RecoveryCodeGenerator
) {
//...
}