totp

package main

import (
	"fmt"
	"log"

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

func main() {
	Issuer := "Example.com"            // name of the service
	AccountName := "alice@example.com" // 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

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: "alice@example.com",
		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

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 := "alice@example.com"

	key, err := totp.GenerateKey(Issuer, AccountName,
		totp.WithAlgorithm(totp.Algorithm("SHA256")),
		totp.WithPeriod(15),
		totp.WithSecretSize(256),
		totp.WithSkew(5),
		totp.WithDigits(totp.DigitsEight),
	)
	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!

//nolint:goconst // allow occurrences for readability
package main

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

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

// 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!
//
//nolint:exhaustruct,funlen // allow them for readability
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 := "example.com alice@example.com bob@example.com TOTP secret v1"
	// Common options for the TOTP secret key generation.
	commonOpts := totp.Options{
		Algorithm:  totp.Algorithm("SHA512"), // Algorithm for passcode generation
		Digits:     totp.DigitsEight,         // Number of digits for the passcode
		Period:     60 * 30,                  // Interval of the passcode validity
		SecretSize: 32,                       // Size of the secret key in bytes
		Skew:       1,                        // Number of periods as tolerance (+/-)
	}

	// ------------------------------------------------------------------------
	//  Key exchange between 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.
	alicePriv, alicePub := testGetECDHKeysForAlice(commonCurve)
	bobPriv, bobPub := testGetECDHKeysForBob(commonCurve)

	// ------------------------------------------------------------------------
	//  Generate a new TOTP key for Alice
	// ------------------------------------------------------------------------
	Issuer := "Example.com"            // name of the service
	AccountName := "alice@example.com" // name of the user

	key, err := totp.GenerateKey(Issuer, AccountName,
		// 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 generated
		// from the hash value of this shared secret and uses the shared context
		// up to the length of the "totp.WithSecretSize" option.
		// (FYI, the hash algorithm is BLAKE3).
		totp.WithECDH(alicePriv, bobPub, commonCtx),
		// Other options can be set as well. But they must be the same between
		// the two parties.
		totp.WithAlgorithm(commonOpts.Algorithm),
		totp.WithDigits(commonOpts.Digits),
		totp.WithPeriod(commonOpts.Period),
		totp.WithSecretSize(commonOpts.SecretSize),
		totp.WithSkew(commonOpts.Skew),
	)
	if err != nil {
		log.Fatal(err)
	}

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

	// Bob validates the passcode
	result := letBobValidate(passcode, bobPriv, alicePub)
	fmt.Println(result)
}

//nolint:exhaustruct // field totp.Options.AccountName is missing but leave it as is for simplicity
func letBobValidate(alicePasscode string, bobPriv *ecdh.PrivateKey, alicePub *ecdh.PublicKey) string {
	// Pre-agreement between Alice and Bob.
	commonCtx := "example.com alice@example.com bob@example.com TOTP secret v1"
	commonOpts := totp.Options{
		Algorithm:  totp.Algorithm("SHA512"), // Algorithm for passcode generation
		Digits:     totp.DigitsEight,         // Number of digits for the passcode
		Period:     60 * 30,                  // Interval of the passcode validity
		SecretSize: 32,                       // Size of the secret key in bytes
		Skew:       1,                        // Number of periods as tolerance (+/-)
	}

	// ------------------------------------------------------------------------
	//  Generate a new TOTP key for Bob
	// ------------------------------------------------------------------------
	Issuer := "Example.com"
	AccountName := "bob@example.com"

	key, err := totp.GenerateKey(Issuer, AccountName,
		totp.WithECDH(bobPriv, alicePub, commonCtx),
		totp.WithPeriod(commonOpts.Period),
		totp.WithAlgorithm(commonOpts.Algorithm),
		totp.WithSecretSize(commonOpts.SecretSize),
		totp.WithSkew(commonOpts.Skew),
		totp.WithDigits(commonOpts.Digits),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Bob validates the passcode
	if key.Validate(alicePasscode) {
		return "* Validation result: Passcode is valid"
	}

	return "* Validation result: Passcode is invalid"
}

// This is a dummy function to return Alice's ECDH private key.
// In a real-world scenario, you would generate this key securely.
//
// paramCommon is the curve type agreed between Alice and Bob.
func testGetECDHKeysForAlice(paramCommon ecdh.Curve) (*ecdh.PrivateKey, *ecdh.PublicKey) {
	alicePriv, err := paramCommon.GenerateKey(rand.Reader)
	if err != nil {
		log.Fatal(err, "failed to generate Alice's ECDH private key for example")
	}

	return alicePriv, alicePriv.PublicKey()
}

// This is a dummy function to return Bob's ECDH public key.
// In a real-world scenario, you would obtain this key securely.
//
// paramCommon is the curve type agreed between Alice and Bob.
func testGetECDHKeysForBob(paramCommon ecdh.Curve) (*ecdh.PrivateKey, *ecdh.PublicKey) {
	bobPriv, err := paramCommon.GenerateKey(rand.Reader)
	if err != nil {
		log.Fatal(err, "failed to generate Alice's ECDH private key for example")
	}

	return bobPriv, bobPriv.PublicKey()
}

Output:

* Validation result: Passcode is valid