totp

This example demonstrates how to generate a new secret key with default options and validate the passcode.

The generated key should be compatible with most TOTP authenticator apps.

package main

import (
	"fmt"
	"log"

	"github.com/KEINOS/go-totp/totp"
)

func main() {
	Issuer := "Example.com"            // name of the service
	AccountName := "[email protected]" // name of the user

	// Generate a new secret key with default options.
	// Compatible with most TOTP authenticator apps.
	key, err := totp.GenerateKey(Issuer, AccountName)
	if err != nil {
		log.Fatal(err)
	}

	// Print the default option values.
	fmt.Println("- Algorithm:", key.Options.Algorithm)
	fmt.Println("- Period:", key.Options.Period)
	fmt.Println("- Secret Size:", key.Options.SecretSize)
	fmt.Println("- Skew (time tolerance):", key.Options.Skew)
	fmt.Println("- Digits:", key.Options.Digits)

	// Generate 6 digits passcode (valid for 30 seconds)
	passcode, err := key.PassCode()
	if err != nil {
		log.Fatal(err)
	}

	// Validate the passcode
	if key.Validate(passcode) {
		fmt.Println("* Validation result: Passcode is valid")
	}
}

Output:

- Algorithm: SHA1
- Period: 30
- Secret Size: 128
- Skew (time tolerance): 1
- Digits: 6
* Validation result: Passcode is valid

This example demonstrates how to generate a new secret key with `GenerateKeyCustom`. But it is recommended to use the `GenerateKey` function with `With*` options.

package main

import (
	"fmt"
	"log"

	"github.com/KEINOS/go-totp/totp"
)

func main() {
	// Options to generate a new key. The secret will be generated randomly.
	opts := totp.Options{
		Issuer:      "Example.com",
		AccountName: "[email protected]",
		Algorithm:   totp.Algorithm("SHA1"), // Choices are: MD5, SHA1, SHA256 and SHA512
		Period:      60,                     // Validity period in seconds
		SecretSize:  20,                     // Secret key size in bytes
		Skew:        0,                      // Number of periods before or after the current time to allow.
		Digits:      totp.Digits(8),         // Choices are: 6 and 8
	}

	// Generate a new secret key
	key, err := totp.GenerateKeyCustom(opts)
	if err != nil {
		log.Fatal(err)
	}

	// Generate 8 digits passcode that are valid for 60 seconds (see options above)
	passcode, err := key.PassCode()
	if err != nil {
		log.Fatal(err)
	}

	// Validate the passcode
	if key.Validate(passcode) {
		fmt.Println("Passcode is valid")
	}
}

Output:

Passcode is valid

This example demonstrates how to generate a new secret key with custom options and validate the passcode.

Since most TOTP authenticator apps are based on SHA1 hashing algorithm to generate the passcode, this example is useful when you need to generate the passcode with a stronger hash algorithm such as SHA256 and SHA512.

package main

import (
	"fmt"
	"log"

	"github.com/KEINOS/go-totp/totp"
)

func main() {
	// Generate a new secret key with custom options
	Issuer := "Example.com"
	AccountName := "[email protected]"

	key, err := totp.GenerateKey(Issuer, AccountName,
		totp.WithAlgorithm(totp.Algorithm("SHA256")), // Algorithm for passcode generation (MD5, SHA1, SHA256 and SHA512)
		totp.WithPeriod(15),                          // Interval of the passcode validity
		totp.WithSecretSize(256),                     // Size of the TOTP secret key in bytes
		totp.WithSkew(5),                             // Number of periods as tolerance (+/-)
		totp.WithDigits(totp.DigitsEight),            // Number of digits for the passcode
	)
	if err != nil {
		log.Fatal(err)
	}

	// Generate 8 digits passcode (valid for 15 ± 5 seconds)
	passcode, err := key.PassCode()
	if err != nil {
		log.Fatal(err)
	}

	// Validate the passcode
	if key.Validate(passcode) {
		fmt.Println("Passcode is valid")
	}
}

Output:

Passcode is valid

This example demonstrates how to generate a new TOTP secret key from a shared secret of ECDH (Elliptic Curve Diffie-Hellman) key exchange.

Meaning that two parties can generate a common TOTP passcode by exchanging their ECDH public keys.

