totp

README

go-totp

Package go-totp library implements functionalities to create and validate Time-Based One-Time Password (TOTP) for Two-Factor Authentication (2FA) applications.

TOTP generates temporary codes based on a shared secret key, enhancing security.

Installation

Use go get

go get -u github.com/FuLygon/go-totp/v2

Import package

import "github.com/FuLygon/go-totp/v2"

Documentation

Example

See Example

Usage

Create TOTP

Generate or define a TOTP instance

t, err := totp.New(totp.TOTP{
    AccountName: "your_account_name",
    Issuer:      "your_issuer_name",
})
if err != nil {
    // handle error
    log.Println("error generating QR code:", err)
    return
}

// optionally, define TOTP details:
t := totp.TOTP{
    AccountName: "your_account_name",
    Issuer:      "your_issuer_name",
    Algorithm:   totp.AlgorithmSHA1,
    Digits:      6,
    Period:      30,
    Secret:      "your_shared_secret",
}

Generate TOTP URL and QR code

// generate TOTP URL
url, err := t.GetURL()
if err != nil {
    // handle error
    log.Println("error generating TOTP URL:", err)
    return
}
fmt.Println("TOTP URL:", url)

// generate QR code
qr, err := t.GetQR(256)
if err != nil {
    // handle error
    log.Println("error generating QR code:", err)
    return
}
fmt.Println("QR Code Base64:", qr.Base64)

Validating TOTP code

Create a validator instance

v := totp.Validator{
  Algorithm: totp.AlgorithmSHA1,
  Digits:    6,
  Period:    30,
  Secret:    "your_shared_secret",
}

Validate TOTP code

code := "123456" // user-provided TOTP code

valid, err := v.Validate(code)
if err != nil {
    // handle error
    log.Println("error validating TOTP code:", err)
    return
}

if valid {
    fmt.Println("TOTP code is valid!")
} else {
    fmt.Println("TOTP code is invalid.")
}

Documentation

Index

• Variables
• type Algorithm
• type QR
• type TOTP
  • func New(options TOTP) (totp TOTP, err error)
  • func (t TOTP) GetQR(size int, qrRecoveryLevel ...qrcode.RecoveryLevel) (QR, error)
  • func (t TOTP) GetURL() (string, error)
• type Validator
  • func (v Validator) Validate(code string) (bool, error)
  • func (v Validator) ValidateWithTimestamp(code string, timestamp int64) (bool, error)

Variables

var (
	// ErrEmptyIssuer value for issuer is required
	ErrEmptyIssuer = errors.New("issuer cannot be empty")
	// ErrEmptyAccountName value for account name is required
	ErrEmptyAccountName = errors.New("account name cannot be empty")
	// ErrInvalidAlgorithm invalid or unsupported algorithm
	ErrInvalidAlgorithm = errors.New("invalid or unsupported algorithm")
	// ErrInvalidDigits invalid or unsupported digits, supported values are from 1 to 10
	ErrInvalidDigits = errors.New("invalid or unsupported digits")
	// ErrInvalidPeriod invalid period value
	ErrInvalidPeriod = errors.New("period cannot be empty")
	// ErrInvalidSecret invalid secret value
	ErrInvalidSecret = errors.New("secret is not a valid base32")
)

Types

type Algorithm

type Algorithm string

Algorithm represents hashing functions for generating OTP

const (
	AlgorithmSHA1   Algorithm = "SHA1"
	AlgorithmSHA256 Algorithm = "SHA256"
	AlgorithmSHA512 Algorithm = "SHA512"
)

type QR

type QR struct {
	// Base64 encoded string of the QR code.
	Base64 string
	// Decoded image data of the QR code.
	Image image.Image
}

QR represents a QR code.

type TOTP

type TOTP struct {
	// Name of the account associated with the TOTP. Required.
	AccountName string
	// Issuer or the service provider of the TOTP. Required.
	Issuer string
	// Hashing function of the TOTP. Default value is AlgorithmSHA1.
	// The commonly supported value by most authenticator app is AlgorithmSHA1, other hash functions might get ignored or unsupported by some authenticator app.
	Algorithm Algorithm
	// Number of digits of the TOTP. Default value is 6.
	// Valid values are from 1 to 10.
	// The commonly supported values by most authenticator app are 6 and 8, other value might get ignored or unsupported by some authenticator app.
	Digits uint8
	// Time period (seconds) of the TOTP. Default value is 30.
	// The commonly supported values my some authenticator app are 30 and 60, other value might get ignored or unsupported by most authenticator app.
	Period uint64
	// Base32 encoded shared secret key of the TOTP.
	Secret string
}

TOTP represents parameters of a Time-based One-Time Password.

func New

func New(options TOTP) (totp TOTP, err error)

New creates a new TOTP with a randomly generated shared secret, default value will be used if null.

func (TOTP) GetQR

func (t TOTP) GetQR(size int, qrRecoveryLevel ...qrcode.RecoveryLevel) (QR, error)

GetQR generates a QR code image for the TOTP with optional recovery level. Default value for recovery level is qrcode.Medium.

See https://pkg.go.dev/github.com/skip2/go-qrcode@v0.0.0-20200617195104-da1b6568686e#RecoveryLevel for additional details on QR code recovery level.

func (TOTP) GetURL

func (t TOTP) GetURL() (string, error)

GetURL generates a TOTP URL string following the TOTP standard format.

type Validator

type Validator struct {
	// Hashing function of the TOTP.
	Algorithm Algorithm
	// Number of digits of the TOTP.
	Digits uint8
	// Skew defines the number of periods before and after the current period that are considered valid.
	// This is used to account for slight differences in time between the client and the server.
	Skew uint
	// Time period (seconds) of the TOTP
	Period uint64
	// Base32 encoded shared secret key of the TOTP.
	Secret string
}

Validator defines the structure used for TOTP validation

func (Validator) Validate

func (v Validator) Validate(code string) (bool, error)

Validate validates the provided TOTP code against the current timestamp

func (Validator) ValidateWithTimestamp

func (v Validator) ValidateWithTimestamp(code string, timestamp int64) (bool, error)

ValidateWithTimestamp validates the provided TOTP code against a specific timestamp