otp

README

otp

Overview

This package provides a Google Authenticator compatible One Time Pad (otp) implementation.

Automated documentation for this Go package is available from .

While the otp package has no dependencies beyond the standard Go packages, we include an example binary, example/main.go, that serves as a demonstration of using the package and includes the generation of a QR code for enrolling a sample OTP config to the Google Authenticator application. This generation uses the github.com/skip2/go-qrcode package.

To try this example:

$ git clone https://github.com/tinkerator/otp.git
$ cd otp
$ go mod tidy
$ go build example/main.go
$ ./main

This will start a webserver listening to localhost:8080. The program generates a random new OTP secret each time it is invoked, and there is no lasting value to the generated key. But the compatibility with Google Authenticator can be validated using it. An example output looks like this:

The webserver:

• shows an enrollment QR code for the stated secret. In a real application, you would not normally show the 16 character base32 encoded secret like this. However, this secret or a copy of the QR code can be used to backup your OTP setup. The QR code and the secret will remain constant until you restart the main program. That is, the QR code doesn't change if you refresh the page.

• shows three OTP codes one for each of the 30 seconds prior to, including, and just after the current time. If you refresh the page, these three codes may change if sufficient time has passed. If you import the QR code into Google Authenticator, you will see the OTP code for "myOTP: nobody@localhost" match one of these three codes. Which code depends on the time skew between your computer at the time you rendered the page and the time on your phone. If it takes a while to set things up, you may need to refresh the page to view a recent enough code.

• given the way this OTP mechanism works, you can set up the same configuration on multiple phones and they will all generate the same OTP code sequences at the same times.

• the --uri command line flag for this example program inlines the QR code using a data:image/png;base64,... URI for the image data. Without that flag, the image is generated as a separately loaded qr.png fetch.

License info

The otp package is distributed with the same BSD 3-clause license as that used by golang itself.

Reporting bugs and feature requests

Use the github otp bug tracker.

Documentation

Overview

Package otp support generation of and validation of time synchronized one-time-pad codes. The conventions used by this package are the default ones used by the Google Authenticator application.

Index

• Variables
• type KnownIDs
  • func NewKnownIDs(issuer string) *KnownIDs
  • func (ki *KnownIDs) AddKey(id, key string) error
  • func (ki *KnownIDs) Code(id string, offset int64) (int, error)
  • func (ki *KnownIDs) GenKey(id string) error
  • func (ki *KnownIDs) TimeURI(id string) (string, error)
  • func (ki *KnownIDs) ValidateTimeCode(id string, code int, adjust uint) bool

Variables

var ErrInvalid = errors.New("invalid structure")

ErrInvalid indicates the id requested is unknown.

var ErrUnknown = errors.New("id unknown")

ErrUnknown indicates the id requested is unknown.

Types

type KnownIDs

type KnownIDs struct {

	// Issuer holds the OTP issuer name string.
	Issuer string

	// Map holds OTP secret information indexed by user ID.
	Map map[string]string
	// contains filtered or unexported fields
}

KnownIDs holds access key material for a set of known IDs.

func NewKnownIDs

func NewKnownIDs(issuer string) *KnownIDs

NewKnownIDs returns a structure holding an issuer's list of secrets indexed by IDs.

func (*KnownIDs) AddKey

func (ki *KnownIDs) AddKey(id, key string) error

AddKey adds a (replacement) issuer key for the specified id. The 80 bits of key material must be provided in valid base32 encoding.

func (*KnownIDs) Code

func (ki *KnownIDs) Code(id string, offset int64) (int, error)

Code generates a one time pad code for a given integer offset.

func (*KnownIDs) GenKey

func (ki *KnownIDs) GenKey(id string) error

GenKey generates a random (replacement) issuer key for the specified id.

func (*KnownIDs) TimeURI

func (ki *KnownIDs) TimeURI(id string) (string, error)

TimeURI returns a universal resource identifier for TOTP setup. Converting the returned string into a QR code, for example, will allow Google Authenticator to import the TOTP keys.

func (*KnownIDs) ValidateTimeCode

func (ki *KnownIDs) ValidateTimeCode(id string, code int, adjust uint) bool

ValidateTimeCode validates a numerical code as satisfying the TOTP criteria. If adjust is non-zero then that many time value indices adjacent to the current time are also checked and any of them are considered valid. No attempts are made to protect against a replay attack.