tfa

Documentation

Overview

Package tfa (two-factor authentication) provides a simple, clean, and idiomatic way for generating and verifying one-time passwords for both HOTP and TOTP defined in RFC 4226 and 6238.

Index

• Constants
• Variables
• func GenerateOTP(otp OTP) (string, error)
• func GenerateSecret(size uint) (string, error)
• func NewOTP(cfg *OTPConfig) (*Key, OTP, error)
• func NewOTPFromKey(raw string) (*Key, OTP, error)
• type Digits
  • func (d Digits) String() string
• type HashAlgorithm
  • func (h HashAlgorithm) Hasher() func() hash.Hash
  • func (h HashAlgorithm) String() string
• type Key
  • func (k *Key) AccountName() string
  • func (k *Key) Algorithm() HashAlgorithm
  • func (k *Key) Counter() uint64
  • func (k *Key) Digits() Digits
  • func (k *Key) Issuer() string
  • func (k *Key) IssuerLabelPrefix() string
  • func (k *Key) Label() string
  • func (k *Key) Period() uint64
  • func (k *Key) Secret() string
  • func (k *Key) SetCounter(count uint64)
  • func (k *Key) Type() OTPType
• type OTP
• type OTPConfig
• type OTPType

Examples

• NewOTP
• NewOTP (Second)
• NewOTP (Third)
• NewOTPFromKey

Constants

const (
	// SHA1 represents the SHA1 algorithm name.
	SHA1 = HashAlgorithm("SHA1")
	// SHA256 represents the SHA256 algorithm name.
	SHA256 = HashAlgorithm("SHA256")
	// SHA512 represents the SHA512 algorithm name.
	SHA512 = HashAlgorithm("SHA512")
)

const (
	// TOTP represents totp, defined in RFC 6238
	TOTP = OTPType("totp")
	// HOTP represents hotp, defined in RFC 4266
	HOTP = OTPType("hotp")
)

Variables

var (
	// ErrWeakSecretSize is returned by GenerateSecret,
	// when input secret size does not meet RFC 4226 requirements.
	ErrWeakSecretSize = errors.New("Weak secret size, The shared secret MUST be at least 128 bits")

	// ErrInvalidOTPTypeE is returned by NewOTP when OTP type not equal TOTP or HOTP
	ErrInvalidOTPTypeE = errors.New("Invalid OTP type")

	// ErrMissingLabel is returned by NewOTP when label missing
	ErrMissingLabel = errors.New("Missing Label")
)

Functions

func GenerateOTP

func GenerateOTP(otp OTP) (string, error)

GenerateOTP return one time password or an error if occurs The function compliant with RFC 4226, and implemented as mentioned in section 5.3 See https://tools.ietf.org/html/rfc4226#section-5.3

func GenerateSecret

func GenerateSecret(size uint) (string, error)

GenerateSecret return base32 random generated secret. Size must be in bytes length, if size does not meet RFC 4226 requirements ErrWeakSecretSize returned.

func NewOTP

func NewOTP(cfg *OTPConfig) (*Key, OTP, error)

NewOTP return OTP instance and it's relevant Key or error if occurs.

Example

cfg := &OTPConfig{
	OTPType:    TOTP,
	Label:      "Test",
	SecretSize: 20,
}
_, otp, _ := NewOTP(cfg)
ok, err := otp.Verify("123456")
fmt.Println(ok, err)

Output:

false <nil>

Example (Second)

cfg := &OTPConfig{
	OTPType:    HOTP,
	Label:      "Test",
	Secret:     "GXNRHI2MFRFWXQGJHWZJFOSYI6E7MEVA",
	SecretSize: 20,
}
_, otp, _ := NewOTP(cfg)
ok, err := otp.Verify("345515") // counter 0
fmt.Println(ok, err)
ok, err = otp.Verify("422283") // counter 1
fmt.Println(ok, err)

Output:

true <nil>
true <nil>

Example (Third)

cfg := &OTPConfig{
	OTPType:       HOTP,
	MaxAttempts:   1,
	Label:         "Test",
	Secret:        "GXNRHI2MFRFWXQGJHWZJFOSYI6E7MEVA",
	LockOutDelay:  1,
	EnableLockout: true,
	SecretSize:    20,
}
_, otp, _ := NewOTP(cfg)
ok, err := otp.Verify("1234567") // counter 0
fmt.Println(ok, err)
time.Sleep(time.Second)
ok, err = otp.Verify("12345678") // counter 1
fmt.Println(ok, err)

Output:

false <nil>
false Max attempts reached, Account locked out

func NewOTPFromKey

func NewOTPFromKey(raw string) (*Key, OTP, error)

NewOTPFromKey parse raw key string and return OTP instance and it's relevant Key or error if occurs.

Example

key, otp, _ := NewOTPFromKey("otpauth://hotp/TEST?secret=GXNRHI2MFRFWXQGJHWZJFOSYI6E7MEVA")
ok, err := otp.Verify("345515") // counter 0
fmt.Println(ok, err)
fmt.Println(key.Digits())
fmt.Println(key.Type())
fmt.Println(key.Secret())
fmt.Println(key.Label())

Output:

true <nil>
6
hotp
GXNRHI2MFRFWXQGJHWZJFOSYI6E7MEVA
TEST

Types

type Digits

type Digits int

Digits represents the length of OTP.

const (
	// SixDigits of OTP.
	SixDigits Digits = 6
	// EightDigits of OTP
	EightDigits Digits = 8
)

