gotp

README

gotp

Golang secure storage for your 2FA secret from your terminal.

gotp has only been tested on Mac OS X (Mojave). It requires specific installation to be used with pass on Linux.

Context

Modern web services offer a 2-factor authentication as a complement of the traditional login/password method. This brings an additional security level, based on the Time-based One-Time Password (TOTP), because even if a user's traditional password is stolen or compromised, an attacker cannot gain access without the TOTP, which expires quickly.

A time-based one-time password (TOTP) is a temporary passcode generated by an algorithm that uses the current time of day as one of its authentication factors.

The TOTP specification (RFC-6238) describes the TOTP algorithm, as an time-based variant of the One-Time Password (OTP), namely the HMAC-based One-Time Password (HOTP) algorithm.

The TOTP is basicaly a hash-mac token computed from a shared key (generaly randomky generated) and seed with a 30-second valid timestamp. Lot's of mobile applications can provide such a service (Google Authenticator, ...)

When you wish to log into a 2FA protected service, you are asked to provide your credentials (login/password) then to enter the TOTP displayed on the application. The web service computed the same TOTP and make sure they are equal.

Motivation

I started using this security feature long time ago, and was happy using the Google Authenticator application on my mobile phone. Until I realized I forgot to export all the secret keys I use every day at work on my new phone, and was unable to connect to AWS console for a day.

That day, I wish I had a backup solution on my laptop. Then I started to wonder how I could implement a desktop application with a secure storage backend.

Use gotp as a program

Download

Get the version for your OS here: download

Install as a command line tool

go get -u github.com/jtbonhomme/gotp/cmd/gotp

Linux - pass backend setup

In order to use the pass backend, you need to initialize it and specify which GPG encryption identity to use. For further informations, see the pass manual.

1 - find your GPG ID gpg --list-secret-keys --keyid-format LONG

uid                 [ultimate] you <you@rocks.com>
ssb   rsa4096/DF5E537CC91EF1CA 2020-03-06 [E]

2 - initialize the backend pass init DF5E537CC91EF1CA

All secrets will be stored under the root folder username:mfa

Add a key

The shared secret shall be in the base-32 format.

gotp add -key=gmail -value=KZAUYVKFGA======

Get a code

The code read is copied to the clipboard.

gotp get -key=AWS
code: 585146 (copied to clipboard)

List all keys

gotp list

Delete a key

gotp del -key=gmail

The secure KeyChain

gotp uses the keyring library to securely store the secret used to compute Time based OTP.

Todo

• Add an update function, to change key name
• Add tests on different OS.

Contributing

gotp accepts Pull Requests! Feel free to add your own features, improve documentation or add tests.

Run tests

$ make test

Execute github actions locally

You can use act to execute locally your github actions. This tool relies on docker to run workflow jobs.

$ act -l
ID       Stage  Name              
build    0      GoReleaser build
release  0      Semver release
test     0      test
$ act -j test

References

• https://godoc.org/github.com/99designs/keyring
• https://tools.ietf.org/html/rfc6238
• https://medium.com/@n.moretto/two-factor-authentication-with-totp-ccc5f828b6df

Documentation

Index

• Constants
• type GOTP
  • func New(bkd backend.Backend) *GOTP
  • func (gotp *GOTP) Get(key string) (string, error)
  • func (gotp *GOTP) List() ([]string, error)
  • func (gotp *GOTP) Remove(key string) error
  • func (gotp *GOTP) Store(key, value string) error
  • func (gotp *GOTP) WithTimeIntervalSeed(interval uint) *GOTP

Constants

const DefaultTimeIntervalSeed uint = 30

DefaultTimeIntervalSeedTimeIntervalSeed is the default time interval seed used to compute the HOTP.

Types

type GOTP

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

func New

func New(bkd backend.Backend) *GOTP

New instanciates a GoTP object with a secured backend

func (*GOTP) Get

func (gotp *GOTP) Get(key string) (string, error)

Get retrieves a key in the secured key ring

func (*GOTP) List

func (gotp *GOTP) List() ([]string, error)

List retrieves all existing keys in the secured key ring

func (*GOTP) Remove

func (gotp *GOTP) Remove(key string) error

Remove deletes a key in the secured key ring

func (*GOTP) Store

func (gotp *GOTP) Store(key, value string) error

Store creates a new key/value pair in the secured key ring

func (*GOTP) WithTimeIntervalSeed

func (gotp *GOTP) WithTimeIntervalSeed(interval uint) *GOTP

WithTimeIntervalSeed configures a specific timeIntervalSeed