The aim of this functionality is to allow the user to generate a common but ephemeral secret value (the generated TOTP passcode) for additional security. Such as time-based salt for hashing, etc.

In this example, we pretend that Alice and Bob want to generate a common TOTP passcode for their communication. And they have exchanged their ECDH public keys securely with no-man-in-the-middle attack.

Let's see how Alice generates a common TOTP passcode between her and Bob!

package main

import (
	"crypto/ecdh"
	"crypto/rand"
	"fmt"
	"log"

	"github.com/KEINOS/go-totp/totp"
)

func main() {
	// ------------------------------------------------------------------------
	//  Pre-agreement between Alice and Bob.
	// ------------------------------------------------------------------------
	//  Both parties must use the same protocol (agreed options) so that the
	//  same shared secret is created and use it to generate a same TOTP
	//  passcode within the same time frame.

	// The curve type.
	commonCurve := ecdh.X25519()
	// A consistent and common context between the two parties.
	// It will be used as a salt-like value for the TOTP secret key derivation.
	commonCtx := "It can be any string but consistent between Alice and Bob."

	// ------------------------------------------------------------------------
	//  Generate a new ECDH keys for Alice and Bob
	// ------------------------------------------------------------------------
	//  We pretend that Alice and Bob have exchanged their ECDH public keys
	//  securely. In a real-world scenario, you must not expose your private
	//  key to the public by any means.

	generateECDHKeys := func(commonCurve ecdh.Curve) (*ecdh.PrivateKey, *ecdh.PublicKey) {
		priv, err := commonCurve.GenerateKey(rand.Reader)
		if err != nil {
			log.Fatal(err, "failed to generate ECDH private key")
		}

		return priv, priv.PublicKey()
	}

	ecdhPrivAlice, ecdhPubAlice := generateECDHKeys(commonCurve)
	ecdhPrivBob, ecdhPubBob := generateECDHKeys(commonCurve)

	// ------------------------------------------------------------------------
	//  Alice Side
	// ------------------------------------------------------------------------
	issuerAlice := "Example.com"            // name of the service
	accountNameAlice := "[email protected]" // name of the user

	totpKeyAlice, err := totp.GenerateKey(issuerAlice, accountNameAlice,
		// Use the ECDH shared secret between Alice and Bob as the base of the
		// TOTP secret key. A common and consistent context is required.
		//
		// The size of the shared ECDH secret is 32 bytes. The secret TOTP key
		// is therefore derived from this shared secret using the key derivation
		// function (KDF) set in the options to stretch up to the options.SecretSize.
		// The default KDF is BLAKE3.
		totp.WithECDH(ecdhPrivAlice, ecdhPubBob, commonCtx),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Alice generates 8 digits of TOTP passcode
	passcodeAlice, err := totpKeyAlice.PassCode()
	if err != nil {
		log.Fatal(err)
	}

	// ------------------------------------------------------------------------
	//  Bob Side
	// ------------------------------------------------------------------------
	issuerBob := "Example.com"
	accountNameBob := "[email protected]"

	totpKeyBob, err := totp.GenerateKey(issuerBob, accountNameBob,
		totp.WithECDH(ecdhPrivBob, ecdhPubAlice, commonCtx),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Bob generates 8 digits of TOTP passcode
	passcodeBob, err := totpKeyBob.PassCode()
	if err != nil {
		log.Fatal(err)
	}

	// ------------------------------------------------------------------------
	//  Validataion
	// ------------------------------------------------------------------------
	if passcodeAlice == passcodeBob {
		fmt.Println("* Validation result: Passcode matches")
	}
}

Output:

* Validation result: Passcode matches

This example demonstrates how to use a custom KDF (Key Derivation Function) that derives the TOTP secret key from the ECDH shared secret.

package main

import (
	"crypto/ecdh"
	"crypto/pbkdf2"
	"crypto/rand"
	"crypto/sha3"
	"fmt"
	"log"
	"math"

	"github.com/KEINOS/go-totp/totp"
	"github.com/pkg/errors"
)

func main() {
	// ------------------------------------------------------------------------
	//  Pre-agreement between Alice and Bob.
	// ------------------------------------------------------------------------
	commonCurve := ecdh.X25519()
	commonCtx := "arbitrary string but consistent between Alice and Bob"

	// Custom KDF (Key Derivation Function) for the TOTP secret key.
	//
	// This custom function uses PBKDF2 from the crypto/pbkdf2 package with
	// SHA3-256 and 4096 iterations. The "secret" is the ECDH shared secret.
	// "ctx" is used as the salt to derive the TOTP secret key, and "outLen"
	// is the desired length of the derived TOTP secret key.
	commonKDF := func(secret []byte, ctx []byte, outLen uint) ([]byte, error) {
		const iter = 4096

		// At least 8 bytes is recommended by the RFC.
		if len(ctx) < 8 {
			return nil, errors.New("context too short. PBKDF2 requires at least 8 bytes")
		}

		// Check for potential integer overflow during uint to int conversion
		if outLen == 0 || outLen > math.MaxInt {
			return nil, errors.New("output length is out of valid range for int conversion")
		}

		return pbkdf2.Key(sha3.New256, string(secret), ctx, iter, int(outLen))
	}

	// ------------------------------------------------------------------------
	//  Generate a new ECDH keys for Alice and Bob
	// ------------------------------------------------------------------------
	generateECDHKeys := func(paramCommon ecdh.Curve) (*ecdh.PrivateKey, *ecdh.PublicKey) {
		priv, err := paramCommon.GenerateKey(rand.Reader)
		if err != nil {
			log.Fatal(err, "failed to generate ECDH private key")
		}

		return priv, priv.PublicKey()
	}

	//  We pretend that Alice and Bob have exchanged their ECDH public keys
	ecdhPrivAlice, ecdhPubAlice := generateECDHKeys(commonCurve)
	ecdhPrivBob, ecdhPubBob := generateECDHKeys(commonCurve)

	// ------------------------------------------------------------------------
	//  Alice Side
	// ------------------------------------------------------------------------

	// Generate a new TOTP key for Alice using ECDH key and common context
	totpKeyAlice, err := totp.GenerateKey("Example.com", "[email protected]",
		totp.WithECDH(ecdhPrivAlice, ecdhPubBob, commonCtx),
		// Assign a custom function to derive the TOTP secret key from the ECDH
		// shared secret. If not set, totp.OptionKDFDefault will be used, which
		// is BLAKE3.
		totp.WithECDHKDF(commonKDF),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Alice generates 8 digits of TOTP passcode
	passcodeAlice, err := totpKeyAlice.PassCode()
	if err != nil {
		log.Fatal(err)
	}

	// ------------------------------------------------------------------------
	//  Bob Side
	// ------------------------------------------------------------------------

	// Generate a new TOTP key for Bob using ECDH key and common context
	totpKeyBob, err := totp.GenerateKey("Example.com", "[email protected]",
		totp.WithECDH(ecdhPrivBob, ecdhPubAlice, commonCtx),
		totp.WithECDHKDF(commonKDF),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Bob generates 8 digits of TOTP passcode
	passcodeBob, err := totpKeyBob.PassCode()
	if err != nil {
		log.Fatal(err)
	}

	// ------------------------------------------------------------------------
	//  Validataion
	// ------------------------------------------------------------------------
	if passcodeAlice == passcodeBob {
		fmt.Println("* Validation result: Passcode matches")
	}
}

Output:

* Validation result: Passcode matches

As of v0.3.0, the "totp.Key.URI()" method returns the URI string with the "secret" query parameter first by default.

This is due to avoid a niche reading error bug of Google Authenticator (#55). QR Code generated with other libraries that uses an old encoding method, Google Authenticator fails to read if the URI in the QR Code ends with a "secret" query parameter.

package main

import (
	"fmt"
	"log"

	"github.com/KEINOS/go-totp/totp"
)

func main() {
	// note the order of the query parameters
	origin := "otpauth://totp/Example.com:[email protected]?algorithm=SHA1&" +
		"period=60&issuer=Example.com&digits=12&" +
		"secret=QF7N673VMVHYWATKICRUA7V5MUGFG3Z3"

	key, err := totp.GenKeyFromURI(origin)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(key.URI())
}

Output:

otpauth://totp/Example.com:[email protected]?secret=QF7N673VMVHYWATKICRUA7V5MUGFG3Z3&algorithm=SHA1&digits=12&issuer=Example.com&period=60