basicOTP

README

BasicOTP

BasicOTP is a Go library for generating and validating one-time passwords (OTP). It provides implementations for both Time-based One-Time Passwords (TOTP) and Sequence-based One-Time Passwords (HOTP).

This library is my own implementation based on the RFC specifications. However, it's important to note that I do not recommend using this library for production purposes without thorough auditing and testing. It may still have limitations or potential issues that need to be addressed before being used.

Overview

The BasicOTP library aims to simplify the generation and validation of one-time passwords in Go applications. It consists of three main components:

1. HOTP: Represents a Sequence-based One-Time Password generator.
2. TOTP: Represents a Time-based One-Time Password generator.
3. OTP: Provides the underlying functionality for generating and validating one-time passwords.

Features

• Support for TOTP and HOTP: BasicOTP supports both Time-based (TOTP) and Sequence-based (HOTP) OTP generation and validation.
• Configurable Hash Algorithms: Users can choose from different hash algorithms including SHA1, SHA256, and SHA512 according to their security requirements.
• Customizable Code Length: BasicOTP allows customization of the length of generated OTP codes to meet specific application needs.
• URI Generation: BasicOTP provides a convenient method for generating URIs according to the Google Authenticator Key URI Format, facilitating integration with OTP token apps.
• Synchronization in HOTP Validation: BasicOTP supports synchronization in HOTP validation, allowing the Validate() function to look ahead and fast forward the counter to the client's counter if a valid token is found.

Use Cases

BasicOTP is suitable for a variety of use cases including:

• Two-Factor Authentication (2FA): Implementing OTP-based 2FA for user authentication in web or mobile applications.
• Secure Transaction Authorization: Generating OTPs for authorizing sensitive transactions or operations in financial or enterprise systems.
• Passwordless Authentication: Using OTPs as an alternative to traditional password-based authentication for improved security and user experience.

Dependencies

BasicOTP is built using Go and leverages Go standard cryptographic libraries for hash functions and HMAC calculation. It is compatible with modern Go development environments and has no third-party dependencies.

Installation

To use BasicOTP in your Go project, you can import it using Go modules:

go get github.com/sebastian-mora/basicOTP

Example

package main

import (
    "fmt"
    "github.com/sebastian-mora/basicOTP"
)

func main() {
    // Create a new TOTP instance
    totp := basicOTP.NewTOTP(basicOTP.TOTPConfig{
        TimeInterval: 30, // Time interval in seconds (default is 30 seconds)
        CodeLength: 6, // Length of generated OTP code (default is 6)
        HashType: basicOTP.SHA1, // Hash algorithm (SHA1, SHA256, or SHA512)
        Secret: []byte("mysecret"),
    })

    // Generate a TOTP code
    code := totp.Generate()

    fmt.Println("Generated TOTP:", code)

    // Validate a TOTP code
    isValid := totp.Validate(code)

    fmt.Println("Is valid TOTP:", isValid)

    // Generate URI for TOTP
    uri := totp.URI("MyLabel", "MyIssuer")

    fmt.Println("TOTP URI:", uri)

}

Documentation

Overview

Package basicOTP implements One-Time Password (OTP) generation according to RFC 4226 and RFC 6238. It provides functionality to generate OTP codes using HMAC-based algorithms like SHA-1, SHA-256, and SHA-512. This package is useful for implementing two-factor authentication (2FA) systems.

Index

• type HOTPConfig
• type HTOP
  • func NewHTOP(config HOTPConfig) *HTOP
  • func (h *HTOP) Generate() string
  • func (t *HTOP) URI(label string, issuer string) string
  • func (h *HTOP) Validate(input string) bool
• type HashType
• type OTP
  • func NewOTP(secret []byte, hashType HashType, codeLength int) OTP
  • func (o OTP) Generate(input int) string
• type TOTP
  • func NewTOTP(config TOTPConfig) *TOTP
  • func (t *TOTP) Generate() string
  • func (t *TOTP) GenerateAt(unixTimeStamp int64) string
  • func (t *TOTP) URI(label string, issuer string) string
  • func (t *TOTP) Validate(code string) bool
  • func (t *TOTP) ValidateAt(unixTimestamp int64, code string) bool
