📚 otpgo - Awesome Go Library for Authentication and OAuth

Go Gopher mascot for otpgo

Time-Based One-Time Password (TOTP) and HMAC-Based One-Time Password (HOTP) library for Go.

🏷️ Authentication and OAuth
📂 Libraries for implementing authentication schemes.
67 stars
View on GitHub 🔗

Detailed Description of otpgo

otpgo

HMAC-Based and Time-Based One-Time Password (HOTP and TOTP) library for Go. Implements RFC 4226 and RFC 6238.

Mentioned in Awesome Go License Go Report Card Test Status Coverage Status PkgGoDev Latest Release

Contents

Supported Operations

  • Generate HOTP and TOTP codes.
  • Verify HOTP an TOTP codes.
  • Export OTP config as a Google Authenticator URI.
  • Export OTP config as a QR code image (used to register secrets in authenticator apps).
  • Export OTP config as a JSON.

Reading Material

Usage

Generating Codes

The simplest way to generate codes is to create the HOTP/TOTP struct and call Generate()

// 
// HMAC-Based
//

// Will use all default values, counter starts in 0
h := otpgo.HOTP{}
token, _ := h.Generate()

// Increment counter and generate next code
h.Counter++
token2, _ := h.Generate()

//
// Time-Based
//

// Will use all default values
t := otpgo.TOTP{}
token, _ := t.Generate()

Each type allows customization. For HMAC-Based tokens you can specify:

  • Key: Secret string, base32 encoded
  • Counter: Unsigned int
  • Leeway: Unsigned int
  • Algorithm: One of HmacSHA1, HmacSHA256 or HmacSHA512
  • Length: Length1 up to Length8

For Time-Based tokens you can specify:

  • Key: Secret string, base32 encoded
  • Period: Integer, period length in seconds
  • Delay: Integer, acceptable number of steps for validation
  • Algorithm: One of HmacSHA1, HmacSHA256 or HmacSHA512
  • Length: Length1 up to Length8

Verifying Codes

Once you receive a token from the user you can verify it by specifying the expected parameters and calling Validate(token string).

// 
// HMAC-Based
//
h := otpgo.HOTP{
    Key: "my-secret-key",
    Counter: 123, // The expected counter
}
ok, _ := h.Validate("the-token")

//
// Time-Based
//
t := otpgo.TOTP{
    Key: "my-secret-key",
}
ok, _ = t.Validate("the-token")

When calling HOTP.Validate() note that the internal counter will be increased if validation is successful, so that the next valid token will correspond to the increased counter.

Both HOTP and TOTP will accept tokens that match the exact Counter/Timestamp or a token within the specified Leeway/Delay.

Registering With Authenticator Apps

Most authenticator apps will give the user 2 options to register a new account: scan a QR code which contains all config and secrets for the OTP generation, or manually enter the secret key and additional info (such as username and issuer). The former being the preferred way because of the ease of use and the avoidance of human error.

QR Code

To generate the QR code just get the KeyUri and call the QRCode method:

otp := otpgo.TOTP{}
base64EncodedQRImage, _ := otp.
   KeyUri("[email protected]", "A Company").
   QRCode()

// Then use base64EncodedQRImage however you like
// e.g.: send it to the client to display as an image

Manual registration

Manual registration usually requires the user to type in the OTP config parameters by hand. The KeyUri type can be easily JSON encoded to then send the params to an external caller or any other place.

otp := otpgo.TOTP{
    Key: "YOUR_KEY",
    Period: 30,
    Delay: 1,
    Algorithm: config.HmacSHA1,
    Length: 6
}
ku := otp.KeyUri("[email protected]", "A Company")
jsonKeyUri, _ := json.Marshal(ku)

// Then use jsonKeyUri however you like
// e.g.: send it to the client for further processing

Defaults

If caller doesn't provide a custom configuration when generating OTPs. The library will ensure the following default values (any empty value will be filled).

HOTP Parameters

ParameterDefault Value
Leeway1 counter down & up
Hash / AlgorithmSHA1
Length6
Key64 random bytes base32 encoded

TOTP Parameters

ParameterDefault Value
Period30 seconds
Delay1 period under & over
Hash / AlgorithmSHA1
Length6
Key64 random bytes base32 encoded