totp

README

TOTP

A time-based one-time password (TOTP) code generator written in Go. A command-line interface that's like Google Authenticator or Authy for your Windows, macOS, or Linux machine.

What it Does

It generates TOTP codes used for two-factor authentication at sites such as Google, GitHub, Dropbox, PayPal, Amazon, and many more.

Warning Every copy of your two-factor credentials increases your risk profile. Using this utility is no exception. This utility will store your TOTP secrets unencrypted on your filesystem. The only protection offered is to store these secrets in a file readable by only your user and protected by the operating system only.

Quick Start

Add TOTP secrets to the TOTP configuration file with the config add option, specifying the name and secret value. Note the secret names are case sensitive.

totp config add mysecretname NV4XGZLDOJSXICQ

Generate TOTP codes using the totp command to specify the secret name. Note that because totp reserves the use of the words config and version for commands, don't use them to name a secret. If you've generated and installed totp completions for for your shell, pressing tab on a partially completed secret name will trigger autocomplete.

totp mysecretname

List the secret entries with the config list command.

totp config list

Aliases are ls and l.

Update secret entries using the config update command. Note that config update and config add are actually the same command and can be used interchangeably.

totp config update mysecretname NV4XGZLDOJSXICQ

Rename the secret entries with the config rename command

totp config rename mysecretname mynewname

Aliases are ren and mv.

Delete secret entries with the config delete command

totp config delete mynewname

Aliases are remove, erase, rm, and del.

Remove all the secrets and start over using the config reset command

totp config reset

Use an ad-hoc secret to generate a code by using the --secret option

totp --secret NV4XGZLDOJSXICQ

Continuous code output can be generated with the --follow option.

totp --follow mysecretname

Use a QR Code to move an entry into your mobile device.

totp --qrcode mysecretname

will output a QR code suitable for scanning into a mobile device app such as Google Authenticator or Authy.

A one-off QR code can also be generated by providing both the name and the secret, for example:

totp --qrcode --secret NV4XGZLDOJSXICQ mysecretname

For help on any of the above, use the --help option. Examples are

totp --help
totp config --help

Shell completion can be enabled by using the completion command.

Bash

. <(totp completion bash)

Powershell

. totp completion powershell | Out-String | Invoke-Expression

TOTP Data Location

The location for saved data is extracted from the LOCALAPPDATA environment variable in Windows and the HOME environment for Linux/MacOS and in the file totp-config.json. This can be customized using the --file option or by setting the TOTP_CONFIG environment variable.

Using the Time Machine

totp implements the --time, --forward, and --backward options to manipulate the time for which the TOTP code is generated. This is useful if totp is being used on a machine with the incorrect time.

The --time option takes an RFC3339 formatted time string as its argument and uses it to generate the TOTP code. Note that the --forward and --backward options will internally modify this option value.

Examples with --time:

$ date '+%FT%T%:z'
2019-06-01T19:58:47-05:00
$ totp --time $(date '+%FT%T%:z') --secret NV4XGZLDOJSXICQ
931665
$ totp --time 2019-06-01T20:00:00-05:00 --secret NV4XGZLDOJSXICQ
526171

The --forward and --backward options move the current time forward and backward by their duration formatted arguments. See Go's time.ParseDuration() documentation for more details on this format.

Examples with --forward and --backward

$ totp --time 2019-06-01T20:00:00-05:00 --backward 3m --secret NV4XGZLDOJSXICQ
222296
$ totp --time 2019-06-01T20:00:00-05:00 --forward 30s --secret NV4XGZLDOJSXICQ
820148

The --follow option is also compatible with the time machine.

totp --time 2001-10-31T20:00:00-05:00 --follow --secret NV4XGZLDOJSXICQ
877737
208737

Using the Stdio Option

If storing secrets in the clear isn't ideal for you, totp supports streaming the shared secret collection through stdin and stdout with the --stdio option. This allows you to roll your own encryption or support other methods of maintaining shared secrets.

The totp <secret name> and totp config list commands support loading the collection via standard input. The totp config update, totp config delete, and totp config rename commands support loading via standard input and sending the modified collection to standard output. Experiment with the --stdio option to observe how this works.

Learning with Plaintext Data

Note the --file option can achieve the same results as this example. This is meant to teach how stdio works with totp.

Create a collection

totp config add --stdio secretname myvalue < /dev/null > totp.json

View the collection

totp config list --stdio < totp.json

Generate a TOTP code

totp secretname --stdio < totp.json

Encrypting Shared Secret Collection

Using what was learned above, a contrived example for encrypting data with GnuPG follows.

Create an encrypted collection

totp config add --stdio secretname myvalue < /dev/null | \
  gpg --batch --yes --passphrase mypassphrase --output totp-collection.gpg --symmetric

View the collection

gpg --quiet --batch --passphrase mypassphrase --decrypt totp-collection.gpg | \
  totp config list --stdio

Add another secret

gpg --quiet --batch --passphrase mypassphrase --decrypt totp-collection.gpg | \
  totp config add  --stdio newname newvalue | \
  gpg --batch --yes --passphrase mypassphrase --output totp-collection.gpg --symmetric

View the modified collection

gpg --quiet --batch --passphrase mypassphrase --decrypt totp-collection.gpg | \
  totp config list --stdio

Generate a TOTP code

gpg --quiet --batch --passphrase mypassphrase --decrypt totp-collection.gpg | totp --stdio secretname

Building

totp is mostly developed using Go 1.19.x on Debian based systems. Only go is required but to use the automated actions the Makefile provides, make must be installed.

To build everything:

git clone https://github.com/arcanericky/totp.git
cd totp
make

For unit tests and code coverage reports:

make test

