com.warrenstrange.googleauth

Class GoogleAuthenticator

java.lang.Object

com.warrenstrange.googleauth.GoogleAuthenticator

All Implemented Interfaces:

IGoogleAuthenticator

public final class GoogleAuthenticator
extends Object
implements IGoogleAuthenticator

This class implements the functionality described in RFC 6238 (TOTP: Time based one-time password algorithm) and has been tested again Google's implementation of such algorithm in its Google Authenticator application.

This class lets users create a new 16-bit base32-encoded secret key with the validation code calculated at time = 0 (the UNIX epoch) and the URL of a Google-provided QR barcode to let an user load the generated information into Google Authenticator.

The random number generator used by this class uses the default algorithm and provider. Users can override them by setting the following system properties to the algorithm and provider name of their choice:

• RNG_ALGORITHM.
• RNG_ALGORITHM_PROVIDER.

This class does not store in any way either the generated keys nor the keys passed during the authorization process.

Java Server side class for Google Authenticator's TOTP generator was inspired by an author's blog post.

Since:

0.3.0

Version:

0.5.0

Author:

Enrico M. Crisostomo, Warren Strange

See Also:

, ,

Field Summary

Fields

Modifier and Type	Field and Description
static String	RNG_ALGORITHM The system property to specify the random number generator algorithm to use.
static String	RNG_ALGORITHM_PROVIDER The system property to specify the random number generator provider to use.
static int	SCRATCH_CODE_MODULUS Modulus used to truncate the scratch code.

Constructor Summary

Constructors

Constructor and Description
GoogleAuthenticator()
GoogleAuthenticator(GoogleAuthenticatorConfig config)

Method Summary

Modifier and Type	Method and Description
boolean	authorize(String secret, int verificationCode) Checks a verification code against a secret key using the current time.
boolean	authorize(String secret, int verificationCode, long time) Checks a verification code against a secret key using the specified time.
boolean	authorizeUser(String userName, int verificationCode) This method validates a verification code of the specified user whose private key is retrieved from the configured credential repository using the current time.
boolean	authorizeUser(String userName, int verificationCode, long time) This method validates a verification code of the specified user whose private key is retrieved from the configured credential repository.
GoogleAuthenticatorKey	createCredentials() This method generates a new set of credentials including: Secret key. Validation code. A list of scratch codes. The user must register this secret on their device.
GoogleAuthenticatorKey	createCredentials(String userName) This method generates a new set of credentials invoking the #createCredentials method with no arguments.
ICredentialRepository	getCredentialRepository() This method loads the first available ICredentialRepository registered using the Java service loader API.
int	getTotpPassword(String secret) This method generates the current TOTP password.
int	getTotpPassword(String secret, long time) This method generates the TOTP password at the specified time.
int	getTotpPasswordOfUser(String userName) This method generates the current TOTP password.
int	getTotpPasswordOfUser(String userName, long time) This method generates the TOTP password at the specified time.
void	setCredentialRepository(ICredentialRepository repository) This method sets the credential repository used by this instance.

Methods inherited from class java.lang.Object

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

Field Detail

RNG_ALGORITHM

public static final String RNG_ALGORITHM

The system property to specify the random number generator algorithm to use.

Since:

0.5.0

See Also:

Constant Field Values

RNG_ALGORITHM_PROVIDER

public static final String RNG_ALGORITHM_PROVIDER

The system property to specify the random number generator provider to use.

Since:

0.5.0

See Also:

Constant Field Values

SCRATCH_CODE_MODULUS

public static final int SCRATCH_CODE_MODULUS

Modulus used to truncate the scratch code.

Constructor Detail

GoogleAuthenticator

public GoogleAuthenticator()

GoogleAuthenticator

public GoogleAuthenticator(GoogleAuthenticatorConfig config)

Method Detail

createCredentials

public GoogleAuthenticatorKey createCredentials()

Description copied from interface: IGoogleAuthenticator

This method generates a new set of credentials including:

1. Secret key.
2. Validation code.
3. A list of scratch codes.

The user must register this secret on their device.

Specified by:

createCredentials in interface IGoogleAuthenticator

Returns:

secret key

createCredentials

public GoogleAuthenticatorKey createCredentials(String userName)

Description copied from interface: IGoogleAuthenticator

This method generates a new set of credentials invoking the #createCredentials method with no arguments. The generated credentials are then saved using the configured #ICredentialRepository service.

The user must register this secret on their device.

Specified by:

createCredentials in interface IGoogleAuthenticator

Parameters:

userName - the user name.

Returns:

secret key

getTotpPassword

public int getTotpPassword(String secret)

Description copied from interface: IGoogleAuthenticator

This method generates the current TOTP password.

Specified by:

