diff --git a/README.md b/README.md index 23596bc..3360095 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # go-totp [![go1.22+](https://img.shields.io/badge/Go-1.22+-blue?logo=go)](https://github.com/KEINOS/go-totp/blob/main/.github/workflows/unit-tests.yml#L81 "Supported versions") -[![Go Reference](https://pkg.go.dev/badge/github.com/KEINOS/go-totp.svg)](https://pkg.go.dev/github.com/KEINOS/go-totp/ "View document") +[![Go Reference](https://pkg.go.dev/badge/github.com/KEINOS/go-totp.svg)](https://pkg.go.dev/github.com/KEINOS/go-totp/totp "View document") `go-totp` is a simple Go package to implement [Timebased-One-Time-Password](https://en.wikipedia.org/wiki/Time-based_one-time_password) authentication functionality, a.k.a. `TOTP`, to the Go app. diff --git a/totp/algorithm.go b/totp/algorithm.go index 53129d8..24ae768 100644 --- a/totp/algorithm.go +++ b/totp/algorithm.go @@ -11,15 +11,19 @@ import ( // Type: Algorithm // ---------------------------------------------------------------------------- -// Algorithm is a string that represents the algorithm used for HMAC. +// Algorithm is a string that represents the algorithm used to generate the +// passcode (for HMAC). type Algorithm string // ---------------------------------------------------------------------------- // Constructor // ---------------------------------------------------------------------------- -// NewAlgorithmStr creates a new Algorithm object from a string. -// Choices of algo are: MD5, SHA1, SHA256 and SHA512. +// NewAlgorithmStr creates a new Algorithm object from a string that is used to +// generate the passcode. +// Choices of algo are: +// +// MD5, SHA1, SHA256 and SHA512. func NewAlgorithmStr(algo string) (Algorithm, error) { const ( cMD5 = "MD5" @@ -39,6 +43,9 @@ func NewAlgorithmStr(algo string) (Algorithm, error) { } // NewAlgorithmID creates a new Algorithm object from an int. +// +// It is not an usual way to create an Algorithm object. It is used to convert +// the ID of the algorithm to the Algorithm object for checking purposes. func NewAlgorithmID(algoID int) (Algorithm, error) { const ( cMD5 = "MD5" diff --git a/totp/example_test.go b/totp/example_test.go index d5dabd5..302e208 100644 --- a/totp/example_test.go +++ b/totp/example_test.go @@ -16,6 +16,10 @@ import ( // Package Examples // ============================================================================ +// 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. func Example() { Issuer := "Example.com" // name of the service AccountName := "alice@example.com" // name of the user @@ -54,12 +58,19 @@ func Example() { // * Validation result: 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. func Example_custom() { // Generate a new secret key with custom options Issuer := "Example.com" AccountName := "alice@example.com" key, err := totp.GenerateKey(Issuer, AccountName, + // Algorithm choices are: MD5, SHA1, SHA256 and SHA512. totp.WithAlgorithm(totp.Algorithm("SHA256")), totp.WithPeriod(15), totp.WithSecretSize(256), @@ -121,7 +132,8 @@ func Example_advanced() { // ============================================================================ func ExampleAlgorithm() { - // Create a new Algorithm object from a string. Choices are: + // Create a new Algorithm object from a string for passcode generation. + // Choices are: // MD5, SHA1, SHA256 and SHA512. algo, err := totp.NewAlgorithmStr("SHA512") if err != nil { @@ -139,7 +151,7 @@ func ExampleAlgorithm() { } func ExampleAlgorithm_IsSupported() { - // Set unsupported algorithm + // Set unsupported algorithm for passcode generation algo := totp.Algorithm("BLAKE3") // Check if the algorithm is supported diff --git a/totp/totp.go b/totp/totp.go index 7748774..9adbc79 100644 --- a/totp/totp.go +++ b/totp/totp.go @@ -4,6 +4,16 @@ authentication functionality, a.k.a. `TOTP`, to the Go app. Optionally, it supports ECDH key agreement protocol to share the same secret key between two parties. + +```shellsession +# Install the module +go get github.com/KEINOS/go-totp +``` + +```go +// Use the package +import "github.com/KEINOS/go-totp/totp" +``` */ package totp