Namespace for Multi-Factor Authentication. More...

Classes
class	AuthenticationResult
	A class that holds an authentication result. More...

class	AbstractMfaProcess
	The interface for a second factor authentication process. More...

class	TotpProcess
	A process managing the TOTP setup and validation. More...

class	TotpQrCode
	A QR code generator for TOTP secret keys. More...

Enumerations
enum class	AuthenticationStatus { Success , Failure , Error }
	Enumeration that holds the result of the authentication event. More...

Functions
std::string	generateSecretKey (int length=32)
	Generate a secret key, for Multi-Factor Authentication. More...

std::string	generateCode (const std::string &key, int codeDigits, std::chrono::seconds time, std::chrono::seconds startTime=std::chrono::seconds(0))
	Generates a TOTP (Time-Based One-Time Password) code. More...

bool	validateCode (const std::string &key, const std::string &code, int codeDigits, std::chrono::seconds time, std::chrono::seconds startTime=std::chrono::seconds(0))
	Validate the given `code` with the given time frame. More...

Detailed Description

Namespace for Multi-Factor Authentication.

Enumeration Type Documentation

◆ AuthenticationStatus

enum Wt::Auth::Mfa::AuthenticationStatus

strong

Enumeration that holds the result of the authentication event.

The authentication event as a second step in the authentication flow, will have a certain result after the user submits their input.

Enumerator
Success	Indicates a successful authentication event.
Failure	Indicates a failure to authenticate.
Error	An error was encountered when trying to authenticate.

Function Documentation

◆ generateCode()

WT_NODISCARD WT_API std::string Wt::Auth::Mfa::generateCode	(	const std::string &	key,
		int	codeDigits,
		std::chrono::seconds	time,
		std::chrono::seconds	startTime = `std::chrono::seconds(0)`
	)

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.

Exceptions

WException if the codeDigits specified isn't within the range [6, 16].

◆ generateSecretKey()

WT_NODISCARD WT_API std::string Wt::Auth::Mfa::generateSecretKey ( int length = 32 )

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.

Exceptions

WException if the length specified isn't within the range [16, 256].

See also: WRandom

◆ validateCode()

WT_NODISCARD WT_API bool Wt::Auth::Mfa::validateCode	(	const std::string &	key,
		const std::string &	code,
		int	codeDigits,
		std::chrono::seconds	time,
		std::chrono::seconds	startTime = `std::chrono::seconds(0)`
	)

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