TOTP code (RFC 6238) verification for java

Providing a simple way to integrate RFC 6238 conforming TOTP codes in your application.

This library was designed to be easy to use, lean (no external dependencies), secure and performant.

Dependencies

<!-- https://mvnrepository.com/artifact/eu.fraho.libs/libtotp -->
<dependency>
    <groupId>eu.fraho.libs</groupId>
    <artifactId>libtotp</artifactId>
    <version>1.1.0</version>
</dependency>

Usage

import eu.fraho.libs.totp.*;

import java.nio.charset.StandardCharsets;
import java.time.ZoneId;
import java.time.ZonedDateTime;

public class Example {
    public static void main(String[] args) {
        // the code to verify
        int code = Integer.parseInt(args[0]);

        // default settings (sha1, 6 digits, allow clock screw of +- 90 seconds)
        Totp testee = new Totp(TotpSettings.DEFAULT);

        // get the shared secret key
        byte[] secret = "sharedSecret".getBytes(StandardCharsets.UTF_8);

        // do the verification using the current time
        if (testee.verifyCode(secret, code)) {
            System.out.println("Now: All ok!");
        } else {
            System.out.println("Now: Wrong code!");
        }

        // do the verification using a specific time
        long timestamp = ZonedDateTime.of(2023, 3, 10, 8, 9, 10, 0, ZoneId.of("Europe/Berlin")).toEpochSecond();
        if (testee.verifyCode(secret, code, timestamp / 30)) {
            System.out.println("Custom time: All ok!");
        } else {
            System.out.println("Custom time: Wrong code!");
        }
    }
}

Configuration

The parameters can be configured using the TotpSettings. This class is implemented using the builder-Pattern and provides the following options:

public class Example {
    public static TotpSettings createSettings() {
        TotpSettings.builder()
                .hmac("HmacSHA1")
                .secretLength(20)
                .tokenLength(6)
                .variance(3)
                .build();
    }
}

Setting	Default	Reasonable values	Description
hmac	HmacSHA1	HmacSHA1, HmacSHA256, HmacSHA512	HMAC algorithm to use
secretLength	20	> 16	Defines the length of newly generated secrets
tokenLength	6	6 - 8	Length of the generated codes
variance	3	0 - 3	Defines the allowed clock time differences for verifications, as +- 30 seconds steps

Hacking

This repository uses the git flow layout
Changes are welcome, but please use pull requests with separate branches
Github workflow has to pass before merging
Code coverage should stay about the same level (please write tests for new features!)

Releasing

Releasing is done with the default gradle tasks: