Import twofactor.

git-subtree-dir: twofactor
git-subtree-mainline: 4dc135cfe0
git-subtree-split: c999bf35b0

CHANGELOG

@@ -1,5 +1,21 @@
 CHANGELOG
 
+v1.12.0 - 2025-11-16
+
+Added
+- twofactor: the github.com/kisom/twofactor repo has been subtree'd
+  into this repo.
+
+v1.11.2 - 2025-11-16
+
+Changed
+- cmd/ski, cmd/csrpubdump, cmd/tlskeypair: centralize
+  certificate/private-key/CSR parsing by reusing certlib helpers.
+  This reduces duplication and improves consistency across commands.
+- csr: CSR parsing in the above commands now uses certlib.ParseCSR,
+  which verifies CSR signatures (behavioral hardening compared to
+  prior parsing without signature verification).
+
 v1.11.1 - 2025-11-16
 
 Changed

README.md

@@ -2,39 +2,52 @@ GOUTILS
 
 This is a collection of small utility code I've written in Go; the `cmd/`
 directory has a number of command-line utilities. Rather than keep all
-of these in superfluous repositories of their own, or rewriting them
+of these in superfluous repositories of their own or rewriting them
 for each project, I'm putting them here.
 
-The project can be built with the standard Go tooling, or it can be built
-with Bazel.
+The project can be built with the standard Go tooling.
 
 Contents:
 
     ahash/          Provides hashes from string algorithm specifiers.
     assert/         Error handling, assertion-style.
     backoff/        Implementation of an intelligent backoff strategy.
+    cache/          Implementations of various caches.
+        lru/        Least-recently-used cache.
+        mru/        Most-recently-used cache.
+    certlib/        Library for working with TLS certificates.
     cmd/
         atping/     Automated TCP ping, meant for putting in cronjobs.
-        certchain/  Display the certificate chain from a
-                    TLS connection.
+        ca-signed/  Validate whether a certificate is signed by a CA.
+        cert-bundler/
+                    Create certificate bundles from a source of PEM
+                    certificates.
+        cert-revcheck/
+                    Check whether a certificate has been revoked or is
+                    expired.
+        certchain/  Display the certificate chain from a TLS connection.
         certdump/   Dump certificate information.
         certexpiry/ Print a list of certificate subjects and expiry times
                     or warn about certificates expiring within a certain
                     window.
-        certverify/ Verify a TLS X.509 certificate, optionally printing
+        certverify/ Verify a TLS X.509 certificate file, optionally printing
                     the time to expiry and checking for revocations.
         clustersh/  Run commands or transfer files across multiple
                     servers via SSH.
-        cruntar/    Untar an archive with hard links, copying instead of
+        cruntar/    (Un)tar an archive with hard links, copying instead of
                     linking.
         csrpubdump/ Dump the public key from an X.509 certificate request.
         data_sync/  Sync the user's homedir to external storage.
         diskimg/    Write a disk image to a device.
+        dumpbytes/  Dump the contents of a file as hex bytes, printing it as
+                    a Go []byte literal.
         eig/        EEPROM image generator.
         fragment/   Print a fragment of a file.
+        host/       Go imlpementation of the host(1) command.
         jlp/        JSON linter/prettifier.
         kgz/        Custom gzip compressor / decompressor that handles 99%
                     of my use cases.
+        minmax/     Generate a minmax code for use in uLisp.
         parts/      Simple parts database management for my collection of
                     electronic components.
         pem2bin/    Dump the binary body of a PEM-encoded block.
@@ -44,41 +57,45 @@ Contents:
                     in a bundle.
         renfnv/     Rename a file to base32-encoded 64-bit FNV-1a hash.
         rhash/      Compute the digest of remote files.
+        rolldie/    Roll some dice.
         showimp/    List the external (e.g. non-stdlib and outside the
                     current working directory) imports for a Go file.
         ski         Display the SKI for PEM-encoded TLS material.
         sprox/      Simple TCP proxy.
-        stealchain/ Dump the verified chain from a TLS
-                    connection to a server.
-        stealchain- Dump the verified chain from a TLS
-          server/   connection from a client.
+        stealchain/ Dump the verified chain from a TLS connection to a
+                    server.
+        stealchain-server/
+                    Dump the verified chain from a TLS connection from
+                    from a client.
         subjhash/   Print or match subject info from a certificate.
+        tlsinfo/    Print information about a TLS connection (the TLS version
+                    and cipher suite).
         tlskeypair/ Check whether a TLS certificate and key file match.
         utc/        Convert times to UTC.
         yamll/      A small YAML linter.
+        zsearch/    Search for a string in directory of gzipped files.
     config/         A simple global configuration system where configuration
                     data is pulled from a file or an environment variable
                     transparently.
+        iniconf/    A simple INI-style configuration system.
     dbg/            A debug printer.
     die/            Death of a program.
     fileutil/       Common file functions.
     lib/            Commonly-useful functions for writing Go programs.
+    log/            A syslog library.
     logging/        A logging library.
     mwc/            MultiwriteCloser implementation.
-    rand/           Utilities for working with math/rand.
     sbuf/           A byte buffer that can be wiped.
     seekbuf/        A read-seekable byte buffer.
     syslog/         Syslog-type logging.
     tee/            Emulate tee(1)'s functionality in io.Writers.
     testio/         Various I/O utilities useful during testing.
