https://github.com/cerus/faktor
🔐 Tiny & lightweight RFC 4226 & RFC 6238 compliant one-time password (HOTP/TOTP) generation & validation library for Java
https://github.com/cerus/faktor
2fa 2factor authy google-authenticator hotp one-time-password otp otp-generator otp-verification rfc-4226 rfc-6238 rfc4226 rfc6238 totp totp-generator
Last synced: 7 months ago
JSON representation
🔐 Tiny & lightweight RFC 4226 & RFC 6238 compliant one-time password (HOTP/TOTP) generation & validation library for Java
- Host: GitHub
- URL: https://github.com/cerus/faktor
- Owner: cerus
- License: mit
- Created: 2023-04-08T01:06:09.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-04-08T01:54:50.000Z (over 2 years ago)
- Last Synced: 2025-01-24T17:44:49.577Z (9 months ago)
- Topics: 2fa, 2factor, authy, google-authenticator, hotp, one-time-password, otp, otp-generator, otp-verification, rfc-4226, rfc-6238, rfc4226, rfc6238, totp, totp-generator
- Language: Java
- Homepage:
- Size: 26.4 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
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](https://en.wikipedia.org/wiki/One-time_password) 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
```xml
dev.cerus
faktor
1.0.0
```
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
```java
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
```java
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
```java
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](/CONTRIBUTING.md) for more information.
## License
faktor is licensed under the [MIT License](https://opensource.org/license/mit).