Package eu.webtoolkit.jwt.auth.mfa

Class Totp

java.lang.Object

eu.webtoolkit.jwt.auth.mfa.Totp

public class Totp
extends Object

Utility class containing functions for TOTP functionality.

Method Summary

Modifier and Type	Method	Description
static final String	generateCode(String key, int codeDigits, Duration time)	Generates a TOTP (Time-Based One-Time Password) code.
static String	generateCode(String key, int codeDigits, Duration time, Duration startTime)	Generates a TOTP (Time-Based One-Time Password) code.
static final String	generateSecretKey()	Generate a secret key, for Multi-Factor Authentication.
static String	generateSecretKey(int length)	Generate a secret key, for Multi-Factor Authentication.
static final boolean	validateCode(String key, String code, int codeDigits, Duration time)	Validate the given code with the given time frame.
static boolean	validateCode(String key, String code, int codeDigits, Duration time, Duration startTime)	Validate the given code with the given time frame.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

generateSecretKey

public static String generateSecretKey(int length)

Generate a secret key, for Multi-Factor Authentication.

This will generate a base32-encoded string, of length. This will only contain characters from [A-Z2-7]. The generated string is created securely, and sufficiently random for cryptographic purposes.

This string returned by this function can be used for a user as their shared secret to generate and verify TOTP codes.

Secret keys with length between 16 and 256 are allowed. By default the length will be 32.

generateSecretKey

public static final String generateSecretKey()

Generate a secret key, for Multi-Factor Authentication.

Returns generateSecretKey(32)

generateCode

public static String generateCode(String key,
 int codeDigits,
 Duration time,
 Duration startTime)

Generates a TOTP (Time-Based One-Time Password) code.

This code is generated from a secret key, at the specified time. The code will be of length codeDigits.

The key should be a base32-encoded string, with a length between 16 and 256. The codeDigits parameter should be at least 6 characters, and at most be 16 characters long. Supplying a codeDigits outside of this boundary will result in an exception being thrown.

The specified time will be the time the code is generated. This ensures that the TOTP algorithm generates a different code for each time window, where the width of a window is 30 seconds.

The startTime is optional and is used to define an offset. This offset will be subtracted from the actual time. It can be used to define a starting point.

generateCode

public static final String generateCode(String key,
 int codeDigits,
 Duration time)

Generates a TOTP (Time-Based One-Time Password) code.

Returns generateCode(key, codeDigits, time, Duration.ofSeconds(0))

validateCode

public static boolean validateCode(String key,
 String code,
 int codeDigits,
 Duration time,
 Duration startTime)

Validate the given code with the given time frame.

Here the key is the secret key attached to the User, the code is the TOTP code the user has entered, which is expected to be of length codeDigits. This length is configured in AuthService#setMfaCodeLength().

The time specifies the time window for which the code is valid. When this function executes, the code will be generated for the time frame the passed time falls in, and in the previous window. Each window has a width of 30 seconds. Meaning that at most a user has 1 minute to enter the code (if they submit it immediately at the start of the first time frame). Or at least 30 seconds (if they submit it at the end of the first time frame).

Time frames start either immediately on the minute, or halfway. This means that for the times:

• 12:52:12, the start time frame will be 12:52:00
• 12:52:48, the start time frame will be 12:52:30

The startTime is optional and is used to define an offset. This offset will be subtracted from the actual time. It can be used to define a starting point.

validateCode

public static final boolean validateCode(String key,
 String code,
 int codeDigits,
 Duration time)

Validate the given code with the given time frame.

Returns validateCode(key, code, codeDigits, time, Duration.ofSeconds(0))