Package com.iizix.server.user.mfa

Class MFAUser

java.lang.Object
com.iizix.server.user.mfa.MFAUser
public class MFAUser extends Object
The class used to provide an MFA authentication using a TOTP based QR code. The authentication software will use this QR code to set-up the users' account. The sign in, the user will have to provide a six digit code that is valid during a certain period of time, generally 60 seconds, with a time drift of +/-30 seconds. Oftentimes, allow codes valid for 2 time periods before/after to pass as valid.

  • Field Details

    • SECRET_LENGTH

      public static final int SECRET_LENGTH
      The default number of characters in the secret: 32.
      See Also:

    • DIGITS

      public static final int DIGITS
      The default number of digits: 6.
      See Also:

    • PERIOD

      public final int PERIOD
      The drift period, default +/- 30 seconds.
      See Also:

    • DEFAULT_TIME_PROVIDER_HOST

      public static String DEFAULT_TIME_PROVIDER_HOST
      The default time provider host: "pool.ntp.org".

    • DEFAULT_TIMEOUT_MILLISECONDS

      public static int DEFAULT_TIMEOUT_MILLISECONDS
      Default timeout in milliseconds: 3_000 (or 3 seconds).

  • Constructor Details

    • MFAUser

      public MFAUser(String appName, String account)
      Constructor of the instance for a six digit code.
      Parameters:
      appName - The application name as the issuer, in localized form (should never change).
      account - The account name is generally something to identify uniquely the user, generally an email address.

  • Method Details

    • setDigits

      public MFAUser setDigits(int digits)
      Sets the number of digits to use for the code.

      Setting how many digits long the generated codes are:

      Most TOTP implementations generate codes that are 6 digits long, but codes can have a length of any positive non-zero integer.

      Parameters:
      digits - The requested number of digits (default 6, minimum 4 and maximum 8 is recommended).
      Returns:
      "this" instance for concatenation.
      Throws:
      IllegalArgumentException - If digits range is not within 4 to 8.

    • setPeriod

      public MFAUser setPeriod(int period)
      Sets the drift period in +/- seconds to use, default is PERIOD = 30.

      Setting the time period and discrepancy:

      The one time password codes generated in the authenticator apps only last for a certain time period before they are re-generated, and most implementations of TOTP allow room for codes that have recently expired, or will only "become valid" soon in the future to be accepted as valid, to allow for a small time drift between the server and the authenticator app (discrepancy).

      Parameters:
      period - The requested period in seconds (range is 10 to 60).
      Returns:
      "this" instance for concatenation.
      Throws:
      IllegalArgumentException - If period range is not within 10 to 60 seconds.

    • setAlgorithm

      public MFAUser setAlgorithm(MFAUser.Hashing alg)
      Sets the algorithm to use when creating the QR code.
      Parameters:
      alg - The hashing algorithm.
      Returns:
      "this" instance for concatenation.

    • generateSecret

      public MFAUser generateSecret()
      Generate the secret with the secretLength specified, default SECRET_LENGTH = 32. The secret is only generated once, so there is no point in calling this method many times, nothing will happen.
      Returns:
      "this" instance for concatenation.

    • getSecret

      public String getSecret()
      Gets or generate the secret with the secretLength specified, default SECRET_LENGTH = 32, if not previously done.
      Returns:
      The secret.

    • generateQRCodeData

      public BarcodeURN generateQRCodeData(ErrorCorrectionLevel errorCorrectionLevel) throws BarcodeException
      Generate the QR code data with relevant information with specified error correction level.
      Parameters:
      errorCorrectionLevel - null for default L = Low = ~7% error correction level.
      Returns:
      The generated barcode URN from where e.g. an SVG can be extracted.
      Throws:
      IllegalStateException - If the secret is missing (has not been generated).
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.

    • setTimeProvider

      public MFAUser setTimeProvider(String timeProviderHost, int timeoutMilliseconds)
      Before validating a code, the time provider host and the timeout value in milliseconds can be set. If this is not done, the default values are used:
       
   timeProviderHost    = DEFAULT_TIME_PROVIDER_HOST
   timeoutMilliseconds = DEFAULT_TIMEOUT_MILLISECONDS
      Parameters:
      timeProviderHost - The time provider host.
      timeoutMilliseconds - The timeout value in milliseconds (must be over 500 milliseconds).
      Returns:
      "this" instance for concatenation.
      Throws:
      IllegalArgumentException - If the timeoutMilliseconds value is less than 500 milliseconds or larger than 60_000 milliseconds (1 minute).
      NullPointerException - If the timeProviderHost is null.

    • validateCode

      public boolean validateCode(String code) throws UnknownHostException
      Validates a code.
      Parameters:
      code - The code.
      Returns:
      The valid code flag.
      Throws:
      UnknownHostException - In case the timeProviderHost is an unknown host.