• type TOTPConfig

Types

type HOTPConfig

type HOTPConfig struct {
	CodeLength           int      // CodeLength is the length of the generated OTP code.
	HashType             HashType // HashType is the hash algorithm used for OTP generation.
	Secret               []byte   // Secret is the shared secret key used for OTP generation.
	Counter              int      // Counter is the initial counter value for HOTP generation.
	SynchronizationLimit int      // SynchronizationLimit sets the limit for synchronization in HOTP validation.

}

HOTPConfig holds configuration parameters for HOTP generation.

type HTOP

type HTOP struct {
	Counter int
	// contains filtered or unexported fields
}

HTOP represents a Sequence-based One-Time Password generator.

func NewHTOP

func NewHTOP(config HOTPConfig) *HTOP

NewHTOP creates a new instance of hopt based on the provided HOTPConfig.

func (*HTOP) Generate

func (h *HTOP) Generate() string

Generate returns a string representing a HOTP code. generating a code increments the HOTP counter

func (*HTOP) URI

func (t *HTOP) URI(label string, issuer string) string

URI generates the URI according to the Google Authenticator Key URI Format. See: https://github.com/google/google-authenticator/wiki/Key-Uri-Format

func (*HTOP) Validate

func (h *HTOP) Validate(input string) bool

Validate validates an input OTP code against the current counter value. the function will attempt to look ahead for codes using synchronizationLimit as the upper bound.

type HashType

type HashType string

HashType represents the type of hash algorithm supported.

const (
	SHA1   HashType = "SHA1"
	SHA256 HashType = "SHA256"
	SHA512 HashType = "SHA512"
)

type OTP

type OTP struct {
	HashType HashType // HashType is the type of hash algorithm used.

	CodeLength int // CodeLength is the length of the generated OTP code.
	// contains filtered or unexported fields
}

OTP represents a One-Time Password generator.

func NewOTP

func NewOTP(secret []byte, hashType HashType, codeLength int) OTP

NewOTP creates a new instance of OTP based on the provided configuration. The function will substitute default values for parameters as per the specification:

• codeLength defaults to 6.
• hashFunc will default to SHA1.
• A secret is required but length is not enforced. RFC recommends a shared secret of at least 128 bits.

func (OTP) Generate

func (o OTP) Generate(input int) string

Generate generates an OTP code based on the provided input.

type TOTP

type TOTP struct {
	TimePeriod int // TimePeriod is the time period in seconds used for TOTP generation.
	// contains filtered or unexported fields
}

TOTP represents a Time-based One-Time Password generator.

func NewTOTP

func NewTOTP(config TOTPConfig) *TOTP

NewTOTP creates a new instance of TOTP based on the provided configuration.

func (*TOTP) Generate

func (t *TOTP) Generate() string

Generate generates a TOTP for the current time interval.

func (*TOTP) GenerateAt

func (t *TOTP) GenerateAt(unixTimeStamp int64) string

GenerateAt generates a TOTP for the given Unix timestamp.

func (*TOTP) URI

func (t *TOTP) URI(label string, issuer string) string

URI generates the URI for the TOTP according to the Google Authenticator Key URI Format. See: https://github.com/google/google-authenticator/wiki/Key-Uri-Format

func (*TOTP) Validate

func (t *TOTP) Validate(code string) bool

Validate validates a TOTP against the current time interval.

func (*TOTP) ValidateAt

func (t *TOTP) ValidateAt(unixTimestamp int64, code string) bool

ValidateAt validates a TOTP against a given Unix timestamp.

type TOTPConfig

type TOTPConfig struct {
	TimeInterval int      // TimeInterval is the time interval in seconds for TOTP generation.
	CodeLength   int      // CodeLength is the length of the generated TOTP code.
	HashType     HashType // HashType is the hash algorithm used for TOTP generation.
	Secret       []byte   // Secret is the shared secret key used for TOTP generation.
}

TOTPConfig holds configuration parameters for TOTP generation.