otp

README

otp

One time password for Go.

Features

• Simple API.
• Dependency-free.
• Clean and tested code.
• HOTP RFC 4226.
• TOTP RFC 6238.

See GUIDE.md for more details.

Install

Go version 1.17+

go get github.com/cristalhq/otp

Example

secretInBase32 := "JBSWY3DPEHPK3PXP"

algo := otp.AlgorithmSHA1
digits := otp.Digits(10)
issuer := "cristalhq"

hotp, err := otp.NewHOTP(algo, digits, issuer)
checkErr(err)

code, err := hotp.GenerateCode(42, secretInBase32)
checkErr(err)

fmt.Println(code)

err = hotp.Validate(code, 42, secretInBase32)
checkErr(err)

// Output:
// 0979090604

Also see examples: examples_test.go.

Documentation

See these docs.

License

MIT License.

Documentation

Index

• Variables
• type Algorithm
  • func (a Algorithm) Hash() hash.Hash
  • func (a Algorithm) String() string
• type HOTP
  • func NewHOTP(cfg HOTPConfig) (*HOTP, error)
  • func (h *HOTP) GenerateCode(counter uint64, secret string) (string, error)
  • func (h *HOTP) GenerateURL(account string, secret []byte) string
  • func (h *HOTP) Validate(passcode string, counter uint64, secret string) error
• type HOTPConfig
  • func (cfg HOTPConfig) Validate() error
• type Key
  • func ParseKeyFromURL(s string) (*Key, error)
  • func (k *Key) Account() string
  • func (k *Key) Issuer() string
  • func (k *Key) Period() uint64
  • func (k *Key) Secret() string
  • func (k *Key) String() string
  • func (k *Key) Type() string
• type TOTP
  • func NewTOTP(cfg TOTPConfig) (*TOTP, error)
  • func (t *TOTP) GenerateCode(secret string, at time.Time) (string, error)
  • func (t *TOTP) GenerateURL(account string, secret []byte) string
  • func (t *TOTP) Validate(passcode string, at time.Time, secret string) error
• type TOTPConfig
  • func (cfg TOTPConfig) Validate() error

Examples

• HOTP
• TOTP

Variables

var (
	ErrUnsupportedAlgorithm = errors.New("unsupported algorithm")
	ErrNoDigits             = errors.New("required digits not set")
	ErrEmptyIssuer          = errors.New("empty issuer")
	ErrPeriodNotValid       = errors.New("period is not valid")
	ErrSkewNotValid         = errors.New("skew is not valid")
	ErrCodeLengthMismatch   = errors.New("code length mismatch")
	ErrCodeIsNotValid       = errors.New("code is not valid")
	ErrEncodingNotValid     = errors.New("encoding is not valid")
)

Types

type Algorithm

type Algorithm uint

Algorithm represents the hashing function to use for OTP.

const (
	AlgorithmUnknown Algorithm = 0
	AlgorithmSHA1    Algorithm = 1
	AlgorithmSHA256  Algorithm = 2
	AlgorithmSHA512  Algorithm = 3
)

func (Algorithm) Hash

func (a Algorithm) Hash() hash.Hash

func (Algorithm) String

func (a Algorithm) String() string

type HOTP

type HOTP struct {
	// contains filtered or unexported fields
}

HOTP represents HOTP codes generator and validator.

Example

package main

import (
	"fmt"

	"github.com/cristalhq/otp"
)

func main() {
	hotp, err := otp.NewHOTP(otp.HOTPConfig{
		Algo:   otp.AlgorithmSHA1,
		Digits: 10,
		Issuer: "cristalhq",
	})
	checkErr(err)

	secretInBase32 := "JBSWY3DPEHPK3PXP"
	code, err := hotp.GenerateCode(42, secretInBase32)
	checkErr(err)

	fmt.Println(code)

	err = hotp.Validate(code, 42, secretInBase32)
	checkErr(err)

}

func checkErr(err error) {
	if err != nil {
		panic(err)
	}
}

Output:

0979090604

func NewHOTP

func NewHOTP(cfg HOTPConfig) (*HOTP, error)

NewHOTP creates new HOTP.

func (*HOTP) GenerateCode

func (h *HOTP) GenerateCode(counter uint64, secret string) (string, error)

GenerateCode for the given counter and secret.

func (*HOTP) GenerateURL

func (h *HOTP) GenerateURL(account string, secret []byte) string

GenerateURL for the account for a given secret.

func (*HOTP) Validate

func (h *HOTP) Validate(passcode string, counter uint64, secret string) error

Validate the given passcode, counter and secret.

type HOTPConfig

type HOTPConfig struct {
	Algo   Algorithm
	Digits uint
	Issuer string
}

func (HOTPConfig) Validate

func (cfg HOTPConfig) Validate() error

type Key

type Key struct {
	// contains filtered or unexported fields
}

Key represents an HTOP or TOTP key.

func ParseKeyFromURL

func ParseKeyFromURL(s string) (*Key, error)

ParseKeyFromURL creates a new Key from the HOTP or TOTP URL. See: https://github.com/google/google-authenticator/wiki/Key-Uri-Format

func (*Key) Account

func (k *Key) Account() string

Account returns the name of the user's account.

func (*Key) Issuer

func (k *Key) Issuer() string

Issuer returns the name of the issuing organization.

func (*Key) Period

func (k *Key) Period() uint64

Period returns a tiny int representing the rotation time in seconds.

func (*Key) Secret

func (k *Key) Secret() string

Secret returns the opaque secret for this Key.

func (*Key) String

func (k *Key) String() string

func (*Key) Type

func (k *Key) Type() string

Type returns "hotp" or "totp".

type TOTP

type TOTP struct {
	// contains filtered or unexported fields
}

TOTP represents TOTP codes generator and validator.

Example

package main

import (
	"fmt"
	"time"

	"github.com/cristalhq/otp"
)

func main() {
	totp, err := otp.NewTOTP(otp.TOTPConfig{
		Algo:   otp.AlgorithmSHA1,
		Digits: 10,
		Issuer: "cristalhq",
		Period: 30,
		Skew:   2,
	})
	checkErr(err)

	secretInBase32 := "JBSWY3DPEHPK3PXP"
	at := time.Date(2023, 11, 26, 12, 15, 18, 0, time.UTC)

	code, err := totp.GenerateCode(secretInBase32, at)
	checkErr(err)

	fmt.Println(code)

	err = totp.Validate(code, at, secretInBase32)
	checkErr(err)

}

func checkErr(err error) {
	if err != nil {
		panic(err)
	}
}

Output:

0462778229

func NewTOTP

func NewTOTP(cfg TOTPConfig) (*TOTP, error)

NewTOTP creates new TOTP.

func (*TOTP) GenerateCode

func (t *TOTP) GenerateCode(secret string, at time.Time) (string, error)

GenerateCode for the given counter and secret.

func (*TOTP) GenerateURL

func (t *TOTP) GenerateURL(account string, secret []byte) string

GenerateURL for the account for a given secret.

func (*TOTP) Validate

func (t *TOTP) Validate(passcode string, at time.Time, secret string) error

Validate the given passcode, time and secret.

type TOTPConfig

type TOTPConfig struct {
	Algo   Algorithm
	Digits uint
	Issuer string
	Period uint
	Skew   uint
}

func (TOTPConfig) Validate

func (cfg TOTPConfig) Validate() error