totp-kt - Kotlin OTP Library

Visit the documentation at: https://robinohs.github.io/totp-kt/

CURRENTLY IN ALPHA v2

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.

Navigation

• Installation
  • Jitpack
    • Kotlin DSL
    • Maven
    • Gradle
• Usage
  • TOTP (Time-based One-Time Password)
  • HOTP (HMAC-based One-Time Password)
  • Secret generator
  • Recovery-Code generator
  • Random Generator
• Spring Boot
• License

Installation

Only Jitpack is supported in the alpha phase.

Jitpack

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.

Kotlin DSL

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:v2.0.0-alpha")
}

Maven

Add Jitpack to repositories:

<repositories>
  <repository>
    <id>jitpack.ioid>
    <url>https://jitpack.iourl>
  repository>
repositories>

Add the dependency:

<dependency>
  <groupId>com.github.robinohsgroupId>
    <artifactId>totp-ktartifactId>
    <version>v2.0.0-alphaversion>
dependency>

Gradle

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:v2.0.0-alpha'
}

Usage

TOTP (Time-based One-Time Password)

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.

TOTP flow

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

Create a TOTP generator

You can create an instance of the TotpGenerator in the following way:

val totpGenerator = TotpGenerator()

Use the TOTP generator

Method: Generate Code

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())

Method: Validate Code

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)

Method: Validate Code With Tolerance

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)

Method: Timeslot beginning

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)

Method: Remaining time

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())

Customize properties

It is possible to customize the properties of the generator, either by setters or applying them in the constructor.

Clock

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.

Time period

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.

Tolerance

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.

Code length

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.

HOTP (HMAC-based One-Time Password)

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.

HOTP flow

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

Create a HOTP generator

You can create an instance of the HotpGenerator in the following way:

val hotpGenerator = HotpGenerator()

Use the HOTP generator

Method: Generate Code

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)

Method: Validate Code

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)

Customize properties

It is possible to customize the properties of the generator, either by setters or applying them in the constructor.

Code length

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.

Secret generator

The secret generator can be used to generate base32 encoded secrets as strings and bytearrays.

Create a Secret generator

You can create an instance of the SecretGenerator in the following way:

val secretGenerator = SecretGenerator()

Use the Secret generator

Method: Generate Secret

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()

Data Class: Base32Secret

The Base32Secret data class contains a secret in the form of a bytearray and a string.

val base32Secret: Base32Secret = secretGenerator.generateSecret()
val (secretAsString, secretAsByteArray) = base32Secret

Customize properties

It is possible to customize the properties of the generator, either by setters or applying them in the constructor.

Used Random generator

The RandomGenerator instance used internally to generate random strings.

Recovery-Code generator

This generator can be used to create a randomly generated string in block form.

Create a Recovery-Code generator

You can create an instance of the RecoveryCodeGenerator in the following way:

val recoveryCodeGenerator = RecoveryCodeGenerator()

Use the Recovery-Code generator

Method: Generate Recovery-Code

This method generates a single recovery-code.

val recoveryCode = recoveryCodeGenerator.generateRecoveryCode()
println(recoveryCode)
"AAAA-BBBB-CCCC-DDDD"

Method: Generate a list of Recovery-Codes

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"]

Customize properties

It is possible to customize the properties of the generator, either by setters or applying them in the constructor.

Number of blocks

Specifies the number of blocks that make up each recovery code.

Block length

Specifies the length of each block in each recovery code.

Used Random generator

The RandomGenerator instance used internally to generate random strings.

Random generator

The random generator is internally used by the SecretGenerator and RecoveryCodeGenerator to create randomly secure strings.

Customize properties

It is possible to customize the properties of the generator, either by setters or applying them in the constructor.

Random (Dangerous)

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!

Charpool (Dangerous)

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.

Spring Boot

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
) {
	//...
}

License

MIT