kotlin-onetimepassword

The OTP process relies on a shared secret between a user and a server.

1. Shared Secret: Both parties agree on a stable secret in advance.
2. Challenge: The server may send a challenge (e.g., a timestamp for TOTP) that the user must solve using the secret.
3. Code: The user's client generates a numeric code (the OTP) which is sent to the server for validation.

Implementation Note: The client and server must use identical configurations, specifically the number of code digits and the HMAC algorithm (e.g., SHA1, SHA256, SHA512).

Code Digits: Codes are returned as String to preserve leading zeroes. While RFC 4226 recommends 6-8 digits, this library allows explicit configuration for shorter lengths if allowInsecureConfiguration = true is set.

Add the library as a dependency to your project using Gradle or Maven. The library is hosted on Maven Central.

Version: 3.0.0

// Groovy
implementation 'dev.turingcomplete:kotlin-onetimepassword:3.0.0'

// Kotlin
implementation("dev.turingcomplete:kotlin-onetimepassword:3.0.0")

<!-- Maven -->
<dependency>
    <groupId>dev.turingcomplete</groupId>
    <artifactId>kotlin-onetimepassword</artifactId>
    <version>3.0.0</version>
</dependency>

To run the provided Google Authenticator example application, you can either execute the main function in the GoogleAuthenticatorAppKt class or use the Gradle wrapper from your terminal.

Using Gradle

Execute the following command in your terminal:

./gradlew :example:googleauthenticator:run

To facilitate easy account setup via QR codes, use OtpAuthUriBuilder to create a URI following the Key Uri Format specification.

Note: The specification requires that Base32 padding characters (=) are removed from the secret parameter in the URI.

All generators provide an otpAuthUriBuilder() helper that pre-configures the builder with the generator's current settings.

// Manual construction
OtpAuthUriBuilder.forTotp(Base32().encode("secret".toByteArray()))
  .label("John", "Company")
  .issuer("Company")
  .digits(8)
  .buildToString()

// Using the generator's helper (pre-configured)
val googleAuth = GoogleAuthenticator(Base32().encode("secret".toByteArray()))
val uri = googleAuth.otpAuthUriBuilder()
  .issuer("Company")
  .buildToString()

Use RandomSecretGenerator to create cryptographically secure shared secrets. It is recommended to use a secret length that matches the output of the chosen HMAC algorithm (e.g., 20 bytes for SHA1).

val randomSecretGenerator = RandomSecretGenerator()

val secretSHA1 = randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA1)   // 20-byte
val secretSHA256 = randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA256) // 32-byte
val secretSHA512 = randomSecretGenerator.createRandomSecret(HmacAlgorithm.SHA512) // 64-byte

The GoogleAuthenticator class is a convenience wrapper for generating Time-based One-Time Passwords (TOTP) that are compatible with Google Authenticator. It uses a fixed configuration:

• HMAC algorithm: HmacAlgorithm.SHA1
• Time step: 30 seconds
• Code digits: 6

To use it, provide a Base32-encoded secret as a ByteArray. You can then generate codes for a specific timestamp or validate a provided code against a timestamp.

// Initialize with a Base32-encoded secret
val secret = GoogleAuthenticator.createSecureRandomSecretAsByteArray()
val authenticator = GoogleAuthenticator(secret)

// Generate a code (defaults to current system time)
val code = authenticator.generate()

// Validate a code
val isValid = authenticator.isValid(code)

To allow users to easily add an account to an authenticator app, you can generate an otpauth:// URI. The GoogleAuthenticator class provides a preconfigured builder that uses the correct secret and the fixed Google Authenticator settings (SHA1, 30s step, 6 digits).

val authenticator = GoogleAuthenticator(secret)
val uriBuilder = authenticator.otpAuthUriBuilder()
// Use uriBuilder to construct your URI

The RandomSecretGenerator class provides utilities for generating cryptographically secure random bytes using SecureRandom. These bytes serve as the shared secrets required for OTP (HOTP/TOTP) configurations.

Important Note on Encoding: The generated secret is a raw ByteArray. Most authenticator apps (like Google Authenticator) and OTP Auth URIs expect the secret to be encoded in Base32. You must encode these bytes before using them in a URI or providing them to a user as a text-based secret.

val generator = RandomSecretGenerator()

// Option 1: Generate a secret of a specific byte length
val secret = generator.createRandomSecret(20)

// Option 2: Generate a secret matching the length of an HMAC algorithm
val secretFromAlgo = generator.createRandomSecret(HmacAlgorithm.SHA1)

The GoogleAuthenticator companion object provides methods to generate new secrets.

• createSecureRandomSecretAsByteArray(): Generates an RFC 4226 recommended 160-bit secret as a Base32-encoded ByteArray. This is the preferred method for new deployments.
• createRandomSecretAsByteArray(): Generates an 80-bit secret (16-character Base32) to maintain compatibility with historical Google Authenticator conventions.
• createRandomSecret(): (Deprecated) Returns the 80-bit secret as a String. Use the ByteArray version instead to avoid keeping secrets in immutable JVM strings.

// Recommended for new deployments
val secureSecret = GoogleAuthenticator.createSecureRandomSecretAsByteArray()

// For historical 80-bit compatibility
val legacySecret = GoogleAuthenticator.createRandomSecretAsByteArray()