otp

README

OTP: One-Time Password

Time-based one-time password

Referenced the following packages:

• pyotp
• otp
• Key-Uri-Format

Formula

OTP(K, C) = Truncate(HMAC-SHA-1(K, C))

HMAC supports the following algorithms:

• SHA1 (Default)
• SHA256
• SHA512
• MD5

Why

kit4go/otp is a Go library for generating and verifying one-time passwords. It can be used to implement two-factor (2FA) or multi-factor (MFA) authentication methods in web applications and in other systems that require users to log in.

It enables you to easily add TOTPs to your own application, increasing your user's security against mass-password breaches and malware.

Features

• Generating QR Code images for easy user enrollment.
• Time-based One-time Password Algorithm (TOTP) (RFC 6238): Time based OTP, the most commonly used method.
• HMAC-based One-time Password Algorithm (HOTP) (RFC 4226): Counter based OTP, which TOTP is based upon.
• Generation and Validation of codes for either algorithm.

Shall Know

• OTPs involve a shared secret, stored both on the device(client) and the server
• OTPs can be generated on a device without internet connectivity
• OTPs should always be used as a second factor of authentication (if your device is lost, you account is still secured with a password)
• Microsoft Authenticator, Google Authenticator and other OTP client apps allow you to store multiple OTP secrets and provision those using a QR Code

Usage

• secret key
  • RandomSecret(length int) string generates a random secret, b32NoPadding.
  • VerifySecret(secret string) bool verifies the secret is base32.
• otp url
  • GenerateURLHOTP(opts KeyOpts) string generates the hotp url
  • GenerateURLTOTP(opts KeyOpts) string generates the totp url
• code totp most commonly used
  • Code(secret string) string generates the totp code
  • CodeCustom(secret string, t time.Time) string generates the totp code with time
  • TOTPCode(secret string) (code string) generates the totp code
  • TOTPCodeCustom(secret string, t time.Time, opts *Opts) string generates the totp code with time and opts
  • VerifyTOTP(passcode string, secret string) bool verifies the code of totp
  • VerifyTOTPCustom(passcode string, secret string, t time.Time, opts *Opts) bool verifies the code of totp with opts
• code hotp
  • HOTPCode(secret string, counter uint64) string generates the hotp code
  • HOTPCodeCustom(secret string, counter uint64, opts *Opts) string generates the hotp code with the opts
  • VerifyHOTP(passcode string, counter uint64, secret string) bool verifies the code of hotp
  • VerifyHOTPCustom(passcode string, counter uint64, secret string, opts *Opts) bool verifies the code of hotp with opts

Documentation

Index

• Constants
• func Code(secret string) string
• func CodeCustom(secret string, t time.Time) string
• func GenerateURLHOTP(opts KeyOpts) (url string)
• func GenerateURLTOTP(opts KeyOpts) (url string)
• func HOTPCode(secret string, counter uint64) (code string)
• func HOTPCodeCustom(secret string, counter uint64, opts *Opts) (code string)
• func KeyFromHOTPOpts(opts KeyOpts) (*xtp.Key, error)
• func KeyFromTOTPOpts(opts KeyOpts) (*xtp.Key, error)
• func KeyFromURL(url string) (*xtp.Key, error)
• func RandomSecret(length int) (secret string)
• func TOTPCode(secret string) (code string)
• func TOTPCodeCustom(secret string, t time.Time, opts *Opts) (code string)
• func VerifyHOTP(passcode string, counter uint64, secret string) bool
• func VerifyHOTPCustom(passcode string, counter uint64, secret string, opts *Opts) (ret bool)
• func VerifySecret(secret string) bool
• func VerifyTOTP(passcode string, secret string) bool
• func VerifyTOTPCustom(passcode string, secret string, t time.Time, opts *Opts) (ret bool)
• type KeyOpts
• type Opts
  • func (opts *Opts) GetAlgorithm() xtp.Algorithm
  • func (opts *Opts) GetDigits() xtp.Digits
  • func (opts *Opts) GetPeriod() uint
  • func (opts *Opts) GetSkew() uint

Constants

const (
	// AlgorithmSHA1 should be used for compatibility with Google Authenticator.
	//
	// See https://github.com/pquerna/otp/issues/55 for additional details.
	AlgorithmSHA1   = xtp.AlgorithmSHA1
	AlgorithmSHA256 = xtp.AlgorithmSHA256
	AlgorithmSHA512 = xtp.AlgorithmSHA512
	AlgorithmMD5    = xtp.AlgorithmMD5
)

