Time-Based One-Time Password (TOTP) and HMAC-Based One-Time Password (HOTP) library for Go.

Overview

otpgo

HMAC-Based and Time-Based One-Time Password (HOTP and TOTP) library for Go. Implements RFC 4226 and RFC 6238.

Mentioned in Awesome Go License Go Report Card Test Status Coverage Status PkgGoDev Latest Release

Contents

Supported Operations

  • Generate HOTP and TOTP codes.
  • Verify HOTP an TOTP codes.
  • Export OTP config as a Google Authenticator URI.
  • Export OTP config as a QR code image (used to register secrets in authenticator apps).
  • Export OTP config as a JSON.

Reading Material

Usage

Generating Codes

The simplest way to generate codes is to create the HOTP/TOTP struct and call Generate()

// 
// HMAC-Based
//

// Will use all default values, counter starts in 0
h := otpgo.HOTP{}
token, _ := h.Generate()

// Increment counter and generate next code
h.Counter++
token2, _ := h.Generate()

//
// Time-Based
//

// Will use all default values
t := otpgo.TOTP{}
token, _ := t.Generate()

Each type allows customization. For HMAC-Based tokens you can specify:

  • Key: Secret string, base32 encoded
  • Counter: Unsigned int
  • Leeway: Unsigned int
  • Algorithm: One of HmacSHA1, HmacSHA256 or HmacSHA512
  • Length: Length1 up to Length8

For Time-Based tokens you can specify:

  • Key: Secret string, base32 encoded
  • Period: Integer, period length in seconds
  • Delay: Integer, acceptable number of steps for validation
  • Algorithm: One of HmacSHA1, HmacSHA256 or HmacSHA512
  • Length: Length1 up to Length8

Verifying Codes

Once you receive a token from the user you can verify it by specifying the expected parameters and calling Validate(token string).

// 
// HMAC-Based
//
h := otpgo.HOTP{
    Key: "my-secret-key",
    Counter: 123, // The expected counter
}
ok, _ := h.Validate("the-token")

//
// Time-Based
//
t := otpgo.TOTP{
    Key: "my-secret-key",
}
ok, _ = t.Validate("the-token")

When calling HOTP.Validate() note that the internal counter will be increased if validation is successful, so that the next valid token will correspond to the increased counter.

Both HOTP and TOTP will accept tokens that match the exact Counter/Timestamp or a token within the specified Leeway/Delay.

Registering With Authenticator Apps

Most authenticator apps will give the user 2 options to register a new account: scan a QR code which contains all config and secrets for the OTP generation, or manually enter the secret key and additional info (such as username and issuer). The former being the preferred way because of the ease of use and the avoidance of human error.

QR Code

To generate the QR code just get the KeyUri and call the QRCode method:

otp := otpgo.TOTP{}
base64EncodedQRImage, _ := otp.
   KeyUri("[email protected]", "A Company").
   QRCode()

// Then use base64EncodedQRImage however you like
// e.g.: send it to the client to display as an image

Manual registration

Manual registration usually requires the user to type in the OTP config parameters by hand. The KeyUri type can be easily JSON encoded to then send the params to an external caller or any other place.

otp := otpgo.TOTP{
    Key: "YOUR_KEY",
    Period: 30,
    Delay: 1,
    Algorithm: config.HmacSHA1,
    Length: 6
}
ku := otp.KeyUri("[email protected]", "A Company")
jsonKeyUri, _ := json.Marshal(ku)

// Then use jsonKeyUri however you like
// e.g.: send it to the client for further processing

Defaults

If caller doesn't provide a custom configuration when generating OTPs. The library will ensure the following default values (any empty value will be filled).

HOTP Parameters

Parameter Default Value
Leeway 1 counter down & up
Hash / Algorithm SHA1
Length 6
Key 64 random bytes base32 encoded

TOTP Parameters

Parameter Default Value
Period 30 seconds
Delay 1 period under & over
Hash / Algorithm SHA1
Length 6
Key 64 random bytes base32 encoded
Issues
  • Look ahead in HOTP

    Look ahead in HOTP

    Handle look ahead in HOTP.

    • Add the field to the struct
    • Handle defaults for this new field
    • Update the Validate method to make use of this new options
    • Update test to fully cover the new validate logic
    enhancement 
    opened by jltorresm 1
  • Add method to generate a QR encoded authenticator URI

    Add method to generate a QR encoded authenticator URI

    Depends on #4.

    Applies to both HMAC and Time Based token.

    QR lib: https://github.com/skip2/go-qrcode Debugging tool: https://rootprojects.org/authenticator/

    enhancement 
    opened by jltorresm 0
  • Add method to get OTP params as authenticator URI

    Add method to get OTP params as authenticator URI

    To be able to send data to Google Authenticator, Authy or any other. This method will be used within the QR generating method.

    Relevant Doc: https://github.com/google/google-authenticator/wiki/Key-Uri-Format

    enhancement 
    opened by jltorresm 0
  • Add method to get OTP params as json

    Add method to get OTP params as json

    This applies for both HMAC and time based tokens.

    This functionality will be useful for callers that send generation parameters to external resources. As a generic export other than the authenticator URI.

    enhancement 
    opened by jltorresm 0