getTotpPassword in interface IGoogleAuthenticator

Parameters:

secret - the encoded secret key.

Returns:

the current TOTP password.

getTotpPassword

public int getTotpPassword(String secret,
                           long time)

Description copied from interface: IGoogleAuthenticator

This method generates the TOTP password at the specified time.

Specified by:

getTotpPassword in interface IGoogleAuthenticator

Parameters:

secret - The encoded secret key.

time - The time to use to calculate the password.

Returns:

the TOTP password at the specified time.

getTotpPasswordOfUser

public int getTotpPasswordOfUser(String userName)

Description copied from interface: IGoogleAuthenticator

This method generates the current TOTP password.

Specified by:

getTotpPasswordOfUser in interface IGoogleAuthenticator

Parameters:

userName - The user whose password must be created.

Returns:

the current TOTP password.

getTotpPasswordOfUser

public int getTotpPasswordOfUser(String userName,
                                 long time)

Description copied from interface: IGoogleAuthenticator

This method generates the TOTP password at the specified time.

Specified by:

getTotpPasswordOfUser in interface IGoogleAuthenticator

Parameters:

userName - The user whose password must be created.

time - The time to use to calculate the password.

Returns:

the TOTP password at the specified time.

authorize

public boolean authorize(String secret,
                         int verificationCode)
                  throws GoogleAuthenticatorException

Description copied from interface: IGoogleAuthenticator

Checks a verification code against a secret key using the current time.

Specified by:

authorize in interface IGoogleAuthenticator

Parameters:

secret - the encoded secret key.

verificationCode - the verification code.

Returns:

true if the validation code is valid, false otherwise.

Throws:

GoogleAuthenticatorException - if a failure occurs during the calculation of the validation code. The only failures that should occur are related with the cryptographic functions provided by the JCE.

See Also:

IGoogleAuthenticator.authorize(String, int, long)

authorize

public boolean authorize(String secret,
                         int verificationCode,
                         long time)
                  throws GoogleAuthenticatorException

Description copied from interface: IGoogleAuthenticator

Checks a verification code against a secret key using the specified time. The algorithm also checks in a time window whose size determined by the windowSize property of this class.

The default value of 30 seconds recommended by RFC 6238 is used for the interval size.

Specified by:

authorize in interface IGoogleAuthenticator

Parameters:

secret - The encoded secret key.

verificationCode - The verification code.

time - The time to use to calculate the TOTP password..

Returns:

true if the validation code is valid, false otherwise.

Throws:

GoogleAuthenticatorException - if a failure occurs during the calculation of the validation code. The only failures that should occur are related with the cryptographic functions provided by the JCE.

authorizeUser

public boolean authorizeUser(String userName,
                             int verificationCode)
                      throws GoogleAuthenticatorException

Description copied from interface: IGoogleAuthenticator

This method validates a verification code of the specified user whose private key is retrieved from the configured credential repository using the current time. This method delegates the validation to the IGoogleAuthenticator.authorizeUser(String, int, long).

Specified by:

authorizeUser in interface IGoogleAuthenticator

Parameters:

userName - The user whose verification code is to be validated.

verificationCode - The validation code.

Returns:

true if the validation code is valid, false otherwise.

Throws:

GoogleAuthenticatorException - if an unexpected error occurs.

See Also:

IGoogleAuthenticator.authorize(String, int)

authorizeUser

public boolean authorizeUser(String userName,
                             int verificationCode,
                             long time)
                      throws GoogleAuthenticatorException

Description copied from interface: IGoogleAuthenticator

This method validates a verification code of the specified user whose private key is retrieved from the configured credential repository. This method delegates the validation to the IGoogleAuthenticator.authorize(String, int, long) method.

Specified by:

authorizeUser in interface IGoogleAuthenticator

Parameters:

userName - The user whose verification code is to be validated.

verificationCode - The validation code.

time - The time to use to calculate the TOTP password.

Returns:

true if the validation code is valid, false otherwise.

Throws:

GoogleAuthenticatorException - if an unexpected error occurs.

See Also:

IGoogleAuthenticator.authorize(String, int)

getCredentialRepository

public ICredentialRepository getCredentialRepository()

This method loads the first available ICredentialRepository registered using the Java service loader API.

Specified by:

getCredentialRepository in interface IGoogleAuthenticator

Returns:

the first registered ICredentialRepository or null if none is found.

setCredentialRepository

public void setCredentialRepository(ICredentialRepository repository)

Description copied from interface: IGoogleAuthenticator

This method sets the credential repository used by this instance. If null is passed to this method, no credential repository will be used, nor discovered using the ServiceLoader API.

Specified by:

setCredentialRepository in interface IGoogleAuthenticator

Parameters:

repository - The credential repository to use, or null to disable this feature.