Clavem

Verify a Clavem license token offline in Go

Split the token on dots, decode the parts with base64.RawURLEncoding, verify the signature over "sgt1.<payload>" with ed25519.Verify, then check v, pid, valid, exp and refresh_by. It needs no third-party module, and ed25519.Verify panics if the key is not 32 bytes, so check that first.

The token format and the checks are in the offline verification reference, which has other languages. This page is the Go version. It reports why a token was refused, takes the clock as a parameter so tests need no timers, and covers the places where Go’s API surprises people. The call that fetches the token is in license key validation in Go. The logic was run in Swift, Rust, Python, C++ and Node against the same test tokens, and the results are in the table.

The verifier

package license

import (
	"crypto/ed25519"
	"encoding/base64"
	"encoding/json"
	"errors"
	"strings"
	"time"
)

type Claims struct {
	V         int    `json:"v"`
	LID       int64  `json:"lid"`
	PID       int64  `json:"pid"`
	KH        string `json:"kh"`
	Status    string `json:"status"`
	Valid     bool   `json:"valid"`
	IID       string `json:"iid"`
	FP        string `json:"fp"`
	Email     string `json:"email"`
	IAT       int64  `json:"iat"`
	EXP       *int64 `json:"exp"` // nil for perpetual licenses
	RefreshBy int64  `json:"refresh_by"`
}

type Check string

const (
	Ok           Check = "ok"
	Malformed    Check = "malformed"
	BadSignature Check = "bad-signature"
	WrongProduct Check = "wrong-product"
	NotValid     Check = "not-valid"
	Expired      Check = "expired"
	Stale        Check = "stale"
	ClockSetBack Check = "clock-set-back"
)

type Verifier struct {
	key       ed25519.PublicKey
	productID int64
	Now       func() time.Time // replace in tests
}

// NewVerifier takes the 32-byte public key, base64url, from the product page.
func NewVerifier(publicKey string, productID int64) (*Verifier, error) {
	raw, err := base64.RawURLEncoding.DecodeString(strings.TrimSpace(publicKey))
	if err != nil || len(raw) != ed25519.PublicKeySize {
		return nil, errors.New("public key must be 32 bytes, base64url")
	}
	return &Verifier{key: ed25519.PublicKey(raw), productID: productID, Now: time.Now}, nil
}

// Claims returns the claims when the signature is good, otherwise Malformed or BadSignature.
func (v *Verifier) Claims(token string) (*Claims, Check) {
	parts := strings.Split(token, ".")
	if len(parts) != 3 || parts[0] != "sgt1" {
		return nil, Malformed
	}
	signature, err1 := base64.RawURLEncoding.DecodeString(parts[2])
	payload, err2 := base64.RawURLEncoding.DecodeString(parts[1])
	if err1 != nil || err2 != nil || len(signature) != ed25519.SignatureSize {
		return nil, Malformed
	}
	if !ed25519.Verify(v.key, []byte(parts[0]+"."+parts[1]), signature) { // the text exactly as received
		return nil, BadSignature
	}
	var c Claims
	if err := json.Unmarshal(payload, &c); err != nil {
		return nil, Malformed
	}
	return &c, Ok
}

// Check returns Ok or the reason. highestIAT is the largest iat verified before.
func (v *Verifier) Check(token string, highestIAT int64) Check {
	c, result := v.Claims(token)
	if result != Ok {
		return result
	}
	now := v.Now().Unix()
	switch {
	case c.V != 1:
		return Malformed
	case c.PID != v.productID:
		return WrongProduct
	case !c.Valid:
		return NotValid
	case c.EXP != nil && *c.EXP <= now:
		return Expired
	case now < highestIAT:
		return ClockSetBack
	case c.RefreshBy <= now:
		return Stale
	}
	return Ok
}

Only Ok should turn the paid features on, and Stale means validate online once. Construct the verifier at startup and return the error to the caller. A bad key is a build mistake you want to see in development.

What the checks give

The same logic, run on test tokens signed with a throwaway key in the documented sgt1 format. These results come from the Swift, Rust, Python, C++ and Node versions of this guide. The Go code should return the same:

Token Result
Fresh ok
exp in 30 days ok
exp a minute ago expired
refresh_by 6 days ago stale
Issued for an expired license (valid: false) not-valid
Another product’s pid wrong-product
v is 2 malformed
Payload edited to a far-off exp, old signature bad-signature
Signed by another key bad-signature
The live demo token, with a different public key bad-signature
Two or four parts, sgt2 prefix, plain text malformed
Fresh token, 15 days later stale
Fresh token, clock behind a token already seen clock-set-back

The live demo token is real and decodes, but Clavem signed it with its own key, so a verifier built with any other public key has to refuse it. Write these as a table-driven test with t.Run and a fixed Now, and the 15-days-later case needs no sleep.

Does this token belong to this key?

kh is the first 16 hex characters of the SHA-256 of the normalized key. A Clavem-format key is uppercased with I and L read as 1, O as 0 and U as V. Any other key is lowercased:

import (
	"crypto/sha256"
	"encoding/hex"
	"regexp"
	"strings"
)

var nativeKey = regexp.MustCompile(`^[0-9A-Za-z]{5}(-[0-9A-Za-z]{5}){4}$`)

func (c *Claims) MatchesKey(licenseKey string) bool {
	k := strings.TrimSpace(licenseKey)
	if nativeKey.MatchString(k) {
		k = strings.ToUpper(k)
		k = strings.NewReplacer("I", "1", "L", "1", "O", "0", "U", "V").Replace(k)
	} else {
		k = strings.ToLower(k)
	}
	sum := sha256.Sum256([]byte(k))
	return hex.EncodeToString(sum[:])[:16] == c.KH
}

The clock guard, and where the token lives

Keep the highest iat you have verified next to the license in the keyring entry from the validation page, and pass it as highestIAT. Raise it only after Check returned Ok. A user who deletes the entry starts over, and nothing offline can prevent that. The guard stops the casual date change. A token is signed, not secret, so a file under os.UserConfigDir() is enough: a changed byte fails the signature. Its payload includes the buyer’s email address in readable form, so keep it out of logs.

Traps in Go

  • ed25519.Verify panics on a wrong key length. The documentation says so. The constructor checks the length once.
  • base64.URLEncoding expects padding. Tokens have none. Use RawURLEncoding.
  • Base64 decoders skip line breaks. A token pasted with a newline in the middle still decodes, so trim and split strictly, as above.
  • Integer width. int is 32 bits on some targets. Timestamps are int64 here.
  • json.Unmarshal ignores unknown fields, which is what you want: a token that gains a field does not break old builds.

Doing this with Clavem

Each product has its own key pair. The public half is on the product page and in GET /v1/admin/products, and every activate and validate response carries a token signed with the private half. See the API reference for the endpoints.

Questions

Does Go need a library for Ed25519?

No. The standard library has crypto/ed25519, with Verify taking the public key, the message and the 64-byte signature. Pair it with encoding/base64 and encoding/json and you have everything the token check needs.

Why does ed25519.Verify panic?

The documentation says it panics when the public key is not exactly 32 bytes. A wrong key in your configuration would crash the program. Decode the key once at startup, check its length, and return an error instead.

Which base64 encoding do Clavem tokens use?

Unpadded base64url, which is base64.RawURLEncoding in Go. URLEncoding expects padding and fails on tokens, and StdEncoding uses a different alphabet.

Sources

  1. Go crypto/ed25519, Verify (checked November 2026)
  2. Go encoding/base64, RawURLEncoding (checked November 2026)