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.
- 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
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.
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);
}
}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);
}
}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
}
}Please see CONTRIBUTING.md for more information.
faktor is licensed under the MIT License.