otpgo
HMAC-Based and Time-Based One-Time Password (HOTP and TOTP) library for Go. Implements RFC 4226 and RFC 6238.
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
- 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,HmacSHA256orHmacSHA512 - Length:
Length1up toLength8
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,HmacSHA256orHmacSHA512 - Length:
Length1up toLength8
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
| 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 |