func (Digits) String

func (d Digits) String() string

String describe Digits as a string

type HashAlgorithm

type HashAlgorithm string

HashAlgorithm represents the hashing function to use in the HMAC

func (HashAlgorithm) Hasher

func (h HashAlgorithm) Hasher() func() hash.Hash

Hasher returns a function create new hash.Hash.

func (HashAlgorithm) String

func (h HashAlgorithm) String() string

String describe HashAlgorithm as string

type Key

type Key struct{ *url.URL }

Key represnt Uri Format for OTP See https://github.com/google/google-authenticator/wiki/Key-Uri-Format

func (*Key) AccountName

func (k *Key) AccountName() string

AccountName returns the name of the user's account.

func (*Key) Algorithm

func (k *Key) Algorithm() HashAlgorithm

Algorithm return the hashing Algorithm name

func (*Key) Counter

func (k *Key) Counter() uint64

Counter return initial counter value. for provisioning a key for use with HOTP // if type not a hopt the returned value is 0

func (*Key) Digits

func (k *Key) Digits() Digits

Digits returns the length of pin code.

func (*Key) Issuer

func (k *Key) Issuer() string

Issuer returns a string value indicating the provider or service.

func (*Key) IssuerLabelPrefix

func (k *Key) IssuerLabelPrefix() string

IssuerLabelPrefix returns a string value indicating the provider or service extracted from label.

func (*Key) Label

func (k *Key) Label() string

Label returns the label for the Key.

func (*Key) Period

func (k *Key) Period() uint64

Period that a TOTP code will be valid for, in seconds. The default value is 30. if type not a topt the returned value is 0

func (*Key) Secret

func (k *Key) Secret() string

Secret returns the secret for the Key.

func (*Key) SetCounter

func (k *Key) SetCounter(count uint64)

SetCounter set counter value. if type not a hopt the set operation ignored.

func (*Key) Type

func (k *Key) Type() OTPType

Type returns the type for the Key (totp, hotp).

type OTP

type OTP interface {
	// Interval returns sequential value to be used in HMAC.
	// If targted OTP is HOTP returns counter value,
	// Otherwise, return time-step (current UTC time / period)
	Interval() uint64
	// Secret return OTP shared secret.
	Secret() string
	// Algorithm return OTP hashing algorithm.
	Algorithm() HashAlgorithm
	// Digits return OTP digits.
	Digits() Digits
	// Verify increments its interval and then calculates the next OTP value.
	// If the received value matches the calculated value then the OTP value is valid.
	// Verify follow validation of OTP values as described in RFC 6238 section 4.1 and
	// And RFC 4226 section 7.2.
	// To enable throttling at the server and stop brute force attacks,
	// The Verify method lunch lockout mechanism based on a predefined configuration.
	// The lockout mechanism implement a delay scheme and failed OTP counter,
	// Each time OTP verification failed the delay scheme increased by delay*failed, number of seconds,
	// And client must wait for the delay window, Otherwise, an error returned  verification process disabled.
	// Once the max attempts reached the verification process return error indicate account has been blocked.
	// Lockout mechanism disabled by default, See OTPConfig to learn more about lockout configuration.
	// Lockout follow Throttling at the Server as described in RFC 4226 section 7.3 .
	Verify(otp string) (bool, error)
	// SetMaxAttempts of verification failures to lock the account.
	SetMaxAttempts(max uint)
	// SetDealy window to periodically disable password verification process.
	SetDealy(dealy uint)
	// SetStartAt, set in what attempt number, lockout mechanism start to work.
	SetStartAt(num uint)
	// Failed return count of failed verification.
	Failed() uint
	// SetFailed, set count of failed verification.
	SetFailed(num uint)
	// DelayTime return time represents the end of the disabling password verification process.
	DelayTime() time.Time
	// SetDelayTime set time that represents the end of the disabling password verification process.
	SetDelayTime(t time.Time)
}

OTP represents one-time password algorithm for both HOTP and TOTP.

type OTPConfig

type OTPConfig struct {
	// OTPType targted OTP (TOTP, HOTP)
	OTPType OTPType
	// LockOutStartAt define in what attempt number, lockout mechanism start to work.
	// Default  0
	LockOutStartAt uint
	// EnableLockout enable or disable lockout mechanism
	EnableLockout bool
	// LockOutDelay define delay window to disable password verification process default 30
	// the formula is delay * failed Attempts as described in RFC 4226 section-7.3.
	LockOutDelay uint
	// MaxAttempts define max attempts of verification failures to lock the account default 3.
	MaxAttempts uint
	// Digits represents the length of OTP.
	Digits Digits
	// SecretSize represents the length of secret, default 20 bytes.
	SecretSize uint
	// Secret represents shared secret between client and server, if empty a new secret will be generated.
	Secret string
	// HashAlgorithm represents tha hash algorithm hmac use, default SHA1
	HashAlgorithm HashAlgorithm
	// Period represents time step in seconds used by TOTP, default 30 as descriped in  RFC 6238 section-4.1.
	Period uint64
	// Counter represents the incremental number used by HOTP.
	Counter uint64
	// Issuer represents  the provider or service.
	Issuer string
	// Label represents path in key uri
	Label string
}

OTPConfig represent configuration needed to create OTP instance.

type OTPType

type OTPType string

OTPType represent OTP type (TOTP, HOTP)