Long-form recipes for github.com/ubgo/crypt. For each common task, the right function plus a copy-pasteable snippet.
For runnable end-to-end programs, see examples/. For the full API reference, see godoc.
- Authenticated encryption
- Application-wide Sealer
- Binding ciphertext to a context (AAD)
- Random bytes, tokens, IDs
- HMAC signing and verification
- Constant-time comparison
- Password hashing
- Reading AES-CBC ciphertext
- Mixed-format reads with OpenAuto
- Cross-language interop with Node.js
- Testing patterns
Use Seal and Open for AES-256-GCM authenticated encryption. The output is a base64url-no-pad string suitable for any DB column or HTTP header.
key, _ := crypt.RandomBytes(crypt.AEADKeySize) // 32 bytes from CSPRNG
ciphertext, err := crypt.Seal(key, []byte("hello"), nil)
if err != nil {
return err
}
plaintext, err := crypt.Open(key, ciphertext, nil)
if err != nil {
return err
}- Exactly 32 bytes. Other lengths return
ErrInvalidKey. - Sourced from a CSPRNG. Use
crypt.RandomBytes(crypt.AEADKeySize)or load from secure config. - Same key for Seal and Open. Different keys →
ErrTampered.
ciphertext bytes = 1 (version) + 12 (nonce) + N (plaintext) + 16 (tag)
= N + 29 bytes (binary)
≈ N * 4/3 + 39 chars (after base64url encoding)
For an empty plaintext, the ciphertext is 29 bytes / 39 base64url chars. For a 100-byte plaintext, ~172 chars.
For a service that encrypts repeatedly with the same key, construct one Sealer at boot and inject it.
type Plugin struct {
Sealer *crypt.Sealer
DB *ent.Client
}
func New(cfg *Config) (*Plugin, error) {
sealer, err := crypt.NewSealer(cfg.EncryptionKey)
if err != nil {
return nil, fmt.Errorf("init sealer: %w", err)
}
return &Plugin{
Sealer: sealer,
DB: openDB(cfg),
}, nil
}Why a Sealer over the package-level Seal/Open:
- One key validation, not N.
NewSealervalidates the key length once at boot. - One AEAD construction, not N. Reuses
cipher.AEADacross calls. - Concurrent-safe. Share across goroutines without locks.
- Testable. Inject a sealer with a fixed test key in unit tests.
The package-level functions are convenient for one-shot calls (CLIs, scripts, tests). Use a Sealer in long-running services.
AAD (additional authenticated data) lets you bind a ciphertext to a specific context without encrypting the context itself.
// Issue a session token bound to user ID.
token, _ := sealer.Seal([]byte(payload), []byte("user:"+userID))
// At decrypt time, the same userID must be supplied.
pt, err := sealer.Open(token, []byte("user:"+userID))
// err == ErrTampered if userID differs from issue-time| Pattern | AAD value |
|---|---|
| Per-user data | []byte("user:" + userID) |
| Per-tenant data | []byte("tenant:" + tenantID) |
| Per-row encryption | []byte(tableName + ":" + primaryKey) |
| Per-version data | []byte("v=1") (helps detect format upgrades) |
- Token replay across contexts. A token issued for user A is not valid as user B.
- Cross-table replay. A
users.tokenvalue pasted intopartners.tokenwon't decrypt with the partner's AAD. - Format confusion. AAD
"v=1"distinguishes version-1 ciphertexts from future v2 with different semantics.
- Replay against the same user. Use a one-time nonce or timestamp inside the plaintext.
- Token leakage via logs. Operational concern, separate from AEAD.
keyBytes, _ := crypt.RandomBytes(32) // raw bytes for AEAD/HMAC keys
apiKey, _ := crypt.RandomToken(32) // 43 chars, URL-safe base64
shortToken, _ := crypt.RandomToken(16) // 22 chars, for short-lived tokens
logCorrID, _ := crypt.RandomHex(8) // 16 chars, hex| Need | Use | Output length |
|---|---|---|
| AEAD key | RandomBytes(32) |
32 bytes |
| HMAC key | RandomBytes(32) |
32 bytes |
| Long-lived API key | RandomToken(32) |
43 chars |
| Short-lived (≤24h) token | RandomToken(16) |
22 chars |
| CSRF token | RandomToken(24) |
32 chars |
| Log correlation ID | RandomHex(8) |
16 chars |
| Filename / path-safe ID | RandomHex(16) |
32 chars |
All helpers source from crypto/rand. Never use math/rand for any cryptographic purpose — it's pseudo-random and predictable.
// At issue time:
plain, _ := crypt.RandomToken(32)
showOnce(plain)
hash := sha256.Sum256([]byte(plain))
db.SaveAPIKey(user.ID, hex.EncodeToString(hash[:]))
// At verify time:
provided := c.GetHeader("X-API-Key")
hash := sha256.Sum256([]byte(provided))
if !crypt.ConstantTimeEqual(hash[:], db.LoadAPIKeyHash(...)) {
c.AbortWithStatus(401)
return
}A SHA-256 hash is sufficient here because the input is high-entropy random. For passwords (low-entropy), use HashPassword (argon2id) instead.
For symmetric authentication where signer and verifier share a secret.
secret := []byte("partner-webhook-secret")
// Signer
mac := crypt.Sign(secret, body)
// Verifier
if !crypt.Verify(secret, body, mac) {
return errInvalidSignature
}func (h *Handler) sendWebhook(ctx context.Context, p *PartnerApp, e Event) error {
body, err := json.Marshal(e)
if err != nil {
return err
}
mac := crypt.Sign(p.WebhookSecret, body)
req, _ := http.NewRequestWithContext(ctx, "POST", p.WebhookURL, bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Signature", base64.StdEncoding.EncodeToString(mac))
req.Header.Set("X-Signature-Algorithm", "hmac-sha256")
resp, err := h.httpClient.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
return nil
}func WebhookVerify(secret []byte) gin.HandlerFunc {
return func(c *gin.Context) {
body, err := io.ReadAll(c.Request.Body)
if err != nil {
c.AbortWithStatusJSON(400, gin.H{"error": "read body"})
return
}
c.Request.Body = io.NopCloser(bytes.NewReader(body))
sig := c.GetHeader("X-Signature")
mac, err := base64.StdEncoding.DecodeString(sig)
if err != nil || !crypt.Verify(secret, body, mac) {
c.AbortWithStatusJSON(401, gin.H{"error": "invalid signature"})
return
}
c.Next()
}
}The MAC is computed over the exact bytes the verifier will see. If you re-marshal between signing and sending, the MAC may not match (whitespace, key order can differ). Always sign the bytes you actually transmit.
Always use for any comparison involving secret material.
provided := c.GetHeader("X-Internal-Key")
if !crypt.ConstantTimeEqual([]byte(provided), []byte(internalKey)) {
c.AbortWithStatus(401)
return
}Naive == short-circuits at the first differing byte. An attacker measuring response time can recover the secret one byte at a time.
The function reports false in constant time when inputs are equal-length-but-different. Length difference itself isn't constant-time (it can't be), but in nearly all practical applications inputs already have a known fixed length (32-byte HMAC tag, 36-char UUID, etc.).
For storing user-supplied passwords. Use HashPassword on registration, VerifyPassword on login.
// Registration
hash, err := crypt.HashPassword(password)
if err != nil {
return err
}
db.User.Create().SetEmail(email).SetPasswordHash(hash).Save(ctx)
// Login
user, _ := db.User.Query().Where(user.Email(email)).Only(ctx)
ok, err := crypt.VerifyPassword(password, user.PasswordHash)
if err != nil || !ok {
return errInvalidCredentials
}The stored string is OWASP-recommended PHC format:
$argon2id$v=19$m=65536,t=2,p=1$<salt>$<hash>
Parameters are encoded in the string itself. You can re-tune memory or time costs in future without breaking existing hashes — VerifyPassword reads parameters from the stored value.
Argon2id is intentionally slow (~10–100 ms per hash on a typical server). This is the entire point: it makes brute-force attacks expensive. Don't be tempted to lower the parameters below OWASP recommendations.
For high-throughput systems where login latency matters, consider:
- Caching successful auth in a session token (encrypted with
Seal) so repeat requests don't re-hash. - Rate-limiting login endpoints (e.g., 10 attempts per IP per minute).
If you need to retrieve the original value later (API keys you display once, encrypted credentials), use Seal/Open instead. Hashing is one-way.
If you have data already encrypted with EncryptCBC (or the deprecated EncryptWithKey from v0.x), decrypt with DecryptCBC:
plaintext, err := crypt.DecryptCBC(key, ciphertext)
if err != nil {
return err
}CBC has no message authentication. A tampered ciphertext that produces invalid PKCS7 padding returns ErrInvalidPadding, but a tamper landing on valid padding returns silent garbage plaintext. Don't write new code with CBC. Only use it to read existing data.
See MIGRATION.md for the full migration playbook.
During a migration window when some rows are AEAD and others are still CBC:
import "github.com/ubgo/crypt"
plain, err := crypt.OpenAuto(key, row.Ciphertext, nil)OpenAuto detects the format (base64url+0x01 → AEAD; hex → CBC) and dispatches.
Treat any import "github.com/ubgo/crypt" line as a smell. Production reads should call crypt.Open directly. The legacy subpackage exists to make migration tooling easy to grep for and clean up post-migration.
The TypeScript package crypt-ts produces byte-for-byte identical AEAD ciphertexts. Common patterns:
// Go service issues a session token
token, _ := sealer.Seal([]byte(payload), []byte("user:"+userID))
return token// Node service receives and verifies
import { open } from "@ubgo/crypt"
const plaintext = open(sharedKey, token, Buffer.from("user:" + userID))
const session = JSON.parse(plaintext.toString("utf8"))import { sign } from "@ubgo/crypt"
const mac = sign(serviceKey, body)
fetch(goAPI, { headers: { "X-Sig": mac.toString("hex") }, body })sigHex := c.GetHeader("X-Sig")
sig, _ := hex.DecodeString(sigHex)
if !crypt.Verify(serviceKey, body, sig) {
c.AbortWithStatus(401)
return
}- AEAD
Seal/Open(round-trip and wire bytes) - HMAC
Sign/Verify - AES-CBC
EncryptCBC/DecryptCBC
Both repos consume the same testdata/vectors.json. Any change to one side that breaks parity fails CI on both.
func TestService_Encrypt(t *testing.T) {
testKey := bytes.Repeat([]byte{0x01}, crypt.AEADKeySize)
sealer, err := crypt.NewSealer(testKey)
require.NoError(t, err)
svc := NewService(sealer)
ct, err := svc.Encrypt("test data")
require.NoError(t, err)
pt, err := svc.Decrypt(ct)
require.NoError(t, err)
require.Equal(t, "test data", pt)
}argon2id tests are intentionally slow. If you have a fast-lane test runner:
func TestPasswordHash(t *testing.T) {
if testing.Short() {
t.Skip("argon2id is slow; skipped under -short")
}
// ...
}Then run go test -short ./... for the fast lane and go test ./... for the full suite.
The package has no I/O — every call is pure CPU. Just call it directly in tests. Mocking introduces drift between the mock and the real behavior; nothing about Seal or Sign is slow enough to need mocking.