-    testutil/       Various utility functions useful during testing.
-
+	twofactor/      Two-factor authentication.
 
 Each program should have a small README in the directory with more
 information.
 
-All code here is licensed under the ISC license.
-
+All code here is licensed under the Apache 2.0 license.
 
 Error handling
 --------------
@@ -99,7 +116,7 @@ Examples:
 ```
 cert, err := certlib.LoadCertificate(path)
 if err != nil {
-    // sentinel match
+    // sentinel match:
     if errors.Is(err, certerr.ErrEmptyCertificate) {
         // handle empty input
     }
@@ -116,5 +133,3 @@ if err != nil {
     }
 }
 ```
-
-Avoid including sensitive data (keys, passwords, tokens) in error messages.

cmd/csrpubdump/main.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"os"
 
+	"git.wntrmute.dev/kyle/goutils/certlib"
 	"git.wntrmute.dev/kyle/goutils/die"
 )
 
@@ -19,14 +20,7 @@ func main() {
 		in, err := os.ReadFile(fileName)
 		die.If(err)
 
-		if p, _ := pem.Decode(in); p != nil {
-			if p.Type != "CERTIFICATE REQUEST" {
-				die.With("INVALID FILE TYPE")
-			}
-			in = p.Bytes
-		}
-
-		csr, err := x509.ParseCertificateRequest(in)
+		csr, _, err := certlib.ParseCSR(in)
 		die.If(err)
 
 		out, err := x509.MarshalPKIXPublicKey(csr.PublicKey)

cmd/ski/main.go

@@ -2,7 +2,6 @@ package main
 
 import (
 	"bytes"
-	"crypto"
 	"crypto/ecdsa"
 	"crypto/rsa"
 	"crypto/sha1" // #nosec G505
@@ -16,6 +15,7 @@ import (
 	"os"
 	"strings"
 
+	"git.wntrmute.dev/kyle/goutils/certlib"
 	"git.wntrmute.dev/kyle/goutils/die"
 	"git.wntrmute.dev/kyle/goutils/lib"
 )
@@ -83,28 +83,19 @@ func parse(path string) ([]byte, string, string) {
 }
 
 func parseKey(data []byte) ([]byte, string) {
-	privInterface, err := x509.ParsePKCS8PrivateKey(data)
+	priv, err := certlib.ParsePrivateKeyDER(data)
 	if err != nil {
-		privInterface, err = x509.ParsePKCS1PrivateKey(data)
-		if err != nil {
-			privInterface, err = x509.ParseECPrivateKey(data)
-			if err != nil {
-				die.With("couldn't parse private key.")
-			}
-		}
+		die.If(err)
 	}
 
-	var priv crypto.Signer
 	var kt string
-	switch p := privInterface.(type) {
-	case *rsa.PrivateKey:
-		priv = p
+	switch priv.Public().(type) {
+	case *rsa.PublicKey:
 		kt = keyTypeRSA
-	case *ecdsa.PrivateKey:
-		priv = p
+	case *ecdsa.PublicKey:
 		kt = keyTypeECDSA
 	default:
-		die.With("unknown private key type %T", privInterface)
+		die.With("unknown private key type %T", priv)
 	}
 
 	public, err := x509.MarshalPKIXPublicKey(priv.Public())
@@ -134,7 +125,8 @@ func parseCertificate(data []byte) ([]byte, string) {
 }
 
 func parseCSR(data []byte) ([]byte, string) {
-	csr, err := x509.ParseCertificateRequest(data)
+	// Use certlib to support both PEM and DER and to centralize validation.
+	csr, _, err := certlib.ParseCSR(data)
 	die.If(err)
 
 	pub := csr.PublicKey

cmd/tlskeypair/main.go

@@ -13,6 +13,7 @@ import (
 	"fmt"
 	"os"
 
+	"git.wntrmute.dev/kyle/goutils/certlib"
 	"git.wntrmute.dev/kyle/goutils/die"
 )
 
@@ -124,34 +125,14 @@ func loadKey(path string) (crypto.Signer, error) {
 	}
 
 	in = bytes.TrimSpace(in)
-	p, _ := pem.Decode(in)
-	if p != nil {
+	if p, _ := pem.Decode(in); p != nil {
 		if !validPEMs[p.Type] {
 			return nil, errors.New("invalid private key file type " + p.Type)
 		}
-		in = p.Bytes
+		return certlib.ParsePrivateKeyPEM(in)
 	}
 
-	priv, err := x509.ParsePKCS8PrivateKey(in)
-	if err != nil {
-		priv, err = x509.ParsePKCS1PrivateKey(in)
-		if err != nil {
-			priv, err = x509.ParseECPrivateKey(in)
-			if err != nil {
-				return nil, err
-			}
-		}
-	}
-
-	switch p := priv.(type) {
-	case *rsa.PrivateKey:
-		return p, nil
-	case *ecdsa.PrivateKey:
-		return p, nil
-	default:
-		// should never reach here
-		return nil, errors.New("invalid private key")
-	}
+	return certlib.ParsePrivateKeyDER(in)
 }
 
 func main() {

twofactor/.circleci/config.yml

@@ -0,0 +1,42 @@
+# Use the latest 2.1 version of CircleCI pipeline process engine.
+# See: https://circleci.com/docs/2.0/configuration-reference
+version: 2.1
+
+# Define a job to be invoked later in a workflow.
+# See: https://circleci.com/docs/2.0/configuration-reference/#jobs
+jobs:
+  testbuild:
+    working_directory: ~/repo
+    # Specify the execution environment. You can specify an image from Dockerhub or use one of our Convenience Images from CircleCI's Developer Hub.
+    # See: https://circleci.com/docs/2.0/configuration-reference/#docker-machine-macos-windows-executor
+    docker:
+      - image: cimg/go:1.22.2
+    # Add steps to the job
+    # See: https://circleci.com/docs/2.0/configuration-reference/#steps
+    steps:
+      - checkout
+      - restore_cache:
+          keys:
+            - go-mod-v4-{{ checksum "go.sum" }}
+      - run:
+          name: Install Dependencies
+          command: go mod download
+      - save_cache:
+          key: go-mod-v4-{{ checksum "go.sum" }}
+          paths:
+            - "/go/pkg/mod"
+      - run:
+          name: Run tests
+          command: go test ./...
+      - run:
+          name: Run build
+          command: go build ./...
+      - store_test_results:
+          path: /tmp/test-reports
+
+# Invoke jobs via workflows
+# See: https://circleci.com/docs/2.0/configuration-reference/#workflows
+workflows:
+  testbuild:
+    jobs:
+      - testbuild

twofactor/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2017 Kyle Isom <kyle@imap.cc>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

twofactor/README.md

@@ -0,0 +1,33 @@
+## `twofactor`
+
+[![GoDoc](https://godoc.org/github.com/gokyle/twofactor?status.svg)](https://godoc.org/github.com/gokyle/twofactor)
+
+
+### Author
+
+`twofactor` was written by Kyle Isom <kyle@tyrfingr.is>.
+
+
+### License
+
+```
+Copyright (c) 2017 Kyle Isom <kyle@imap.cc>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

twofactor/doc.go

@@ -0,0 +1,5 @@
+// twofactor implements two-factor authentication.
+//
+// Currently supported are RFC 4226 HOTP one-time passwords and
+// RFC 6238 TOTP SHA-1 one-time passwords.
+package twofactor

twofactor/go.mod

@@ -0,0 +1,8 @@
+module github.com/gokyle/twofactor
+
+go 1.14
+
+require (
+	github.com/benbjohnson/clock v0.0.0-20161215174838-7dc76406b6d3
+	rsc.io/qr v0.1.0
+)

twofactor/go.sum

@@ -0,0 +1,4 @@
+github.com/benbjohnson/clock v0.0.0-20161215174838-7dc76406b6d3 h1:wOysYcIdqv3WnvwqFFzrYCFALPED7qkUGaLXu359GSc=
+github.com/benbjohnson/clock v0.0.0-20161215174838-7dc76406b6d3/go.mod h1:UMqtWQTnOe4byzwe7Zhwh8f8s+36uszN51sJrSIZlTE=
+rsc.io/qr v0.1.0 h1:M/sAxsU2J5mlQ4W84Bxga2EgdQqOaAliipcjPmMUM5Q=
+rsc.io/qr v0.1.0/go.mod h1:IF+uZjkb9fqyeF/4tlBoynqmQxUoPfWEKh921coOuXs=

twofactor/hotp.go

@@ -0,0 +1,103 @@
+package twofactor
+
+import (
+	"crypto"
+	"crypto/sha1"
+	"encoding/base32"
+	"io"
+	"net/url"
+	"strconv"
+	"strings"
+)
+
+// HOTP represents an RFC-4226 Hash-based One Time Password instance.
+type HOTP struct {
+	*OATH
+}
+
+// Type returns OATH_HOTP.
+func (otp *HOTP) Type() Type {
+	return OATH_HOTP
+}
+
+// NewHOTP takes the key, the initial counter value, and the number
+// of digits (typically 6 or 8) and returns a new HOTP instance.
+func NewHOTP(key []byte, counter uint64, digits int) *HOTP {
+	return &HOTP{
+		OATH: &OATH{
+			key:     key,
+			counter: counter,
+			size:    digits,
+			hash:    sha1.New,
+			algo:    crypto.SHA1,
+		},
+	}
+}
+
+// OTP returns the next OTP and increments the counter.
+func (otp *HOTP) OTP() string {
+	code := otp.OATH.OTP(otp.counter)
+	otp.counter++
+	return code
+}
+
+// URL returns an HOTP URL (i.e. for putting in a QR code).
+func (otp *HOTP) URL(label string) string {
+	return otp.OATH.URL(otp.Type(), label)
+}
+
+// SetProvider sets up the provider component of the OTP URL.
+func (otp *HOTP) SetProvider(provider string) {
+	otp.provider = provider
+}
+
+// GenerateGoogleHOTP generates a new HOTP instance as used by
+// Google Authenticator.
+func GenerateGoogleHOTP() *HOTP {
+	key := make([]byte, sha1.Size)
+	if _, err := io.ReadFull(PRNG, key); err != nil {
+		return nil
+	}
+	return NewHOTP(key, 0, 6)
+}
+
+func hotpFromURL(u *url.URL) (*HOTP, string, error) {
+	label := u.Path[1:]
+	v := u.Query()
+
+	secret := strings.ToUpper(v.Get("secret"))
+	if secret == "" {
+		return nil, "", ErrInvalidURL
+	}
+
+	var digits = 6
+	if sdigit := v.Get("digits"); sdigit != "" {
+		tmpDigits, err := strconv.ParseInt(sdigit, 10, 8)
+		if err != nil {
+			return nil, "", err
+		}
+		digits = int(tmpDigits)
+	}
+
+	var counter uint64 = 0
+	if scounter := v.Get("counter"); scounter != "" {
+		var err error
+		counter, err = strconv.ParseUint(scounter, 10, 64)
+		if err != nil {
+			return nil, "", err
+		}
+	}
+
+	key, err := base32.StdEncoding.DecodeString(Pad(secret))
+	if err != nil {
+		// assume secret isn't base32 encoded
+		key = []byte(secret)
+	}
+	otp := NewHOTP(key, counter, digits)
+	return otp, label, nil
+}
+
+// QR generates a new QR code for the HOTP.
+func (otp *HOTP) QR(label string) ([]byte, error) {
+	return otp.OATH.QR(otp.Type(), label)
+}

twofactor/hotp_test.go

@@ -0,0 +1,64 @@
+package twofactor
+
+import (
+	"fmt"
+	"testing"
+)
+
+var testKey = []byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}
+
+var rfcHotpKey = []byte("12345678901234567890")
+var rfcHotpExpected = []string{
+	"755224",
+	"287082",
+	"359152",
+	"969429",
+	"338314",
+	"254676",
+	"287922",
+	"162583",
+	"399871",
+	"520489",
+}
+
+// This test runs through the test cases presented in the RFC, and
+// ensures that this implementation is in compliance.
+func TestHotpRFC(t *testing.T) {
+	otp := NewHOTP(rfcHotpKey, 0, 6)
+	for i := 0; i < len(rfcHotpExpected); i++ {
+		if otp.Counter() != uint64(i) {
+			fmt.Printf("twofactor: invalid counter (should be %d, is %d",
+				i, otp.Counter())
+			t.FailNow()
+		}
+		code := otp.OTP()
+		if code == "" {
+			fmt.Printf("twofactor: failed to produce an OTP\n")
+			t.FailNow()
+		} else if code != rfcHotpExpected[i] {
+			fmt.Printf("twofactor: invalid OTP\n")
+			fmt.Printf("\tExpected: %s\n", rfcHotpExpected[i])
+			fmt.Printf("\t  Actual: %s\n", code)
+			fmt.Printf("\t Counter: %d\n", otp.counter)
+			t.FailNow()
+		}
+	}
+}
+
+// This test uses a different key than the test cases in the RFC,
+// but runs through the same test cases to ensure that they fail as
+// expected.
+func TestHotpBadRFC(t *testing.T) {
+	otp := NewHOTP(testKey, 0, 6)
+	for i := 0; i < len(rfcHotpExpected); i++ {
+		code := otp.OTP()
+		switch code {
+		case "":
+			fmt.Printf("twofactor: failed to produce an OTP\n")
+			t.FailNow()
+		case rfcHotpExpected[i]:
+			fmt.Printf("twofactor: should not have received a valid OTP\n")
+			t.FailNow()
+		}
+	}
+}

twofactor/oath.go

@@ -0,0 +1,150 @@
+package twofactor
+
+import (
+	"crypto"
+	"crypto/hmac"
+	"encoding/base32"
+	"encoding/binary"
+	"fmt"
+	"hash"
+	"net/url"
+
+	"rsc.io/qr"
+)
+
+const defaultSize = 6
+
+// OATH provides a baseline structure for the two OATH algorithms.
+type OATH struct {
+	key      []byte
+	counter  uint64
+	size     int
+	hash     func() hash.Hash
+	algo     crypto.Hash
+	provider string
+}
+
+// Size returns the output size (in characters) of the password.
+func (o OATH) Size() int {
+	return o.size
+}
+
+// Counter returns the OATH token's counter.
+func (o OATH) Counter() uint64 {
+	return o.counter
+}
+
+// SetCounter updates the OATH token's counter to a new value.
+func (o *OATH) SetCounter(counter uint64) {
+	o.counter = counter
+}
+
+// Key returns the token's secret key.
+func (o OATH) Key() []byte {
+	return o.key[:]
+}
+
+// Hash returns the token's hash function.
+func (o OATH) Hash() func() hash.Hash {
+	return o.hash
+}
+
+// URL constructs a URL appropriate for the token (i.e. for use in a
+// QR code).
+func (o OATH) URL(t Type, label string) string {
+	secret := base32.StdEncoding.EncodeToString(o.key)
+	u := url.URL{}
+	v := url.Values{}
+	u.Scheme = "otpauth"
+	switch t {
+	case OATH_HOTP:
+		u.Host = "hotp"
+	case OATH_TOTP:
+		u.Host = "totp"
+	}
+	u.Path = label
+	v.Add("secret", secret)
+	if o.Counter() != 0 && t == OATH_HOTP {
+		v.Add("counter", fmt.Sprintf("%d", o.Counter()))
+	}
+	if o.Size() != defaultSize {
+		v.Add("digits", fmt.Sprintf("%d", o.Size()))
+	}
+
+	switch o.algo {
+	case crypto.SHA256:
+		v.Add("algorithm", "SHA256")
+	case crypto.SHA512:
+		v.Add("algorithm", "SHA512")
+	}
+
+	if o.provider != "" {
+		v.Add("provider", o.provider)
+	}
+
+	u.RawQuery = v.Encode()
+	return u.String()
+
+}
+
+var digits = []int64{
+	0:  1,
+	1:  10,
+	2:  100,
+	3:  1000,
+	4:  10000,
+	5:  100000,
+	6:  1000000,
+	7:  10000000,
+	8:  100000000,
+	9:  1000000000,
+	10: 10000000000,
+}
+
+// The top-level type should provide a counter; for example, HOTP
+// will provide the counter directly while TOTP will provide the
+// time-stepped counter.
+func (o OATH) OTP(counter uint64) string {
+	var ctr [8]byte
+	binary.BigEndian.PutUint64(ctr[:], counter)
+
+	var mod int64 = 1
+	if len(digits) > o.size {
+		for i := 1; i <= o.size; i++ {
+			mod *= 10
+		}
+	} else {
+		mod = digits[o.size]
+	}
+
+	h := hmac.New(o.hash, o.key)
+	h.Write(ctr[:])
+	dt := truncate(h.Sum(nil)) % mod
+	fmtStr := fmt.Sprintf("%%0%dd", o.size)
+	return fmt.Sprintf(fmtStr, dt)
+}
+
+// truncate contains the DT function from the RFC; this is used to
+// deterministically select a sequence of 4 bytes from the HMAC
+// counter hash.
+func truncate(in []byte) int64 {
+	offset := int(in[len(in)-1] & 0xF)
+	p := in[offset : offset+4]
+	var binCode int32
+	binCode = int32((p[0] & 0x7f)) << 24
+	binCode += int32((p[1] & 0xff)) << 16
+	binCode += int32((p[2] & 0xff)) << 8
+	binCode += int32((p[3] & 0xff))
+	return int64(binCode) & 0x7FFFFFFF
+}
+
+// QR generates a byte slice containing the a QR code encoded as a
+// PNG with level Q error correction.
+func (o OATH) QR(t Type, label string) ([]byte, error) {
+	u := o.URL(t, label)
+	code, err := qr.Encode(u, qr.Q)
+	if err != nil {
+		return nil, err
+	}
+	return code.PNG(), nil
+}

twofactor/oath_test.go

@@ -0,0 +1,30 @@
+package twofactor
+
+import (
+	"fmt"
+	"testing"
+)
+
+var sha1Hmac = []byte{
+	0x1f, 0x86, 0x98, 0x69, 0x0e,
+	0x02, 0xca, 0x16, 0x61, 0x85,
+	0x50, 0xef, 0x7f, 0x19, 0xda,
+	0x8e, 0x94, 0x5b, 0x55, 0x5a,
+}
+
+var truncExpect int64 = 0x50ef7f19
+
+// This test runs through the truncation example given in the RFC.
+func TestTruncate(t *testing.T) {
+	if result := truncate(sha1Hmac); result != truncExpect {
+		fmt.Printf("hotp: expected truncate -> %d, saw %d\n",
+			truncExpect, result)
+		t.FailNow()
+	}
+
+	sha1Hmac[19]++
+	if result := truncate(sha1Hmac); result == truncExpect {
+		fmt.Println("hotp: expected truncation to fail")
+		t.FailNow()
+	}
+}

twofactor/otp.go

@@ -0,0 +1,86 @@
+package twofactor
+
+import (
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"hash"
+	"net/url"
+)
+
+type Type uint
+
+const (
+	OATH_HOTP = iota
+	OATH_TOTP
+)
+
+// PRNG is an io.Reader that provides a cryptographically secure
+// random byte stream.
+var PRNG = rand.Reader
+
+var (
+	ErrInvalidURL  = errors.New("twofactor: invalid URL")
+	ErrInvalidAlgo = errors.New("twofactor: invalid algorithm")
+)
+
+// Type OTP represents a one-time password token -- whether a
+// software taken (as in the case of Google Authenticator) or a
+// hardware token (as in the case of a YubiKey).
+type OTP interface {
+	// Returns the current counter value; the meaning of the
+	// returned value is algorithm-specific.
+	Counter() uint64
+
+	// Set the counter to a specific value.
+	SetCounter(uint64)
+
+	// the secret key contained in the OTP
+	Key() []byte
+
+	// generate a new OTP
+	OTP() string
+
+	// the output size of the OTP
+	Size() int
+
+	// the hash function used by the OTP
+	Hash() func() hash.Hash
+
+	// Returns the type of this OTP.
+	Type() Type
+}
+
+func otpString(otp OTP) string {
+	var typeName string
+	switch otp.Type() {
+	case OATH_HOTP:
+		typeName = "OATH-HOTP"
+	case OATH_TOTP:
+		typeName = "OATH-TOTP"
+	default:
+		typeName = "UNKNOWN"
+	}
+	return fmt.Sprintf("%s, %d", typeName, otp.Size())
+}
+
+// FromURL constructs a new OTP token from a URL string.
+func FromURL(URL string) (OTP, string, error) {
+	u, err := url.Parse(URL)
+	if err != nil {
+		return nil, "", err
+	}
+
+	if u.Scheme != "otpauth" {
+		return nil, "", ErrInvalidURL
+	}
+
+	switch u.Host {
+	case "totp":
+		return totpFromURL(u)
+	case "hotp":
+		return hotpFromURL(u)
+	default:
+		return nil, "", ErrInvalidURL
+	}
+}

twofactor/otp_test.go

@@ -0,0 +1,136 @@
+package twofactor
+
+import (
+	"fmt"
+	"io"
+	"testing"
+)
+
+func TestHOTPString(t *testing.T) {
+	hotp := NewHOTP(nil, 0, 6)
+	hotpString := otpString(hotp)
+	if hotpString != "OATH-HOTP, 6" {
+		fmt.Println("twofactor: invalid OTP string")
+		t.FailNow()
+	}
+}
+
+// This test generates a new OTP, outputs the URL for that OTP,
+// and attempts to parse that URL. It verifies that the two OTPs
+// are the same, and that they produce the same output.
+func TestURL(t *testing.T) {
+	var ident = "testuser@foo"
+	otp := NewHOTP(testKey, 0, 6)
+	url := otp.URL("testuser@foo")
+	otp2, id, err := FromURL(url)
+	if err != nil {
+		fmt.Printf("hotp: failed to parse HOTP URL\n")
+		t.FailNow()
+	} else if id != ident {
+		fmt.Printf("hotp: bad label\n")
+		fmt.Printf("\texpected: %s\n", ident)
+		fmt.Printf("\t  actual: %s\n", id)
+		t.FailNow()
+	} else if otp2.Counter() != otp.Counter() {
+		fmt.Printf("hotp: OTP counters aren't synced\n")
+		fmt.Printf("\toriginal: %d\n", otp.Counter())
+		fmt.Printf("\t  second: %d\n", otp2.Counter())
+		t.FailNow()
+	}
+
+	code1 := otp.OTP()
+	code2 := otp2.OTP()
+	if code1 != code2 {
+		fmt.Printf("hotp: mismatched OTPs\n")
+		fmt.Printf("\texpected: %s\n", code1)
+		fmt.Printf("\t  actual: %s\n", code2)
+	}
+
+	// There's not much we can do test the QR code, except to
+	// ensure it doesn't fail.
+	_, err = otp.QR(ident)
+	if err != nil {
+		fmt.Printf("hotp: failed to generate QR code PNG (%v)\n", err)
+		t.FailNow()
+	}
+
+	// This should fail because the maximum size of an alphanumeric
+	// QR code with the lowest-level of error correction should
+	// max out at 4296 bytes. 8k may be a bit overkill... but it
+	// gets the job done. The value is read from the PRNG to
+	// increase the likelihood that the returned data is
+	// uncompressible.
+	var tooBigIdent = make([]byte, 8192)
+	_, err = io.ReadFull(PRNG, tooBigIdent)
+	if err != nil {
+		fmt.Printf("hotp: failed to read identity (%v)\n", err)
+		t.FailNow()
+	} else if _, err = otp.QR(string(tooBigIdent)); err == nil {
+		fmt.Println("hotp: QR code should fail to encode oversized URL")
+		t.FailNow()
+	}
+}
+
+// This test makes sure we can generate codes for padded and non-padded
+// entries
+func TestPaddedURL(t *testing.T) {
+	var urlList = []string{
+		"otpauth://hotp/?secret=ME",
+		"otpauth://hotp/?secret=MEFR",
+		"otpauth://hotp/?secret=MFRGG",
+		"otpauth://hotp/?secret=MFRGGZA",
+		"otpauth://hotp/?secret=a6mryljlbufszudtjdt42nh5by=======",
+		"otpauth://hotp/?secret=a6mryljlbufszudtjdt42nh5by",
+		"otpauth://hotp/?secret=a6mryljlbufszudtjdt42nh5by%3D%3D%3D%3D%3D%3D%3D",
+	}
+	var codeList = []string{
+		"413198",
+		"770938",
+		"670717",
+		"402378",
+		"069864",
+		"069864",
+		"069864",
+	}
+
+	for i := range urlList {
+		if o, id, err := FromURL(urlList[i]); err != nil {
+			fmt.Println("hotp: URL should have parsed successfully (id=", id, ")")
+			fmt.Printf("\turl was: %s\n", urlList[i])
+			t.FailNow()
+			fmt.Printf("\t%s, %s\n", o.OTP(), id)
+		} else {
+			code2 := o.OTP()
+			if code2 != codeList[i] {
+				fmt.Printf("hotp: mismatched OTPs\n")
+				fmt.Printf("\texpected: %s\n", codeList[i])
+				fmt.Printf("\t  actual: %s\n", code2)
+				t.FailNow()
+			}
+		}
+	}
+}
+
+// This test attempts a variety of invalid urls against the parser
+// to ensure they fail.
+func TestBadURL(t *testing.T) {
+	var urlList = []string{
+		"http://google.com",
+		"",
+		"-",
+		"foo",
+		"otpauth:/foo/bar/baz",
+		"://",
+		"otpauth://hotp/?digits=",
+		"otpauth://hotp/?secret=MFRGGZDF&digits=ABCD",
+		"otpauth://hotp/?secret=MFRGGZDF&counter=ABCD",
+	}
+
+	for i := range urlList {
+		if _, _, err := FromURL(urlList[i]); err == nil {
+			fmt.Println("hotp: URL should not have parsed successfully")
+			fmt.Printf("\turl was: %s\n", urlList[i])
+			t.FailNow()
+		}
+	}
+}

twofactor/totp.go

@@ -0,0 +1,172 @@
+package twofactor
+
+import (
+	"crypto"
+	"crypto/sha1"
+	"crypto/sha256"
+	"crypto/sha512"
+	"encoding/base32"
+	"hash"
+	"io"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"github.com/benbjohnson/clock"
+)
+
+var timeSource = clock.New()
+
+// TOTP represents an RFC 6238 Time-based One-Time Password instance.
+type TOTP struct {
+	*OATH
+	step uint64
+}
+
+// Type returns OATH_TOTP.
+func (otp *TOTP) Type() Type {
+	return OATH_TOTP
+}
+
+func (otp *TOTP) otp(counter uint64) string {
+	return otp.OATH.OTP(counter)
+}
+
+// OTP returns the OTP for the current timestep.
+func (otp *TOTP) OTP() string {
+	return otp.otp(otp.OTPCounter())
+}
+
+// URL returns a TOTP URL (i.e. for putting in a QR code).
+func (otp *TOTP) URL(label string) string {
+	return otp.OATH.URL(otp.Type(), label)
+}
+
+// SetProvider sets up the provider component of the OTP URL.
+func (otp *TOTP) SetProvider(provider string) {
+	otp.provider = provider
+}
+
+func (otp *TOTP) otpCounter(t uint64) uint64 {
+	return (t - otp.counter) / otp.step
+}
+
+// OTPCounter returns the current time value for the OTP.
+func (otp *TOTP) OTPCounter() uint64 {
+	return otp.otpCounter(uint64(timeSource.Now().Unix()))
+}
+
+// NewTOTP takes a new key, a starting time, a step, the number of
+// digits of output (typically 6 or 8) and the hash algorithm to
+// use, and builds a new OTP.
+func NewTOTP(key []byte, start uint64, step uint64, digits int, algo crypto.Hash) *TOTP {
+	h := hashFromAlgo(algo)
+	if h == nil {
+		return nil
+	}
+
+	return &TOTP{
+		OATH: &OATH{
+			key:     key,
+			counter: start,
+			size:    digits,
+			hash:    h,
+			algo:    algo,
+		},
+		step: step,
+	}
+
+}
+
+// NewTOTPSHA1 will build a new TOTP using SHA-1.
+func NewTOTPSHA1(key []byte, start uint64, step uint64, digits int) *TOTP {
+	return NewTOTP(key, start, step, digits, crypto.SHA1)
+}
+
+func hashFromAlgo(algo crypto.Hash) func() hash.Hash {
+	switch algo {
+	case crypto.SHA1:
+		return sha1.New
+	case crypto.SHA256:
+		return sha256.New
+	case crypto.SHA512:
+		return sha512.New
+	}
+	return nil
+}
+
+// GenerateGoogleTOTP produces a new TOTP token with the defaults expected by
+// Google Authenticator.
+func GenerateGoogleTOTP() *TOTP {
+	key := make([]byte, sha1.Size)
+	if _, err := io.ReadFull(PRNG, key); err != nil {
+		return nil
+	}
+	return NewTOTP(key, 0, 30, 6, crypto.SHA1)
+}
+
+// NewGoogleTOTP takes a secret as a base32-encoded string and
+// returns an appropriate Google Authenticator TOTP instance.
+func NewGoogleTOTP(secret string) (*TOTP, error) {
+	key, err := base32.StdEncoding.DecodeString(secret)
+	if err != nil {
+		return nil, err
+	}
+	return NewTOTP(key, 0, 30, 6, crypto.SHA1), nil
+}
+
+func totpFromURL(u *url.URL) (*TOTP, string, error) {
+	label := u.Path[1:]
+	v := u.Query()
+
+	secret := strings.ToUpper(v.Get("secret"))
+	if secret == "" {
+		return nil, "", ErrInvalidURL
+	}
+
+	var algo = crypto.SHA1
+	if algorithm := v.Get("algorithm"); algorithm != "" {
+		if strings.EqualFold(algorithm, "SHA256") {
+			algo = crypto.SHA256
+		} else if strings.EqualFold(algorithm, "SHA512") {
+			algo = crypto.SHA512
+		} else if !strings.EqualFold(algorithm, "SHA1") {
+			return nil, "", ErrInvalidAlgo
+		}
+	}
+
+	var digits = 6
+	if sdigit := v.Get("digits"); sdigit != "" {
+		tmpDigits, err := strconv.ParseInt(sdigit, 10, 8)
+		if err != nil {
+			return nil, "", err
+		}
+		digits = int(tmpDigits)
+	}
+
+	var period uint64 = 30
+	if speriod := v.Get("period"); speriod != "" {
+		var err error
+		period, err = strconv.ParseUint(speriod, 10, 64)
+		if err != nil {
+			return nil, "", err
+		}
+	}
+
+	key, err := base32.StdEncoding.DecodeString(Pad(secret))
+	if err != nil {
+		// assume secret isn't base32 encoded
+		key = []byte(secret)
+	}
+	otp := NewTOTP(key, 0, period, digits, algo)
+	return otp, label, nil
+}
+
+// QR generates a new TOTP QR code.
+func (otp *TOTP) QR(label string) ([]byte, error) {
+	return otp.OATH.QR(otp.Type(), label)
+}
+
+func SetClock(c clock.Clock) {
+	timeSource = c
+}

twofactor/totp_test.go

@@ -0,0 +1,87 @@
+package twofactor
+
+import (
+	"crypto"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/benbjohnson/clock"
+)
+
+var rfcTotpKey = map[crypto.Hash][]byte{
+	crypto.SHA1:   []byte("12345678901234567890"),
+	crypto.SHA256: []byte("12345678901234567890123456789012"),
+	crypto.SHA512: []byte("1234567890123456789012345678901234567890123456789012345678901234"),
+}
+var rfcTotpStep uint64 = 30
+
+var rfcTotpTests = []struct {
+	Time uint64
+	Code string
+	T    uint64
+	Algo crypto.Hash
+}{
+	{59, "94287082", 1, crypto.SHA1},
+	{59, "46119246", 1, crypto.SHA256},
+	{59, "90693936", 1, crypto.SHA512},
+	{1111111109, "07081804", 37037036, crypto.SHA1},
+	{1111111109, "68084774", 37037036, crypto.SHA256},
+	{1111111109, "25091201", 37037036, crypto.SHA512},
+	{1111111111, "14050471", 37037037, crypto.SHA1},
+	{1111111111, "67062674", 37037037, crypto.SHA256},
+	{1111111111, "99943326", 37037037, crypto.SHA512},
+	{1234567890, "89005924", 41152263, crypto.SHA1},
+	{1234567890, "91819424", 41152263, crypto.SHA256},
+	{1234567890, "93441116", 41152263, crypto.SHA512},
+	{2000000000, "69279037", 66666666, crypto.SHA1},
+	{2000000000, "90698825", 66666666, crypto.SHA256},
+	{2000000000, "38618901", 66666666, crypto.SHA512},
+	{20000000000, "65353130", 666666666, crypto.SHA1},
+	{20000000000, "77737706", 666666666, crypto.SHA256},
+	{20000000000, "47863826", 666666666, crypto.SHA512},
+}
+
+func TestTotpRFC(t *testing.T) {
+	for _, tc := range rfcTotpTests {
+		otp := NewTOTP(rfcTotpKey[tc.Algo], 0, rfcTotpStep, 8, tc.Algo)
+		if otp.otpCounter(tc.Time) != tc.T {
+			fmt.Printf("twofactor: invalid TOTP (t=%d, h=%d)\n", tc.Time, tc.Algo)
+			fmt.Printf("\texpected: %d\n", tc.T)
+			fmt.Printf("\t  actual: %d\n", otp.otpCounter(tc.Time))
+			t.Fail()
+		}
+
+		if code := otp.otp(otp.otpCounter(tc.Time)); code != tc.Code {
+			fmt.Printf("twofactor: invalid TOTP (t=%d, h=%d)\n", tc.Time, tc.Algo)
+			fmt.Printf("\texpected: %s\n", tc.Code)
+			fmt.Printf("\t  actual: %s\n", code)
+			t.Fail()
+		}
+	}
+}
+
+func TestTOTPTime(t *testing.T) {
+	otp := GenerateGoogleTOTP()
+
+	testClock := clock.NewMock()
+	testClock.Add(2 * time.Minute)
+	SetClock(testClock)
+
+	code := otp.OTP()
+
+	testClock.Add(-1 * time.Minute)
+	if newCode := otp.OTP(); newCode == code {
+		t.Errorf("twofactor: TOTP: previous code %s shouldn't match code %s", newCode, code)
+	}
+
+	testClock.Add(2 * time.Minute)
+	if newCode := otp.OTP(); newCode == code {
+		t.Errorf("twofactor: TOTP: future code %s shouldn't match code %s", newCode, code)
+	}
+
+	testClock.Add(-1 * time.Minute)
+	if newCode := otp.OTP(); newCode != code {
+		t.Errorf("twofactor: TOTP: current code %s shouldn't match code %s", newCode, code)
+	}
+}

twofactor/util.go

@@ -0,0 +1,16 @@
+package twofactor
+
+import (
+	"strings"
+)
+
+// Pad calculates the number of '='s to add to our encoded string
+// to make base32.StdEncoding.DecodeString happy
+func Pad(s string) string {
+	if !strings.HasSuffix(s, "=") && len(s)%8 != 0 {
+		for len(s)%8 != 0 {
+			s += "="
+		}
+	}
+	return s
+}

twofactor/util_test.go

@@ -0,0 +1,53 @@
+package twofactor
+
+import (
+	"encoding/base32"
+	"fmt"
+	"math/rand"
+	"strings"
+	"testing"
+)
+
+const letters = "1234567890!@#$%^&*()abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+func randString() string {
+	b := make([]byte, rand.Intn(len(letters)))
+	for i := range b {
+		b[i] = letters[rand.Intn(len(letters))]
+	}
+	return base32.StdEncoding.EncodeToString(b)
+}
+
+func TestPadding(t *testing.T) {
+	for i := 0; i < 300; i++ {
+		b := randString()
+		origEncoding := string(b)
+		modEncoding := strings.ReplaceAll(string(b), "=", "")
+		str, err := base32.StdEncoding.DecodeString(origEncoding)
+		if err != nil {
+			fmt.Println("Can't decode: ", string(b))
+			t.FailNow()
+		}
+
+		paddedEncoding := Pad(modEncoding)
+		if origEncoding != paddedEncoding {
+			fmt.Println("Padding failed:")
+			fmt.Printf("Expected: '%s'", origEncoding)
+			fmt.Printf("Got: '%s'", paddedEncoding)
+			t.FailNow()
+		} else {
+			mstr, err := base32.StdEncoding.DecodeString(paddedEncoding)
+			if err != nil {
+				fmt.Println("Can't decode: ", paddedEncoding)
+				t.FailNow()
+			}
+
+			if string(mstr) != string(str) {
+				fmt.Println("Re-padding failed:")
+				fmt.Printf("Expected: '%s'", str)
+				fmt.Printf("Got: '%s'", mstr)
+				t.FailNow()
+			}
+		}
+	}
+}