Releases(v0.3.0)
  • v0.3.0(Sep 9, 2020)

  • v0.2.0(Sep 2, 2020)

    Added

    • Mark as first official release.
    • QR support to export key URI.
    • Support to format OTP configuration as authenticator key URI.
    • Coverage report with GitHub Actions and Coveralls.

    Changed

    • Improve usage instructions in the README.
    • Generate random keys without padding.
    • Documentation references pkg.go.dev instead of godoc.
    • Internal structure refactor.

    Fixed

    • Handle key padding correctly when generating OTPs.
    Source code(tar.gz)
    Source code(zip)
  • v0.1.0(Aug 28, 2020)

    Important: The code could change dramatically until the official v1. Use with care.

    Added

    • Generation and validation of tokens.
    • Simple standalone usage examples.
    • GitHub Actions configuration for continuous testing.
    • HMAC-Based and Time-Based OTP types.
    • OTP calculation algorithm full spec.
    • List of supported algorithms.
    • Basic go module configuration, README, badges.
    Source code(tar.gz)
    Source code(zip)
Owner
Jose Torres
Jose Torres
Gotp - Generate TOTP codes from standalone TOTP secret keys

⏲️ GOTP Generate TOTP codes from standalone TOTP secrets. Usage $ gotp TOTPSECRE

Federico Damián Schonborn 1 Mar 22, 2022
HMAC-based JWT written in Go

JWT JSON Web Tokens JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties. Usage of jwt:

Pedro Albanese 0 Nov 16, 2021
Implementation of RFC-6238 (Time-Based One-Time Password Algorithm) in Go.

TOTP TOTP (RFC-6238) implementation in Go with no external dependencies. INSTALL You can do little copying the totp.go file or add this package as Go

Sarjono Mukti Aji 1 Jan 18, 2022
✨ Pretty TOTP manager in your terminal

asunder Asunder, Sweet and Other Distress asunder is a small pretty command-line TOTP manager. Installation Binaries Download a binary from the releas

obscurity 3 May 14, 2022
Yet another ykman Go lib for requesting OATH TOTP Multi-Factor Authentication Codes from Yubikey Devices

ykmangoath Ykman OATH TOTP with Go Yet another ykman Go lib for requesting OATH TOTP Multi-Factor Authentication Codes from Yubikey Devices. ?? Work-i

Ari Palo 4 Jul 3, 2022
Go based HTTP server with 2FA based on OTP (One-Time Password) manager like Google Authenticator

Go based HTTP server with 2FA based on OTP (One-Time Password) manager like Goog

Valentin Kuznetsov 5 Jul 8, 2022
Go implementation of OTP (One-time-password). SMS send async (goroutine)

Go-OTP Go realization to otp authentication Stack: Redis (Save OTP and token) Go SMS provider (Megafon as example) Schema: User send phonenumber (ex.7

Andrei Koptev 0 Dec 14, 2021
One time password for Go.

otp One time password for Go. Features Simple API. Dependency-free. Clean and tested code. HOTP RFC 4226. TOTP RFC 6238. See GUIDE.md for more details

cristaltech 4 May 16, 2022
Terraform utility provider for generating Time-Based One-Time Passwords (TOTPs)

Terraform TOTP Provider The TOTP provider is a utility provider, which allows for generating Time-Based One-Time Passwords (TOTP) following the RFC 62

null 2 Dec 27, 2021
Go library for one-time passwords, supports HOPT and TOPT (Google Authenticator compatible)

GoTP: One-time password library for Go GoTP library provides implementations of one-time password generators and validators. This implemantation suppo

Oleksiy Voronin 4 May 5, 2022
Goauth - Basic username password cookie based authentication with Go Lang

goauth [WIP] Basic username password cookie based authentication with Go Lang Overview Use a Postgres DB to store Sign-in and Sign-up info Redis for c

Joseph Chen 0 Jan 4, 2022
simple-jwt-provider - Simple and lightweight provider which exhibits JWTs, supports login, password-reset (via mail) and user management.

Simple and lightweight JWT-Provider written in go (golang). It exhibits JWT for the in postgres persisted user, which can be managed via api. Also, a password-reset flow via mail verification is available. User specific custom-claims also available for jwt-generation and mail rendering.

Max 26 Jul 24, 2022
Onetime-Password generator sample writte in Go.

Go OTP Sample Goのgithub.com/pquerna/otpを使用したワンタイムパスワード生成実験 実験方法 Google Authenticator Microsoft Authenticator 1password 以上、3つのワンタイムパスワード生成器を利用し、ハッシュアルゴ

Yuto Watanabe 0 Nov 27, 2021
A Go library for doing header-based OAuth over HTTP or HTTPS.

Installation goinstall github.com/alloy-d/goauth Usage import ( "github.com/alloy-d/goauth" "os" ) func someFuncThatDoesStuffWithOAuth() (er

Adam Lloyd 24 Sep 2, 2020
JWT wrapper library which makes it simple to use ECDSA based JWT signing

JWT JWT wrapper library which makes it simple to user ECDSA based JWT signing. Usage package main import ( "context" "github.com/infiniteloopcloud

infinite loop 0 Feb 10, 2022
Go-Guardian is a golang library that provides a simple, clean, and idiomatic way to create powerful modern API and web authentication.

❗ Cache package has been moved to libcache repository Go-Guardian Go-Guardian is a golang library that provides a simple, clean, and idiomatic way to

Sanad Haj Yahya 388 Aug 2, 2022
A simple and lightweight library for creating, formatting, manipulating, signing, and validating JSON Web Tokens in Go.

GoJWT - JSON Web Tokens in Go GoJWT is a simple and lightweight library for creating, formatting, manipulating, signing and validating Json Web Tokens

Toby 5 Feb 7, 2022
A library for performing OAuth Device flow and Web application flow in Go client apps.

oauth A library for Go client applications that need to perform OAuth authorization against a server, typically GitHub.com. Traditionally,

GitHub CLI 336 Aug 9, 2022
A library and binary to dump authentication configuration from etcd.

A libary and binary to dump authentication information from etcd. The commands are suitable for configuring an empty etcd cluster to get to the same authentication config.

Jille Timmermans 1 Jan 20, 2022