gotp

README

G - Otp

G - Otp is a Golang client for Google Authenticator.

Google Authenticator Logic

Google Authenticator uses a HMAC-based One-time Password Algorithm (HOTP) to generate a one-time password. The algorithm is described in RFC 4226. The algorithm uses a shared secret key and a counter value to generate a one-time password. The counter value is incremented after each password generation. The counter value is usually the current time in seconds divided by a time step. The time step is usually 30 seconds. The shared secret key is usually a random string of bytes. The shared secret key is usually stored in the user's mobile device. The one-time password is usually displayed to the user as a 6-digit number.

With Lifecycle

First, you must create a secret key for the user. (Fear not, our gotp package will do it; just run it.)

Then you have to generate a qr code with secret key and some customizable data. (gotp will do that too, just run it.)

Then show the qr to the user and tell him to scan it from the Google Authenticator app.

Then wait for the user to enter a code.

When the user enters a code, tell gotp to verify it and give him the user's secret.

This will give you a boolean value. Then you can run the logic you want.

Installation

go get github.com/9ssi7/gotp

Contributing

Contributions are always welcome!

License

MIT

Documentation

Variables
gotp.Digits
gotp.Algorithm
gotp.SecretSize
gotp.Period
gotp.ValidChars

Functions
gotp.CreateSecret()
gotp.GetCode(..., ...)
gotp.GetTime()
gotp.Verify(...)
gotp.GetQRCode(...)

Variables

Variables have parameters that are used when generating, decoding, and validating code. You can customize the variables.

Digits

Digits is the number of digits in the code. It must be between 6 and 8. The default is 6.

import "github.com/9ssi7/gotp"

gotp.Digits = gotp.DigitsEight

Algorithm

Algorithm is the algorithm used to generate the code. The default is SHA1.

import "github.com/9ssi7/gotp"

gotp.Algorithm = gotp.AlgorithmSHA256
gotp.Algorithm = gotp.AlgorithmSHA512

SecretSize

SecretSize is the size of the secret key in bytes. The default is 10.

import "github.com/9ssi7/gotp"

gotp.SecretSize = 20

Period

Period is the time step in seconds. The default is 30.

import "github.com/9ssi7/gotp"

gotp.Period = 60

ValidChars

ValidChars is the set of characters that are used to generate the secret key. The default is "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567".

import "github.com/9ssi7/gotp"

gotp.ValidChars = "0123456789"

Functions

Functions are used to generate, decode, and validate code.

CreateSecret

CreateSecret creates a secret key. The secret key is a random string of bytes. The secret key is usually stored in the user's mobile device.

import "github.com/9ssi7/gotp"

secret := gotp.CreateSecret()

GetCode

GetCode generates a one-time password. The one-time password is usually displayed to the user as a 6-digit number.

import "github.com/9ssi7/gotp"

code := gotp.GetCode("secret", 0)

GetTime

GetTime returns the current time in seconds.

import "github.com/9ssi7/gotp"

time := gotp.GetTime()

Verify

Verify verifies a one-time password. The one-time password is usually entered by the user.

import "github.com/9ssi7/gotp"

valid := gotp.Verify(gotp.VerifyConfig{
    Secret: "secret",
    Code:   "123456",
})

GetQRCode

GetQRCode generates a qr code with secret key and some customizable data.

import "github.com/9ssi7/gotp"

qr := gotp.GetQRCode(gotp.QrConfig{
    Secret: "secret",
    Issuer: "Your Company",
    AccountName: "User Name / Email",
}) 

</docgen-api>

Documentation

Index

• Variables
• func CreateSecret() string
• func GetCode(secret string, time int64) string
• func GetQRCode(config QrConfig) string
• func GetTime() int64
• func Verify(config VerifyConfig) bool
• type Algorithm
  • func (a Algorithm) Hash() func() hash.Hash
  • func (a Algorithm) String() string
• type Digits
  • func (d Digits) Length() int
  • func (d Digits) String() string
• type QrConfig
• type VerifyConfig

Variables

var Config = config{

	Digits: DigitsSix,

	SecretSize: 16,

	Period: 30,

	Algorithm: AlgorithmSHA1,

	ValidChars: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
}

Config is the configuration for the package. It can be changed to customize the package. The default configuration is:

SecretSize:    16,
Period:        30,
Algorithm:     AlgorithmSHA1,
Digits:        DigitsSix,
ValidChars:    "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",

Functions

func CreateSecret

func CreateSecret() string

CreateSecret returns a random secret key. The secret key is a string of characters from the set A-Z, 2-7. The default length of the secret key is 16 characters. This can be changed by setting Config.SecretSize. The default set of characters can be changed by setting Config.ValidChars.

func GetCode

func GetCode(secret string, time int64) string

GetCode returns the current code for the secret key. The code is valid for the current period. The period is 30 seconds by default. This can be changed by setting Config.Period.

func GetQRCode

func GetQRCode(config QrConfig) string

GetQRCode returns the URL of the QR code for the secret key. The QR code can be used to add the secret key to an authenticator app. The QR code is a Google Chart. The QR code is a PNG image.

func GetTime

func GetTime() int64

GetTime returns the current time in Unix time divided by the period. This is used to generate the counter for the HOTP algorithm. The period is 30 seconds by default. This can be changed by setting Config.Period. The Unix time is divided by the period to make it easier to test. This way, the counter can be set to any value.

func Verify

func Verify(config VerifyConfig) bool

Verify verifies the code against the secret key. It returns true if the code is valid, false otherwise.

Types

type Algorithm

type Algorithm int

Algorithm is the hash function used to generate the code.

const (
	// AlgorithmSHA1 is the hash function used to generate the code.
	AlgorithmSHA1 Algorithm = 1

	// AlgorithmSHA256 is the hash function used to generate the code.
	AlgorithmSHA256 Algorithm = 2

	// AlgorithmSHA512 is the hash function used to generate the code.
	AlgorithmSHA512 Algorithm = 3
)

func (Algorithm) Hash

func (a Algorithm) Hash() func() hash.Hash

Hash returns the hash function.

func (Algorithm) String

func (a Algorithm) String() string

String returns the string representation of the hash function.

type Digits

type Digits int

Digits is the number of digits in the code. It can be 6 or 8. The default is 6.

const (
	// DigitsSix is the number of digits in the code.
	DigitsSix Digits = 6

	// DigitsEight is the number of digits in the code.
	DigitsEight Digits = 8
)

func (Digits) Length

func (d Digits) Length() int

Length returns the number of digits.

func (Digits) String

func (d Digits) String() string

String returns the string representation of the number of digits.

type QrConfig

type QrConfig struct {
	// Secret is the secret key.
	Secret string

	// Issuer is the name of the issuer. This is optional. If set, it will be displayed on the authenticator app. For example, "Google".
	Issuer string

	// AccountName is the name of the account. This is required. For example, "John Doe".
	// This will be displayed on the authenticator app.
	// The final display will be "Issuer (AccountName)" or "AccountName" if Issuer is not set.
	AccountName string
}

QrConfig is the configuration for the GetQRCode function.

type VerifyConfig

type VerifyConfig struct {
	// Secret is the secret key.
	// It must be a string of valid characters.
	Secret string
	// Code is the code to verify.
	// It must be a string of digits.
	Code string
	// Window is the number of codes to check before and after the current code.
	// If Window is 0, only the current code is checked.
	Window int
}

VerifyConfig is the configuration for the Verify function.