DOCSEARCHbyAlgolia
Submit Docs

pquerna/otp

repository·master·Indexed 25 days ago

https://github.com/pquerna/otp

A Go library providing utilities for implementing One-Time Password (OTP) mechanisms, specifically supporting TOTP (RFC 6238) and HOTP (RFC 4226) algorithms. It includes functionality for generating and validating passcodes, creating QR code images for user enrollment, and managing OTP keys via URLs.

Tokens
1K
Snippets
0
Records
11
Agent score
34%

What's inside pquerna-otp

  1. Implement TOTP User Enrollment

    master

    To enroll a user in TOTP (Time-based One-time Password), follow these steps:

    1. Generate a new TOTP Key: Use totp.Generate(...) to create a new key for the user.
    2. Display Secret and QR Code: Show the user their secret via key.Secret() and provide a QR code for easy scanning using key.Image(...).
    3. Verify Setup: Test that the user can successfully use their TOTP by calling totp.Validate(...) with the code they provide.
    4. Store the Secret: Save the user's TOTP secret (key.Secret()) in your backend database.
    5. Provide Recovery Codes: Generate and provide recovery codes to the user in case they lose access to their device.

  2. Validate TOTP passcodes

    master

    To validate a user's TOTP passcode during login:

    1. Prompt and validate the user's password as usual.
    2. If TOTP is enabled for the user, prompt for their TOTP passcode.
    3. Retrieve the user's stored TOTP Secret from your backend.
    4. Validate the passcode using totp.Validate(...).

  3. Generate TOTP or HOTP codes

    master

    You can generate valid codes compatible with most implementations using the following methods:

    • Standard Generation: Use GenerateCode and provide either a counter (for HOTP) or a time.Time struct (for TOTP).
    • Custom Generation: For uncommon or custom settings, or to handle specific error cases, use GenerateCodeCustom in either the totp or hotp modules.

  4. Implement Recovery Codes

    master

    Since TOTP devices (like mobile phones) can be lost or stolen, you should implement a recovery code system. Recovery codes are a set of one-time-use strings that allow users to bypass the TOTP requirement.

    Implementation pattern:

    • Generate a set of random strings.
    • Store these strings in your backend associated with the user.
    • Allow the user to use one of these strings in place of a TOTP code during authentication.

  5. Extract configuration from a Key

    master

    Once a Key is created from a URL, you can retrieve its configuration using the following methods:

    • Type(): Returns "hotp" or "totp".
    • Issuer(): Returns the name of the issuing organization.
    • AccountName(): Returns the name of the user's account.
    • Secret(): Returns the opaque base32 secret.
    • Period(): Returns the rotation time in seconds (defaults to 30 if not specified).
    • Digits(): Returns the number of OTP digits (defaults to DigitsSix).
    • Algorithm(): Returns the hashing algorithm used (defaults to AlgorithmSHA1).
    • Encoder(): Returns the encoder used (e.g., EncoderSteam).
    • URL(): Returns the original OTP URL as a string.

  6. Create a Key from an OTP URL

    master
    Use NewKeyFromURL to initialize a Key object from an existing TOTP or HOTP URI. The URI format should follow the Google Authenticator Key URI format. The resulting Key object provides access to the secret, issuer, account name, and other configuration parameters extracted from the URL.

  7. Generate a QR Code image for user enrollment

    master
    The Image(width int, height int) method on a Key returns an image.Image representing a QR code of the specified dimensions. This image is suitable for displaying to users so they can scan it with authenticator apps like Google Authenticator to enroll their TOTP/HOTP key.

  8. Error types for Key validation

    master

    The following error variables are exported for checking failure states:

    • ErrValidateSecretInvalidBase32: Occurs when decoding a secret from base32 fails.
    • ErrValidateInputInvalidLength: Occurs when the provided passcode length is unexpected.
    • ErrGenerateMissingIssuer: Occurs when generating a Key without an Issuer.
    • ErrGenerateMissingAccountName: Occurs when generating a Key without an AccountName.

  10. Use Digits constants and formatting

    master
    The Digits type represents the number of digits in the OTP passcode. Common values are DigitsSix (6) and DigitsEight (8). The Format(in int32) method converts an integer into a zero-filled string based on the digit count.

  11. Use Algorithm constants and types

    master

    The Algorithm type defines the hashing function used in the HMAC operation. Supported algorithms are:

    • AlgorithmSHA1: Recommended for compatibility with Google Authenticator.
    • AlgorithmSHA256
    • AlgorithmSHA512
    • AlgorithmMD5

    Each Algorithm provides a .String() method for its name and a .Hash() method that returns the corresponding hash.Hash implementation.