README.md

otpgo

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

Contents

• Supported Operations
• Reading Material
• Usage
  • Generating Codes
  • Verifying Codes
  • Registering with Authenticator App
    • QR Code
    • Manual Registration
• Defaults
  • HOTP Parameters
  • TOTP Parameters

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

• HOTP: An HMAC-Based One-Time Password Algorithm
• TOTP: Time-Based One-Time Password Algorithm
• Google Authenticator Key URI Format
• Browser Authenticator Demo

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("john.doe@example.org", "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("john.doe@example.org", "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

Parameter	Default Value
Leeway	1 counter down & up
Hash / Algorithm	SHA1
Length	6
Key	64 random bytes base32 encoded

TOTP Parameters

Parameter	Default Value
Period	30 seconds
Delay	1 period under & over
Hash / Algorithm	SHA1
Length	6
Key	64 random bytes base32 encoded