Functions

func Code

func Code(secret string) string

Code generates the totp code, with the default settings: digits=6, algorithm=SHA1, base now timestamp.

func CodeCustom

func CodeCustom(secret string, t time.Time) string

CodeCustom generates the totp code, with the default settings: digits=6, algorithm=SHA1, with your specified timestamp.

func GenerateURLHOTP

func GenerateURLHOTP(opts KeyOpts) (url string)

GenerateURLHOTP returns the HOTP URL as a string.

func GenerateURLTOTP

func GenerateURLTOTP(opts KeyOpts) (url string)

GenerateURLTOTP returns the TOTP URL as a string.

func HOTPCode

func HOTPCode(secret string, counter uint64) (code string)

func HOTPCodeCustom

func HOTPCodeCustom(secret string, counter uint64, opts *Opts) (code string)

func KeyFromHOTPOpts

func KeyFromHOTPOpts(opts KeyOpts) (*xtp.Key, error)

KeyFromHOTPOpts creates a new HOTP Key.

func KeyFromTOTPOpts

func KeyFromTOTPOpts(opts KeyOpts) (*xtp.Key, error)

KeyFromTOTPOpts creates a new TOTP Key.

func KeyFromURL

func KeyFromURL(url string) (*xtp.Key, error)

KeyFromURL creates a new Key from an TOTP or HOTP url.

The URL format is documented here:

https://github.com/google/google-authenticator/wiki/Key-Uri-Format

func RandomSecret

func RandomSecret(length int) (secret string)

RandomSecret generates a random secret of given length (number of bytes) without padding, if rand.Read failed returns empty string.

func TOTPCode

func TOTPCode(secret string) (code string)

func TOTPCodeCustom

func TOTPCodeCustom(secret string, t time.Time, opts *Opts) (code string)

func VerifyHOTP

func VerifyHOTP(passcode string, counter uint64, secret string) bool

func VerifyHOTPCustom

func VerifyHOTPCustom(passcode string, counter uint64, secret string, opts *Opts) (ret bool)

func VerifySecret

func VerifySecret(secret string) bool

VerifySecret verifies the secret is valid, support padding or NoPadding format.

func VerifyTOTP

func VerifyTOTP(passcode string, secret string) bool

func VerifyTOTPCustom

func VerifyTOTPCustom(passcode string, secret string, t time.Time, opts *Opts) (ret bool)

Types

type KeyOpts

type KeyOpts struct {
	// Name of the issuing Organization/Company.
	Issuer string
	// Name of the User's Account (eg, email address)
	AccountName string
	// Number of seconds a TOTP hash is valid for. Defaults to 30 seconds.
	Period uint
	// Size in size of the generated Secret. Defaults to 20 bytes.
	SecretSize uint
	// Secret to store. Defaults to a randomly generated secret of SecretSize.  You should generally leave this empty.
	Secret []byte
	// Digits to request. Defaults to 6.
	Digits xtp.Digits
	// Algorithm to use for HMAC. Defaults to SHA1.
	Algorithm xtp.Algorithm
	// Reader to use for generating TOTP Key.
	Rand io.Reader
	// Counter for HOTP. if type is hotp: The counter parameter is required when provisioning a key for use with HOTP. It will set the initial counter value.
	Counter uint64
}

KeyOpts provides options for Generate(). The default values are compatible with Google-Authenticator.

Required: Issuer, AccountName, htop also need counter.

type Opts

type Opts struct {
	// Number of seconds a TOTP hash is valid for. Defaults to 30 seconds.
	Period uint
	// Periods before or after the current time to allow.  Value of 1 allows up to Period
	// of either side of the specified time.  Defaults to 0 allowed skews.  Values greater
	// than 1 are likely sketchy.
	Skew uint
	// Digits as part of the input. Defaults to 6.
	Digits xtp.Digits
	// Algorithm to use for HMAC. Defaults to SHA1.
	Algorithm xtp.Algorithm
}

Opts provides options for ValidateCustom().

Only for TOTP: Period, Skew.

func (*Opts) GetAlgorithm

func (opts *Opts) GetAlgorithm() xtp.Algorithm

func (*Opts) GetDigits

func (opts *Opts) GetDigits() xtp.Digits

func (*Opts) GetPeriod

func (opts *Opts) GetPeriod() uint

func (*Opts) GetSkew

func (opts *Opts) GetSkew() uint