README.md

faktor 🔐

Tiny RFC 4226 & RFC 6238 compliant one-time password generation & validation library for Java

---

faktor is a tiny otp library that supports otp generation and validation. faktor supports HOTP (HMAC-based one-time passwords) and TOTP (Time-based one-time passwords).

One-time passwords provide an extra layer of security for your users. Instead of just logging in with your username and password an additional one-time password is required, which is usually generated by the user's phone. Please see the Wikipedia page for more information about OTPs.

Features

• HOTP
  • HMAC-SHA-1
• TOTP
  • HMAC-SHA-1, HMAC-SHA-256, HMAC-SHA-512
• Generation & validation
• Hex secrets
• Base32 secrets
• RFC 4226 & RFC 6238 compliant
• Very lightweight, no runtime dependencies

Usage

Maven installation

<dependency>
    <groupId>dev.cerus</groupId>
    <artifactId>faktor</artifactId>
    <version>1.0.0</version>
</dependency>

Most of faktor's functionality revolves around these four classes: HOTPGenerator, TOTPGenerator, TOTPService and OTPSecret.

To generate a new secret use either OTPSecret#generateBase32Secret(HMACAlgorithm, Random) or OTPSecret#generateHexSecret(HMACAlgorithm, Random).

To generate HOTPs use the HOTPGenerator class. To generate TOTPs use the TOTPGenerator class. To generate and validate TOTPs use the TOTPService class. Check the examples section for more information.

Examples

HOTPGenerator

import dev.cerus.faktor.HMACAlgorithm;
import dev.cerus.faktor.generator.HOTPGenerator;
import dev.cerus.faktor.service.secret.OTPSecret;
import java.security.SecureRandom;
import java.util.Random;

class Example {

    public static void main(String[] args) {
        long counter = 123456789L;  // This is the counter value used for otp generation
        int digits = 6;             // This is the amount of digits the otp will have (can be between 6 and 10)

        Random rand = new SecureRandom();
        OTPSecret secret = OTPSecret.generateBase32Secret(HMACAlgorithm.SHA1, rand);
        HOTPGenerator gen = HOTPGenerator.newDefaultGenerator(); // Creates a new instance of DefaultHOTPGenerator
        final int otp = gen.generateHOTP(secret.asBytes(), counter, digits);
        System.out.print("Your HOTP is %d%n", otp);
    }

}

TOTPGenerator

import dev.cerus.faktor.HMACAlgorithm;
import dev.cerus.faktor.generator.TOTPGenerator;
import dev.cerus.faktor.service.secret.OTPSecret;
import java.security.SecureRandom;
import java.util.Random;
import java.util.concurrent.TimeUnit;

class Example {

    public static void main(String[] args) {
        long timestamp = System.currentTimeMillis();    // This is the timestamp the otp will be generated for
        long timeStep = TimeUnit.SECONDS.toMillis(30);  // This is the lifetime of each otp
        int digits = 6;                                 // This is the amount of digits the otp will have (can be between 6 and 10)
        HMACAlgorithm algo = HMACAlgorithm.SHA1;        // This is the algorithm that's used for otp generation

        Random rand = new SecureRandom();
        OTPSecret secret = OTPSecret.generateBase32Secret(HMACAlgorithm.SHA1, rand);
        TOTPGenerator gen = TOTPGenerator.newDefaultGenerator(); // Creates a new instance of DefaultTOTPGenerator
        final int otp = gen.generateTOTP(secret.asBytes(), timestamp, timeStep, digits, algo);
        System.out.print("Your TOTP is %d%n", otp);
    }

}

TOTPService

import dev.cerus.faktor.HMACAlgorithm;
import dev.cerus.faktor.service.TOTPService;
import java.util.concurrent.TimeUnit;

class Example {

    public static void main(String[] args) {
        Random rand = new SecureRandom();
        OTPSecret secret = OTPSecret.generateBase32Secret(HMACAlgorithm.SHA1, rand);
        TOTPService totpService = TOTPService.defaultServiceBuilder()
                .withAlgorithm(HMACAlgorithm.SHA1)
                .withSecret(secret)
                .withTimeStep(30, TimeUnit.SECONDS)
                .withDigits(6)
                .withDefaultGenerator() // DefaultTOTPGenerator
                .withBackwardsSteps(2) // This specifies how many time steps a secret can be old to still count as valid
                .build();

        final int totp = totpService.generateTOTP();
        totpService.validateTOTP(totp); // -> true
    }

}

Contributing

Please see CONTRIBUTING.md for more information.

License

faktor is licensed under the MIT License.