TimeBasedOneTimePasswordUtil (Two Factor Auth 1.3 API)

java.lang.Object
- com.j256.twofactorauth.TimeBasedOneTimePasswordUtil

```
public class TimeBasedOneTimePasswordUtil
extends Object
```
Implementation of the Time-based One-Time Password (TOTP) two factor authentication algorithm. You need to:
1. Use generateBase32Secret() to generate a secret key for a user.
2. Store the secret key in the database associated with the user account.
3. Display the QR image URL returned by qrImageUrl(...) to the user.
4. User uses the image to load the secret key into his authenticator application.
Whenever the user logs in:
1. The user enters the number from the authenticator application into the login form.
2. Read the secret associated with the user account from the database.
3. The server compares the user input with the output from generateCurrentNumber(...).
4. If they are equal then the user is allowed to log in.
See: https://github.com/j256/two-factor-auth

For more details about this magic algorithm, see: http://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm
Author:

graywatson

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_OTP_LENGTH` default number of digits in a OTP string
`static int`	`DEFAULT_QR_DIMENTION` default hight/width of QR image
`static int`	`DEFAULT_TIME_STEP_SECONDS` default time-step which is part of the spec, 30 seconds is default

Constructor Summary

Constructors
Constructor and Description

TimeBasedOneTimePasswordUtil()

Constructors
Constructor and Description
`TimeBasedOneTimePasswordUtil()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static String`	`generateBase32Secret()` Generate and return a 16-character secret key in base32 format (A-Z2-7) using `SecureRandom`.
`static String`	`generateBase32Secret(int numDigits)` Similar to `generateBase32Secret()` but specifies a character length.
`static int`	`generateCurrentNumber(String base32Secret)` Similar to `generateCurrentNumberString(String)` but this returns a int instead of a string.
`static int`	`generateCurrentNumber(String base32Secret, int numDigits)` Similar to `generateCurrentNumberString(String, int)` but this returns a int instead of a string.
`static int`	`generateCurrentNumberHex(String hexSecret)` Similar to `generateCurrentNumberStringHex(String)` but this returns a int instead of a string.
`static int`	`generateCurrentNumberHex(String hexSecret, int numDigits)` Similar to `generateCurrentNumberStringHex(String, int)` but this returns a int instead of a string.
`static String`	`generateCurrentNumberString(String base32Secret)` Return the current number to be checked.
`static String`	`generateCurrentNumberString(String base32Secret, int numDigits)` Similar to `generateCurrentNumberString(String, int)` but you specify the number of digits.
`static String`	`generateCurrentNumberStringHex(String hexSecret)` Similar to `generateCurrentNumberString(String)` except this uses a hexadecimal secret.
`static String`	`generateCurrentNumberStringHex(String hexSecret, int numDigits)` Similar to `generateCurrentNumberString(String, int)` but you specify the number of digits.
`static String`	`generateHexSecret()` Generate and return a 32-character secret key in hexadecimal format (0-9A-F) using `SecureRandom`.
`static String`	`generateHexSecret(int numDigits)` Similar to `generateHexSecret()` but specifies a character length.
`static int`	`generateNumber(String base32Secret, long timeMillis, int timeStepSeconds)` Similar to `generateNumberString(String, long, int, int)` but this returns a int instead of a string.
`static int`	`generateNumber(String base32Secret, long timeMillis, int timeStepSeconds, int numDigits)` Similar to `#generateNumberString(String, long, int)` but this returns a int instead of a string.
`static int`	`generateNumberHex(String hexSecret, long timeMillis, int timeStepSeconds)` Similar to `#generateNumberStringHex(String, long, int, int))` but this returns a int instead of a string.
`static int`	`generateNumberHex(String hexSecret, long timeMillis, int timeStepSeconds, int numDigits)` Similar to `generateNumber(String, long, int, int)` but with a hexadecimal secret.
`static String`	`generateNumberString(String base32Secret, long timeMillis, int timeStepSeconds, int numDigits)` Similar to `generateCurrentNumberString(String)` except exposes other parameters.
`static String`	`generateNumberStringHex(String hexSecret, long timeMillis, int timeStepSeconds, int numDigits)` Similar to `generateNumberStringHex(String, long, int, int)` except it uses a hexadecimal secret.
`static String`	`generateOtpAuthUrl(String keyId, String secret)` Return the otp-auth part of the QR image which is suitable to be injected into other QR generators (e.g.
`static String`	`generateOtpAuthUrl(String keyId, String secret, int numDigits)` Return the otp-auth part of the QR image which is suitable to be injected into other QR generators (e.g.
`static String`	`qrImageUrl(String keyId, String secret)` Return the QR image url thanks to Google.
`static String`	`qrImageUrl(String keyId, String secret, int numDigits)` Return the QR image url thanks to Google.
`static String`	`qrImageUrl(String keyId, String secret, int numDigits, int imageDimension)` Return the QR image url thanks to Google.
`static boolean`	`validateCurrentNumber(String base32Secret, int authNumber, long windowMillis)` Validate a given secret-number using the secret base-32 string.
`static boolean`	`validateCurrentNumber(String base32Secret, int authNumber, long windowMillis, long timeMillis, int timeStepSeconds)` Similar to `#validateCurrentNumber(String, int, int)` except exposes other parameters.
`static boolean`	`validateCurrentNumber(String base32Secret, int authNumber, long windowMillis, long timeMillis, int timeStepSeconds, int numDigits)` Similar to `#validateCurrentNumber(String, int, int)` except exposes other parameters.
`static boolean`	`validateCurrentNumberHex(String hexSecret, int authNumber, long windowMillis)` Similar to `validateCurrentNumber(String, int, long)` except it uses a hexadecimal secret instead of base-32.
`static boolean`	`validateCurrentNumberHex(String hexSecret, int authNumber, long windowMillis, long timeMillis, int timeStepSeconds)` Similar to `#validateCurrentNumberHex(String, int, int)` except exposes other parameters.
`static boolean`	`validateCurrentNumberHex(String hexSecret, int authNumber, long windowMillis, long timeMillis, int timeStepSeconds, int numDigits)` Similar to `validateCurrentNumber(String, int, long, long, int, int)` except it uses hexadecimal secret instead of base-32.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_TIME_STEP_SECONDS
```
public static final int DEFAULT_TIME_STEP_SECONDS
```
    default time-step which is part of the spec, 30 seconds is default
    
    See Also:
    
    Constant Field Values
  - DEFAULT_OTP_LENGTH
```
public static int DEFAULT_OTP_LENGTH
```
    default number of digits in a OTP string
  - DEFAULT_QR_DIMENTION
```
public static int DEFAULT_QR_DIMENTION
```
    default hight/width of QR image
- Constructor Detail
  - TimeBasedOneTimePasswordUtil
```
public TimeBasedOneTimePasswordUtil()
```
- Method Detail
  - generateBase32Secret
```
public static String generateBase32Secret()
```
    Generate and return a 16-character secret key in base32 format (A-Z2-7) using SecureRandom. Could be used to generate the QR image to be shared with the user. Other lengths should use generateBase32Secret(int).
  - generateBase32Secret
```
public static String generateBase32Secret(int numDigits)
```
    Similar to generateBase32Secret() but specifies a character length.
  - generateHexSecret
```
public static String generateHexSecret()
```
    Generate and return a 32-character secret key in hexadecimal format (0-9A-F) using SecureRandom. Could be used to generate the QR image to be shared with the user. Other lengths should use generateHexSecret(int).
  - generateHexSecret
```
public static String generateHexSecret(int numDigits)
```
    Similar to generateHexSecret() but specifies a character length.
  - validateCurrentNumber
```
public static boolean validateCurrentNumber(String base32Secret,
                                            int authNumber,
                                            long windowMillis)
                                     throws GeneralSecurityException
```
    Validate a given secret-number using the secret base-32 string. This allows you to set a window in milliseconds to account for people being close to the end of the time-step. For example, if windowMillis is 10000 then this method will check the authNumber against the generated number from 10 seconds before now through 10 seconds after now.
    WARNING: This requires a system clock that is in sync with the world.
    
    Parameters:
    
    base32Secret - Secret string encoded using base-32 that was used to generate the QR code or shared with the user.
    
    authNumber - Time based number provided by the user from their authenticator application.
    
    windowMillis - Number of milliseconds that they are allowed to be off and still match. This checks before and after the current time to account for clock variance. Set to 0 for no window.
    
    Returns:
    
    True if the authNumber matched the calculated number within the specified window.
    
    Throws:
    
    GeneralSecurityException
  - validateCurrentNumberHex
```
public static boolean validateCurrentNumberHex(String hexSecret,
                                               int authNumber,
                                               long windowMillis)
                                        throws GeneralSecurityException
```
    Similar to validateCurrentNumber(String, int, long) except it uses a hexadecimal secret instead of base-32.
    
    Parameters:
    
    hexSecret - Secret string encoded in hexadecimal that was used to generate the QR code or shared with the user.
    
    authNumber - Time based number provided by the user from their authenticator application.
    
    windowMillis - Number of milliseconds that they are allowed to be off and still match. This checks before and after the current time to account for clock variance. Set to 0 for no window.
    
    Returns:
    
    True if the authNumber matched the calculated number within the specified window.
    
    Throws:
    
    GeneralSecurityException
  - validateCurrentNumber
```
public static boolean validateCurrentNumber(String base32Secret,
                                            int authNumber,
                                            long windowMillis,
                                            long timeMillis,
                                            int timeStepSeconds)
                                     throws GeneralSecurityException
```
    Similar to #validateCurrentNumber(String, int, int) except exposes other parameters. Mostly for testing.
    
    Parameters:
    
    base32Secret - Secret string encoded using base-32 that was used to generate the QR code or shared with the user.
    
    authNumber - Time based number provided by the user from their authenticator application.
    
    windowMillis - Number of milliseconds that they are allowed to be off and still match. This checks before and after the current time to account for clock variance. Set to 0 for no window.
    
    timeMillis - Time in milliseconds.
    
    timeStepSeconds - Time step in seconds. The default value is 30 seconds here. See DEFAULT_TIME_STEP_SECONDS.
    
    Returns:
    
    True if the authNumber matched the calculated number within the specified window.
    
    Throws:
    
    GeneralSecurityException
  - validateCurrentNumberHex
```
public static boolean validateCurrentNumberHex(String hexSecret,
                                               int authNumber,
                                               long windowMillis,
                                               long timeMillis,
                                               int timeStepSeconds)
                                        throws GeneralSecurityException
```
    Similar to #validateCurrentNumberHex(String, int, int) except exposes other parameters. Mostly for testing.
    
    Parameters:
    
    hexSecret - Secret string encoded in hexadecimal that was used to generate the QR code or shared with the user.
    
    authNumber - Time based number provided by the user from their authenticator application.
    
    windowMillis - Number of milliseconds that they are allowed to be off and still match. This checks before and after the current time to account for clock variance. Set to 0 for no window.
    
    timeMillis - Time in milliseconds.
    
    timeStepSeconds - Time step in seconds. The default value is 30 seconds here. See DEFAULT_TIME_STEP_SECONDS.
    
    Returns:
    
    True if the authNumber matched the calculated number within the specified window.
    
    Throws:
    
    GeneralSecurityException
  - validateCurrentNumber
```
public static boolean validateCurrentNumber(String base32Secret,
                                            int authNumber,
                                            long windowMillis,
                                            long timeMillis,
                                            int timeStepSeconds,
                                            int numDigits)
                                     throws GeneralSecurityException
```
    Similar to #validateCurrentNumber(String, int, int) except exposes other parameters. Mostly for testing.
    
    Parameters:
    
    base32Secret - Secret string encoded using base-32 that was used to generate the QR code or shared with the user.
    
    authNumber - Time based number provided by the user from their authenticator application.
    
    windowMillis - Number of milliseconds that they are allowed to be off and still match. This checks before and after the current time to account for clock variance. Set to 0 for no window.
    
    timeMillis - Time in milliseconds.
    
    timeStepSeconds - Time step in seconds. The default value is 30 seconds here. See DEFAULT_TIME_STEP_SECONDS.
    
    numDigits - The number of digits of the OTP.
    
    Returns:
    
    True if the authNumber matched the calculated number within the specified window.
    
    Throws:
    
    GeneralSecurityException
  - validateCurrentNumberHex
```
public static boolean validateCurrentNumberHex(String hexSecret,
                                               int authNumber,
                                               long windowMillis,
                                               long timeMillis,
                                               int timeStepSeconds,
                                               int numDigits)
                                        throws GeneralSecurityException
```
    Similar to validateCurrentNumber(String, int, long, long, int, int) except it uses hexadecimal secret instead of base-32.
    
    Parameters:
    
    hexSecret - Secret string encoded in hexadecimal that was used to generate the QR code or shared with the user.
    
    authNumber - Time based number provided by the user from their authenticator application.
    
    windowMillis - Number of milliseconds that they are allowed to be off and still match. This checks before and after the current time to account for clock variance. Set to 0 for no window.
    
    timeMillis - Time in milliseconds.
    
    timeStepSeconds - Time step in seconds. The default value is 30 seconds here. See DEFAULT_TIME_STEP_SECONDS.
    
    numDigits - The number of digits of the OTP.
    
    Returns:
    
    True if the authNumber matched the calculated number within the specified window.
    
    Throws:
    
    GeneralSecurityException
  - generateCurrentNumberString
```
public static String generateCurrentNumberString(String base32Secret)
                                          throws GeneralSecurityException
```
    Return the current number to be checked. This can be compared against user input.
    WARNING: This requires a system clock that is in sync with the world.
    
    Parameters:
    
    base32Secret - Secret string encoded using base-32 that was used to generate the QR code or shared with the user.
    
    Returns:
    
    A number as a string with possible leading zeros which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateCurrentNumberStringHex
```
public static String generateCurrentNumberStringHex(String hexSecret)
                                             throws GeneralSecurityException
```
    Similar to generateCurrentNumberString(String) except this uses a hexadecimal secret.
    
    Parameters:
    
    hexSecret - Secret string encoded in hexadecimal that was used to generate the QR code or shared with the user.
    
    Returns:
    
    A number as a string with possible leading zeros which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateCurrentNumberString
```
public static String generateCurrentNumberString(String base32Secret,
                                                 int numDigits)
                                          throws GeneralSecurityException
```
    Similar to generateCurrentNumberString(String, int) but you specify the number of digits.
    
    Parameters:
    
    base32Secret - Secret string encoded using base-32 that was used to generate the QR code or shared with the user.
    
    numDigits - The number of digits of the OTP.
    
    Returns:
    
    A number as a string with possible leading zeros which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateCurrentNumberStringHex
```
public static String generateCurrentNumberStringHex(String hexSecret,
                                                    int numDigits)
                                             throws GeneralSecurityException
```
    Similar to generateCurrentNumberString(String, int) but you specify the number of digits.
    
    Parameters:
    
    hexSecret - Secret string encoded in hexadecimal that was used to generate the QR code or shared with the user.
    
    numDigits - The number of digits of the OTP.
    
    Returns:
    
    A number as a string with possible leading zeros which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateNumberString
```
public static String generateNumberString(String base32Secret,
                                          long timeMillis,
                                          int timeStepSeconds,
                                          int numDigits)
                                   throws GeneralSecurityException
```
    Similar to generateCurrentNumberString(String) except exposes other parameters. Mostly for testing.
    
    Parameters:
    
    base32Secret - Secret string encoded using base-32 that was used to generate the QR code or shared with the user.
    
    timeMillis - Time in milliseconds.
    
    timeStepSeconds - Time step in seconds. The default value is 30 seconds here. See DEFAULT_TIME_STEP_SECONDS.
    
    numDigits - The number of digits of the OTP.
    
    Returns:
    
    A number as a string with possible leading zeros which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateNumberStringHex
```
public static String generateNumberStringHex(String hexSecret,
                                             long timeMillis,
                                             int timeStepSeconds,
                                             int numDigits)
                                      throws GeneralSecurityException
```
    Similar to generateNumberStringHex(String, long, int, int) except it uses a hexadecimal secret.
    
    Parameters:
    
    hexSecret - Secret string encoded in hexadecimal that was used to generate the QR code or shared with the user.
    
    timeMillis - Time in milliseconds.
    
    timeStepSeconds - Time step in seconds. The default value is 30 seconds here. See DEFAULT_TIME_STEP_SECONDS.
    
    numDigits - The number of digits of the OTP.
    
    Returns:
    
    A number as a string with possible leading zeros which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateCurrentNumber
```
public static int generateCurrentNumber(String base32Secret)
                                 throws GeneralSecurityException
```
    Similar to generateCurrentNumberString(String) but this returns a int instead of a string.
    
    Returns:
    
    A number which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateCurrentNumberHex
```
public static int generateCurrentNumberHex(String hexSecret)
                                    throws GeneralSecurityException
```
    Similar to generateCurrentNumberStringHex(String) but this returns a int instead of a string.
    
    Returns:
    
    A number which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateCurrentNumber
```
public static int generateCurrentNumber(String base32Secret,
                                        int numDigits)
                                 throws GeneralSecurityException
```
    Similar to generateCurrentNumberString(String, int) but this returns a int instead of a string.
    
    Returns:
    
    A number which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateCurrentNumberHex
```
public static int generateCurrentNumberHex(String hexSecret,
                                           int numDigits)
                                    throws GeneralSecurityException
```
    Similar to generateCurrentNumberStringHex(String, int) but this returns a int instead of a string.
    
    Returns:
    
    A number which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateNumber
```
public static int generateNumber(String base32Secret,
                                 long timeMillis,
                                 int timeStepSeconds)
                          throws GeneralSecurityException
```
    Similar to generateNumberString(String, long, int, int) but this returns a int instead of a string.
    
    Returns:
    
    A number which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateNumberHex
```
public static int generateNumberHex(String hexSecret,
                                    long timeMillis,
                                    int timeStepSeconds)
                             throws GeneralSecurityException
```
    Similar to #generateNumberStringHex(String, long, int, int)) but this returns a int instead of a string.
    
    Returns:
    
    A number which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateNumber
```
public static int generateNumber(String base32Secret,
                                 long timeMillis,
                                 int timeStepSeconds,
                                 int numDigits)
                          throws GeneralSecurityException
```
    Similar to #generateNumberString(String, long, int) but this returns a int instead of a string.
    
    Returns:
    
    A number which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - generateNumberHex
```
public static int generateNumberHex(String hexSecret,
                                    long timeMillis,
                                    int timeStepSeconds,
                                    int numDigits)
                             throws GeneralSecurityException
```
    Similar to generateNumber(String, long, int, int) but with a hexadecimal secret.
    
    Returns:
    
    A number which should match the user's authenticator application output.
    
    Throws:
    
    GeneralSecurityException
  - qrImageUrl
```
public static String qrImageUrl(String keyId,
                                String secret)
```
    Return the QR image url thanks to Google. This can be shown to the user and scanned by the authenticator program as an easy way to enter the secret.
    
    Parameters:
    
    keyId - Name of the key that you want to show up in the users authentication application. Should already be URL encoded.
    
    secret - Secret string that will be used when generating the current number.
  - qrImageUrl
```
public static String qrImageUrl(String keyId,
                                String secret,
                                int numDigits)
```
    Return the QR image url thanks to Google. This can be shown to the user and scanned by the authenticator program as an easy way to enter the secret.
    
    Parameters:
    
    keyId - Name of the key that you want to show up in the users authentication application. Should already be URL encoded.
    
    secret - Secret string that will be used when generating the current number.
    
    numDigits - The number of digits of the OTP.
  - qrImageUrl
```
public static String qrImageUrl(String keyId,
                                String secret,
                                int numDigits,
                                int imageDimension)
```
    Return the QR image url thanks to Google. This can be shown to the user and scanned by the authenticator program as an easy way to enter the secret.
    
    Parameters:
    
    keyId - Name of the key that you want to show up in the users authentication application. Should already be URL encoded.
    
    secret - Secret string that will be used when generating the current number.
    
    numDigits - The number of digits of the OTP. Can be set to DEFAULT_OTP_LENGTH.
    
    imageDimension - The dimension of the image, width and height. Can be set to DEFAULT_QR_DIMENTION.
  - generateOtpAuthUrl
```
public static String generateOtpAuthUrl(String keyId,
                                        String secret)
```
    Return the otp-auth part of the QR image which is suitable to be injected into other QR generators (e.g. JS generator).
    
    Parameters:
    
    keyId - Name of the key that you want to show up in the users authentication application. Should already be URL encoded.
    
    secret - Secret string that will be used when generating the current number.
  - generateOtpAuthUrl
```
public static String generateOtpAuthUrl(String keyId,
                                        String secret,
                                        int numDigits)
```
    Return the otp-auth part of the QR image which is suitable to be injected into other QR generators (e.g. JS generator).
    
    Parameters:
    
    keyId - Name of the key that you want to show up in the users authentication application. Should already be URL encoded.
    
    secret - Secret string that will be used when generating the current number.
    
    numDigits - The number of digits" of the OTP.

Class TimeBasedOneTimePasswordUtil

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_TIME_STEP_SECONDS

DEFAULT_OTP_LENGTH

DEFAULT_QR_DIMENTION

Constructor Detail

TimeBasedOneTimePasswordUtil

Method Detail

generateBase32Secret

generateBase32Secret

generateHexSecret

generateHexSecret

validateCurrentNumber

validateCurrentNumberHex

validateCurrentNumber

validateCurrentNumberHex

validateCurrentNumber

validateCurrentNumberHex

generateCurrentNumberString

generateCurrentNumberStringHex

generateCurrentNumberString

generateCurrentNumberStringHex

generateNumberString

generateNumberStringHex

generateCurrentNumber

generateCurrentNumberHex

generateCurrentNumber

generateCurrentNumberHex

generateNumber

generateNumberHex

generateNumber

generateNumberHex

qrImageUrl

qrImageUrl

qrImageUrl

generateOtpAuthUrl

generateOtpAuthUrl