onetimepasscode

README

One Time Passcodes for Golang

This package provides an implementation of the following IETF RFCs, providing hash based and time based one time passwords, plus a utility to generate crypographically secure secrets.

RFC4226 - HOTP: An HMAC-Based One-Time Password Algorithm

RFC6238 - TOTP: Time-Based One-Time Password Algorithm

Licensed under Apache License, v2.0

Documentation

Overview

Package onetimepasscode provides an implementation of the following IETF RFCs, providing hash based and time based one time passcodes (OTP).

RFC4226 - HOTP: An HMAC-Based One-Time Password Algorithm RFC6238 - TOTP: Time-Based One-Time Password Algorithm

Licensed under Apache License, v2.0

Index

• func GenerateHOTP(secret []byte, movingFactor int, codeDigits int, addChecksum bool, ...) string
• func GenerateRandomBytes(byteLen int) ([]byte, error)
• func GenerateSecureSecret() ([]byte, error)
• func GenerateTOTP(secret []byte, timeStep int, codeDigits int, addChecksum bool, ...) string
• func VerifyOTP(clientOTP, serverOTP []byte) bool

Examples

• GenerateHOTP
• GenerateTOTP

Functions

func GenerateHOTP

func GenerateHOTP(secret []byte, movingFactor int, codeDigits int, addChecksum bool, truncationOffset int) string

GenerateHOTP returns an hash-based one time passcode. This function requires that the moving factor that calculates the OTP can be calculated by both the client and the server. Alternatively, GenerateTOTP uses RFC6238 to generate OTP codes based on unix times, and is recommended is most circumstances.

The shared secret is a value that is pre-shared between the client and the server, and must be kept secret. This value must also be unique for each client. The moving factor is a value that changes frequently, but not necessarily for each authentication request. This must be a random value that both the client and server know how to calculate. The code digits is the length of the OTP to be created. The add checksum flag determines whether a checksum digit is to be appended to the OTP. The truncation offset controls the offset into the MAC that truncation will begin at. If this value is out of the range of 0 ... 15, then dynamic truncation will be used. Dynamic truncation is when the last 4 bits of the last byte of the MAC are used to determine the start offset.

Example

// Each user needs to have a preshared secret value.
// This value must be unique per user, and kept secure.
secret := []byte("12345678901234567890")

// movingFactor is a value that 'moves', that is, it
// is a value that both the client and the server are
// able to derive for a specific request.
movingFactor := 123

// Generate a hash-based one time password
hotpCode := GenerateHOTP(
	secret,
	movingFactor,
	// Generates a 6 digit OTP
	6,
	// Will not add a checksum digit to the end
	false,
	// Sets the truncation offset to 0
	0,
)

fmt.Println(hotpCode)

Output:

108787

func GenerateRandomBytes

func GenerateRandomBytes(byteLen int) ([]byte, error)

GenerateRandomBytes generates a secure random array of byteLen bytes.

func GenerateSecureSecret

func GenerateSecureSecret() ([]byte, error)

GenerateSecureSecret generates a secure random seed of recommended byte length.

The length of the shared secret MUST be at least 128 bits. RFC4226 RECOMMENDs a shared secret length of 160 bits.

func GenerateTOTP

func GenerateTOTP(secret []byte, timeStep int, codeDigits int, addChecksum bool, truncationOffset int) string

GenerateTOTP generates an time based OTP value for the given set of parameters. The OTP is generated using the RFC4226 HOTP implementation as a basis for OTP generation.

The shared secret is a value that is pre-shared between the client and the server, and must be kept secret. This value must also be unique for each client. The time step that each TOTP value is valid for. This value is derived from the current unix time. For example, a time step of 30 indicates each TOTP value is valid for a period of 30 seconds. The code digits is the length of the OTP to be created. The add checksum flag determines whether a checksum digit is to be appended to the OTP. The truncation offset controls the offset into the MAC that truncation will begin at. If this value is out of the range of 0 ... 15, then dynamic truncation will be used. Dynamic truncation is when the last 4 bits of the last byte of the MAC are used to determine the start offset.

Example

// Each user needs to have a preshared secret value.
// This value must be unique per user, and kept secure.
secret := []byte("12345678901234567890")

// timestep is the number of seconds that the TOTP value
// is valid for. This value is used to generate the hash
// in conjunction with the current unix time. An example
// of 30 means that every 30 seconds has a unique TOTP
// value. As time progresses, new TOTP values will be
// generated.
timeStep := 30

// Generate a hash-based one time password
hotpCode := GenerateHOTP(
	secret,
	timeStep,
	// Generates a 6 digit OTP
	6,
	// Will not add a checksum digit to the end
	false,
	// Sets the truncation offset to 0
	0,
)

// Some TOTP code dependent on the time the
// function is invoked.

fmt.Println(hotpCode)

Output:

243384

func VerifyOTP

func VerifyOTP(clientOTP, serverOTP []byte) bool

VerifyOTP tests to ensure the two OTP match in a cryptographically safe fashion. It returns true if the OTP match, otherwise false.