mfa

README

mfa

A virtual (terminal-based) Multi-factor-Authentication device. Can be used in the same way as tools like Google Authenticator.

Tools like Google Authenticator are usually run on a separate device to the device you use to log in so that if one device is lost / stolen, all credentials (SSH keys, saved passwords in browsers, etc) are not compromised.

This utility is really intended for situations like logging into your AWS account where you will enter the password (you don't keep it saved in your browser!) and have MFA configured but don't want to use a phone or are concerned about loss or damage to your phone.

The magic is all done by pquerna/otp. This utility wraps the above library into an executable and add flags for setting algorithms, colors, timing options, etc.

To use this with AWS, if you already have an MFA device associated with your account, you will need to replace it. Remove the existing device under your accounts "My Security Credentials", add a new Virtual MFA device, choose the option to "Show secret key" & save the key to $HOME/.mfa/secret. You should also make sure this file is only readable to your user (you will get a warning when running mfa if you do not)!

For more details on the options:

go run cmd/cmd.go --help

Docker

There is also a Docker image available: The following example assumes your local machine has your secret file in the default location & overrides the default entrypoint to demonstrate setting custom colors & a timezone.

docker run --rm --name mfa -e TZ="Europe/London" -v $HOME/.mfa/secret:/.mfa/secret --entrypoint="" roybrumby/mfa:1.0 /mfa --color=cyan --warn-color=yellow

If you run the above with -d, your container will run in the background & you can then run the following to attach to it:

docker attach mfa

...or, if your container is stopped because you pressed c to exit from a previous attach:

docker start -a mfa

Documentation

Index

• Variables
• func Algorithm(alg string) func(*MFADevice)
• func DefaultColor(c Color) func(*Terminal)
• func Digits(dig int) func(*MFADevice)
• func ErrorColor(c Color) func(*Terminal)
• func Output(w Writer) func(*MFADevice)
• func Prefix(pre string) func(*Terminal)
• func RefreshPeriod(per uint) func(*MFADevice)
• func Secret(secret string) func(*MFADevice)
• func SecretFromFile(file *os.File) func(*MFADevice)
• func UpdateFrequency(p time.Duration) func(*MFADevice)
• func WarningColor(c Color) func(*Terminal)
• type Color
• type MFADevice
  • func NewMFADevice(options ...func(*MFADevice)) *MFADevice
  • func (d *MFADevice) Run()
• type Terminal
  • func NewTerminal(options ...func(*Terminal)) *Terminal
  • func (t *Terminal) Error(p []byte) error
  • func (t *Terminal) Warn(p []byte) error
  • func (t *Terminal) Write(p []byte) error
• type Writer

Variables

var TerminalColors map[string]Color = map[string]Color{
	"red":    Red,
	"green":  Green,
	"yellow": Yellow,
	"blue":   Blue,
	"purple": Purple,
	"cyan":   Cyan,
	"gray":   Gray,
	"white":  White,
}

Functions

func Algorithm

func Algorithm(alg string) func(*MFADevice)

func DefaultColor

func DefaultColor(c Color) func(*Terminal)

DefaultColor is a functional option for setting the terminal default text color

func Digits

func Digits(dig int) func(*MFADevice)

func ErrorColor

func ErrorColor(c Color) func(*Terminal)

ErrorColor is a functional option for setting the terminal error text color

func Output

func Output(w Writer) func(*MFADevice)

Output is a functional option to tell an MFADevice which Writer to output OTP codes to

func Prefix

func Prefix(pre string) func(*Terminal)

Prefix is a functional option for setting a prefix to help identify an OTP (if you have multiple running)

func RefreshPeriod

func RefreshPeriod(per uint) func(*MFADevice)

func Secret

func Secret(secret string) func(*MFADevice)

Secret is a functional option to set a secret on an MFADevice

func SecretFromFile

func SecretFromFile(file *os.File) func(*MFADevice)

SecretFromFile is a functional option to tell an MFADevice to read the secret from a file

func UpdateFrequency

func UpdateFrequency(p time.Duration) func(*MFADevice)

UpdateFrequency is a functional option to tell an MFADevice to read the secret from a file

func WarningColor

func WarningColor(c Color) func(*Terminal)

WarningColor is a functional option for setting the terminal warning text color

Types

type Color

type Color string

const (
	SecretFileNameEnv       = "MFA_SECRET_FILE"
	Red               Color = "\033[31m"
	Green             Color = "\033[32m"
	Yellow            Color = "\033[33m"
	Blue              Color = "\033[34m"
	Purple            Color = "\033[35m"
	Cyan              Color = "\033[36m"
	Gray              Color = "\033[37m"
	White             Color = "\033[97m"
)

type MFADevice

type MFADevice struct {
	Secret          []byte
	Writer          Writer
	UpdateFrequency time.Duration
	TOTPOptions     totp.ValidateOpts
}

func NewMFADevice

func NewMFADevice(options ...func(*MFADevice)) *MFADevice

NewMFADevice creates a new MFADevice using functional options

func (*MFADevice) Run

func (d *MFADevice) Run()

Run runs the MFADevice

type Terminal

type Terminal struct {
	Pattern      string
	Prefix       string
	DefaultColor Color
	WarningColor Color
	ErrorColor   Color
}

Terminsl is a Writer for writing out OTP codes & error/warning messages

func NewTerminal

func NewTerminal(options ...func(*Terminal)) *Terminal

NewTerminal creates a new Terminal using functional options to set the output colors

func (*Terminal) Error

func (t *Terminal) Error(p []byte) error

Error writes in the ErrorColor of the Terminal

func (*Terminal) Warn

func (t *Terminal) Warn(p []byte) error

Warn writes in the WarningColor of the Terminal

func (*Terminal) Write

func (t *Terminal) Write(p []byte) error

Write writes in the DefaultColor of the Terminal

type Writer

type Writer interface {
	Write(p []byte) error
	Warn(p []byte) error
	Error(p []byte) error
}

Writer is an interface which an MFADevce will write to