otp

func DecodeSecret ¶

func DecodeSecret(secret string) ([]byte, error)

func GenerateHOTP ¶

func GenerateHOTP(secret string, counter uint64, param *Param) (string, error)

GenerateHOTP generates an HOTP code from a given secret and counter. If `param` is nil, DefaultHOTPParam is used.

package main

import (
	"fmt"
	"github.com/ja7ad/otp"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	code, err := otp.GenerateHOTP(secret, 1, otp.DefaultHOTPParam)
	if err != nil {
		panic(err)
	}

	fmt.Println(code)
}

func GenerateHOTPURL ¶

func GenerateHOTPURL(param URLParam) (*url.URL, error)

GenerateHOTPURL constructs an otpauth:// URL for configuring HOTP-based authenticators. The URL includes the issuer, account name, secret, algorithm, digits, and counter.

Example output: otpauth://hotp/Example:alice@domain.com?secret=BASE32ENCODEDSECRET&issuer=Example&algorithm=SHA1&digits=6&counter=0

package main

import (
	"fmt"
	"github.com/ja7ad/otp"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	url, err := otp.GenerateHOTPURL(otp.URLParam{
		Issuer:      "https://example.com",
		Secret:      secret,
		AccountName: "foobar",
		Period:      otp.DefaultHOTPParam.Period,
		Digits:      otp.DefaultHOTPParam.Digits,
		Algorithm:   otp.DefaultHOTPParam.Algorithm,
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(url.String())
}

func GenerateOCRA ¶

func GenerateOCRA(secret string, suite Suite, input OCRAInput) (string, error)

GenerateOCRA generates a one-time password (OTP) using the OCRA algorithm (RFC 6287) for the given secret, suite, and input parameters.

The `secret` should be a base32-encoded shared key (e.g., from provisioning), and will be decoded into its raw binary form. The `suite` defines the OCRA configuration (create Suite using NewSuite or NewRawSuite). The `input` provides dynamic values like challenge, counter, session data, timestamp, etc.

Returns the generated OTP string or an error if decoding the secret or derivation fails.

package main

import (
	"fmt"
	"github.com/ja7ad/otp"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	suite := otp.MustRawSuite("OCRA-1:HOTP-SHA1-6:QN08")

	code, err := otp.GenerateOCRA(secret, suite, otp.OCRAInput{
		Challenge: []byte("12345678"),
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(code)
}

func GenerateTOTP ¶

func GenerateTOTP(secret string, t time.Time, param *Param) (string, error)

GenerateTOTP generates a TOTP code based on the given secret and timestamp. If param is nil, DefaultTOTPParam is used. The secret must be encoded according to the specified algorithm's encoding (e.g., base32 for SHA1).

package main

import (
	"fmt"
	"github.com/ja7ad/otp"
	"time"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	code, err := otp.GenerateTOTP(secret, time.Now(), otp.DefaultTOTPParam)
	if err != nil {
		panic(err)
	}

	fmt.Println(code)
}

func GenerateTOTPURL ¶

func GenerateTOTPURL(param URLParam) (*url.URL, error)

GenerateTOTPURL constructs an otpauth:// URL for configuring TOTP-based authenticators (e.g., Google Authenticator). The URL includes the issuer, account name, secret, and TOTP parameters.

Example output: otpauth://totp/Example:alice@domain.com?secret=BASE32ENCODEDSECRET&issuer=Example&algorithm=SHA1&digits=6&period=30

package main

import (
	"fmt"
	"github.com/ja7ad/otp"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	url, err := otp.GenerateTOTPURL(otp.URLParam{
		Issuer:      "https://example.com",
		Secret:      secret,
		AccountName: "foobar",
		Period:      otp.DefaultTOTPParam.Period,
		Digits:      otp.DefaultTOTPParam.Digits,
		Algorithm:   otp.DefaultTOTPParam.Algorithm,
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(url.String())
}

func IsKnownSuite ¶

func IsKnownSuite(raw string) bool

IsKnownSuite reports whether the given raw OCRA suite string is registered in the internal list of known supported suite configurations.

This is useful for validating user input or performing discovery checks.

Example:

if !IsKnownSuite(input) {
    return fmt.Errorf("unsupported OCRA suite")
}

func LeftPadHex ¶

func LeftPadHex(s string, totalLen int) string

LeftPadHex returns the input hex string left-padded with '0' characters until it reaches totalLen characters. If the input string is longer than or equal to totalLen, it returns the rightmost totalLen characters.

func ListSuites ¶

func ListSuites() []string

ListSuites returns all registered and supported OCRA raw suite strings. This is useful for introspection, documentation, CLI display, or API discovery.

func MustHexPadLeft ¶

func MustHexPadLeft(hexStr string, size int) []byte

MustHexPadLeft decodes a hex string after left-padding it to the desired byte length. The size parameter specifies the desired number of bytes; the function left-pads the hex string to size*2 characters. It panics if the hex decoding fails.

func ParseDecimal64BigEndian ¶

func ParseDecimal64BigEndian(decStr string) ([]byte, error)

ParseDecimal64BigEndian is similar to ParseDecimalToBigEndian8. It converts a decimal string to an 8-byte big-endian slice by parsing the string as a uint64.

func ParseDecimalChallengeRFC6287 ¶

func ParseDecimalChallengeRFC6287(s string) ([]byte, error)

ParseDecimalChallengeRFC6287 converts a decimal challenge string to a 128-byte value as required by RFC 6287. The conversion process is as follows:

1. Parse the input as a decimal number into a big.Int.
2. Convert the number to an uppercase hexadecimal string.
3. Right-pad the hex string with '0's until its length is 256 characters (which corresponds to 128 bytes).
4. Decode the padded hex string into a byte slice.

func ParseDecimalToBigEndian8 ¶

func ParseDecimalToBigEndian8(s string) ([]byte, error)

ParseDecimalToBigEndian8 converts a decimal string to an 8-byte big-endian representation. It interprets the input string as a base-10 unsigned integer, then returns an 8-byte slice where the most-significant byte is at index 0. This is useful for encoding counters or similar values.

func ParseHexTimestamp ¶

func ParseHexTimestamp(ts string) ([]byte, error)

ParseHexTimestamp converts a hex-encoded timestamp string to an 8-byte slice. It left-pads the input string with '0' characters until it is 16 hex digits long (i.e. 8 bytes), then decodes the padded string.

func RandomSecret ¶

func RandomSecret(algo Algorithm) (string, error)

RandomSecret returns a base32-encoded random secret for the given algorithm. The secret is of appropriate byte length for RFC-compliant HOTP/TOTP implementations.

func To8ByteBigEndian ¶

func To8ByteBigEndian(v uint64) []byte

To8ByteBigEndian converts a uint64 value into an 8-byte big-endian slice. This is a convenience function for encoding counters or time values.

func ValidateHOTP ¶

func ValidateHOTP(secret, code string, counter uint64, param *Param) (bool, error)

ValidateHOTP checks whether the given HOTP code is valid for the provided secret and counter. Returns true if valid, false otherwise. Uses constant-time comparison internally. If `param` is nil, DefaultHOTPParam is used.

package main

import (
	"fmt"
	"github.com/ja7ad/otp"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	counter := uint64(1)

	code, err := otp.GenerateHOTP(secret, counter, otp.DefaultHOTPParam)
	if err != nil {
		panic(err)
	}

	fmt.Println(code)

	ok, err := otp.ValidateHOTP(secret, code, counter, otp.DefaultTOTPParam)
	if err != nil {
		panic(err)
	}

	fmt.Println(ok)
}

func ValidateOCRA ¶

func ValidateOCRA(secret, code string, suite Suite, input OCRAInput) (bool, error)

ValidateOCRA checks whether a provided OTP code is valid for the given OCRA suite, secret, and input parameters.

The `secret` should be a base32-encoded key, which is decoded before validation. The `code` is the OTP to validate (usually entered by the user). The `suite` and `input` define the expected context in which the OTP should have been generated.

Returns true if the code is valid, false otherwise. An error is returned if decoding the secret fails or if validation encounters a critical issue.

package main

import (
	"fmt"
	"github.com/ja7ad/otp"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	suite := otp.MustRawSuite("OCRA-1:HOTP-SHA1-6:QN08")

	code, err := otp.GenerateOCRA(secret, suite, otp.OCRAInput{
		Challenge: []byte("12345678"),
	})
	if err != nil {
		panic(err)
	}

	ok, err := otp.ValidateOCRA(code, secret, suite, otp.OCRAInput{
		Challenge: []byte("12345678"),
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(ok)
}

func ValidateTOTP ¶

func ValidateTOTP(secret, code string, t time.Time, param *Param) (bool, error)

ValidateTOTP checks whether the given TOTP code is valid for the specified time and secret. It uses constant-time comparison to avoid timing attacks. Returns true if the code is valid, false otherwise. If param is nil, DefaultTOTPParam is used.

package main

import (
	"fmt"
	"github.com/ja7ad/otp"
	"time"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	t := time.Now()

	code, err := otp.GenerateTOTP(secret, t, otp.DefaultTOTPParam)
	if err != nil {
		panic(err)
	}

	fmt.Println(code)

	ok, err := otp.ValidateTOTP(secret, code, t, otp.DefaultTOTPParam)
	if err != nil {
		panic(err)
	}

	fmt.Println(ok)
}