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.Verifypanics on a wrong key length. The documentation says so. The constructor checks the length once.base64.URLEncodingexpects padding. Tokens have none. UseRawURLEncoding.- 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.
intis 32 bits on some targets. Timestamps areint64here. json.Unmarshalignores 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.