- Notifications
You must be signed in to change notification settings - Fork35
A small and easy-to-use one-time password generator library for Java implementing RFC 4226 (HOTP) and RFC 6238 (TOTP).
License
BastiaanJansen/otp-java
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A small and easy-to-use one-time password generator for Java implementingRFC 4226 (HOTP) andRFC 6238 (TOTP).
The following features are supported:
- Generation of secrets
- Time-based one-time password (TOTP, RFC 6238) generation based on current time, specific time, OTPAuth URI and more for different HMAC algorithms.
- HMAC-based one-time password (HOTP, RFC 4226) generation based on counter and OTPAuth URI.
- Verification of one-time passwords
- Generation of OTP Auth URI's
<dependency> <groupId>com.github.bastiaanjansen</groupId> <artifactId>otp-java</artifactId> <version>2.1.0</version></dependency>
implementation'com.github.bastiaanjansen:otp-java:2.1.0'libraryDependencies+="com.github.bastiaanjansen"%"otp-java"%"2.1.0"
<dependencyorg="com.github.bastiaanjansen"name="otp-java"rev="2.1.0" />
Or you can download the source from theGitHub releases page.
To create aHOTPGenerator instance, use theHOTPGenerator.Builder class as follows:
Stringsecret ="VV3KOX7UQJ4KYAKOHMZPPH3US4CJIMH6F3ZKNB5C2OOBQ6V2KIYHM27Q";HOTPGeneratorhotp =newHOTPGenerator.Builder(secret).build();
The above builder creates a HOTP instance with default values for passwordLength = 6 and algorithm = SHA1. Use the builder to change these defaults:
HOTPGeneratorhotp =newHOTPGenerator.Builder(secret) .withPasswordLength(8) .withAlgorithm(HMACAlgorithm.SHA256) .build();
If you have a shared secret described inRFC-4226, you need to encode it first:
byte[]sharedSecret =getMySharedSecret();byte[]secret =Base32.encode(sharedSecret);
When you don't already have a secret, you can let the library generate it:
// To generate a Base32-encoded secret with 160 bitsbyte[]secret =SecretGenerator.generate();// To generate a Base32-encoded secret with a custom amount of bitsbyte[]secret =SecretGenerator.generate(512);
It is also possible to create a HOTP instance based on an OTPAuth URI. When algorithm or digits are not specified, the default values will be used.
URIuri =newURI("otpauth://hotp/issuer?secret=ABCDEFGHIJKLMNOP&algorithm=SHA1&digits=6&counter=8237");HOTPGeneratorhotp =HOTPGenerator.fromURI(uri);
Get information about the generator:
intpasswordLength =hotp.getPasswordLength();// 6HMACAlgorithmalgorithm =hotp.getAlgorithm();// HMACAlgorithm.SHA1
After creating an instance of the HOTP class, a code can be generated by using thegenerate() method:
try {intcounter =5;Stringcode =hotp.generate(counter);// To verify a token:booleanisValid =hotp.verify(code,counter);// Or verify with a delay windowbooleanisValid =hotp.verify(code,counter,2);}catch (IllegalStateExceptione) {// Handle error}
TOTP can accept more paramaters:passwordLength,period,algorithm andsecret. The default values are: passwordLength = 6, period = 30 and algorithm = SHA1.
// Generate a secret (or use your own secret)byte[]secret =SecretGenerator.generate();TOTPGeneratortotp =newTOTPGenerator.Builder(secret) .withHOTPGenerator(builder -> {builder.withPasswordLength(6);builder.withAlgorithm(HMACAlgorithm.SHA1);// SHA256 and SHA512 are also supported }) .withPeriod(Duration.ofSeconds(30)) .build();
Or create aTOTP instance from an OTPAuth URI:
URIuri =newURI("otpauth://totp/issuer?secret=ABCDEFGHIJKLMNOP&algorithm=SHA1&digits=6&period=30");TOTPGeneratortotpGenerator =TOTPGenerator.fromURI(uri);
Get information about the generator:
intpasswordLength =totpGenerator.getPasswordLength();// 6HMACAlgorithmalgorithm =totpGenerator.getAlgorithm();// HMACAlgorithm.SHA1Durationperiod =totpGenerator.getPeriod();// Duration.ofSeconds(30)
After creating an instance of the TOTP class, a code can be generated by using thenow() method, similarly with the HOTP class:
try {Stringcode =totpGenerator.now();// To verify a token:booleanisValid =totpGenerator.verify(code);}catch (IllegalStateExceptione) {// Handle error}
The above code will generate a time-based one-time password based on the current time. The API supports, besides the current time, the creation of codes based ontimeSince1970 in seconds,Date, andInstant:
try {// Based on current timetotpGenerator.now();// Based on specific datetotpGenerator.at(newDate());// Based on specific local datetotpGenerator.at(LocalDate.of(2023,3,2));// Based on seconds past 1970totpGenerator.at(9238346823);// Based on an instanttotpGenerator.at(Instant.now());}catch (IllegalStateExceptione) {// Handle error}
To easily generate a OTPAuth URI for easy on-boarding, use thegetURI() method for bothHOTP andTOTP. Example forTOTP:
TOTPGeneratortotpGenerator =newTOTPGenerator.Builder(secret).build();URIuri =totpGenerator.getURI("issuer","account");// otpauth://totp/issuer:account?period=30&digits=6&secret=SECRET&algorithm=SHA1
Often, services provide "backup codes" or "recovery codes" which can be used when the user cannot access the 2FA device anymore. Often because 2FA device is a mobile phone, which can be lost or stolen.
Because recovery code generation is not part of the specifications of OTP, it is not possible to generate recovery codes with this library and should be implemented seperately.
OTP-Java is available under the MIT License. See the LICENCE for more info.
About
A small and easy-to-use one-time password generator library for Java implementing RFC 4226 (HOTP) and RFC 6238 (TOTP).