The coverage is output to coverage.html. Load it in browser for review. For example:

/opt/google/chrome/chrome file://$PWD/coverage.html

To build for a single platform (see the Makefile for the different targets)

make linux-amd64

See the Makefile for how to use the go command natively.

Contributing

Contributions and issues are welcome. These include bugs reports and fixes, code comments, spelling corrections, and new features. If adding a new feature, please file an issue so it can be discussed prior to implementation so your time isn't wasted.

Unit tests for new code are required. Use make test to verify coverage. Coverage will also be checked with Codecov when pull requests are made.

Inspiration

My ga-cmd project is more popular than I expected. It's basically the same as totp with a much smaller executable, but the list of secrets must be edited manually and there aren't as many command line options. This totp project allows the user to maintain the secret collection through the totp command line interface, run on a variety of operating systems, and gives me a platform to practice my Go coding.

Credits

This utility uses the otp package by pquerna. Without this library, I probably wouldn't have bothered creating this front-end.

Documentation

Index

• Variables
• type Collection
  • func NewCollection() *Collection
  • func NewCollectionWithData(data []byte) (*Collection, error)
  • func NewCollectionWithFile(filename string) (c *Collection, err error)
  • func NewCollectionWithReader(reader io.Reader) (*Collection, error)
  • func (c *Collection) DeleteSecret(name string) (Secret, error)
  • func (c *Collection) Deserialize(data []byte) error
  • func (c *Collection) GenerateCode(name string) (string, error)
  • func (c *Collection) GenerateCodeWithTime(name string, time time.Time) (string, error)
  • func (c *Collection) GetSecret(name string) (Secret, error)
  • func (c *Collection) GetSecrets() []Secret
  • func (c *Collection) RenameSecret(oldName, newName string) (Secret, error)
  • func (c *Collection) Save() error
  • func (c *Collection) Serialize() ([]byte, error)
  • func (c *Collection) SetFilename(filename string) string
  • func (c *Collection) SetWriter(writer io.Writer)
  • func (c *Collection) UpdateSecret(name, value string) (Secret, error)
• type CollectionInterface
• type Secret

Variables

var ErrNoFilename = errors.New("no save target")

var ErrSecretNameEmpty = errors.New("secret name empty")

var ErrSecretNotFound = errors.New("secret not found")

var ErrSecretValueEmpty = errors.New("secret value empty")

Types

type Collection

type Collection struct {
	// Secrets is a map of secrets using the secret name as the key
	Secrets map[string]Secret
	// contains filtered or unexported fields
}

Collection is a struct that holds TOTP data

func NewCollection

func NewCollection() *Collection

NewCollection creates a new, blank Collection instance

func NewCollectionWithData

func NewCollectionWithData(data []byte) (*Collection, error)

NewCollectionWithData creates a new Collection instance with data from a byte slice

func NewCollectionWithFile

func NewCollectionWithFile(filename string) (c *Collection, err error)

NewCollectionWithFile creates a new Collection instance with data from a file. If the file open fails, a new Collection instance is returned along with the file open error, which guarantees a usable but empty collection is returned.

Returning data to be used along with an error is bad design but changing this would be a breaking API change.

func NewCollectionWithReader

func NewCollectionWithReader(reader io.Reader) (*Collection, error)

NewCollectionWithReader creates a new collection from a Reader interface

func (*Collection) DeleteSecret

func (c *Collection) DeleteSecret(name string) (Secret, error)

DeleteSecret deletes an entry by name

func (*Collection) Deserialize

func (c *Collection) Deserialize(data []byte) error

Deserialize unmarshals a byte array into a Collection struct

func (*Collection) GenerateCode

func (c *Collection) GenerateCode(name string) (string, error)

GenerateCode creates a TOTP code with the named secret's value

func (*Collection) GenerateCodeWithTime

func (c *Collection) GenerateCodeWithTime(name string, time time.Time) (string, error)

GenerateCodeWithTime creates a TOTP code with the named secret's value

func (*Collection) GetSecret

func (c *Collection) GetSecret(name string) (Secret, error)

GetSecret returns a secret with the name argument

func (*Collection) GetSecrets

func (c *Collection) GetSecrets() []Secret

GetSecrets returns a slice containing all the secrets

func (*Collection) RenameSecret

func (c *Collection) RenameSecret(oldName, newName string) (Secret, error)

RenameSecret renames a secret

func (*Collection) Save

func (c *Collection) Save() error

Save serializes (marshals) the Collections struct and writes it to a file

func (*Collection) Serialize

func (c *Collection) Serialize() ([]byte, error)

Serialize marshals the Collection struct into a byte array

func (*Collection) SetFilename

func (c *Collection) SetFilename(filename string) string

SetFilename sets the filename for the Save method

func (*Collection) SetWriter

func (c *Collection) SetWriter(writer io.Writer)

SetWriter sets the writer for the Save method

func (*Collection) UpdateSecret

func (c *Collection) UpdateSecret(name, value string) (Secret, error)

UpdateSecret updates (if it exists) or adds a new entry with the name and value given

type CollectionInterface

type CollectionInterface interface {
	DeleteSecret(string) (Secret, error)
	GetSecret(string) (Secret, error)
	GetSecrets() []Secret
	Save() error
	SetFilename(string) string
	UpdateSecret(string, string) (Secret, error)
}

CollectionInterface is used for DI when needed

type Secret

type Secret struct {
	// DateAdded is the date a secret was added to the collection
	DateAdded time.Time

	// DateModified is the date a secret was last modified
	DateModified time.Time

	// Name is the name of the secret used for retrieval
	Name string

	// Value is the secret (seed) value
	Value string
}

Secret is a struct containing data necessary for working with secrets, namely, the name of the secret name and the secret value