License framing — primitive défensive

Cadre cryptographiquement signé qui décide qui peut exécuter quel binaire, sur quelles machines, avec quels secrets, jusqu'à quand, sous quelle politique de révocation.

Hors-ligne par défaut, en-ligne en option. Aucun artefact réseau ou disque émis côté détection (le binaire n'envoie rien, sauf si l'opérateur active explicitement WithRevocation ou WithHeartbeat).

TL;DR — règles du jeu en une page

Vocabulaire

Flow de vérification

sequenceDiagram
    autonumber
    participant Op as "Opérateur (issuer)"
    participant Bin as "Binaire (verifier)"
    participant Rev as "Revocation server (opt)"
    participant Hb as "Heartbeat server (opt)"
    participant NTP as "NTP (opt)"

    Op->>Op: GenerateKey + SavePrivateKey
    Op->>Bin: distribute issuer.pub + license.pem

    Note over Bin: license.Verify(data, trusted, opts...)

    Bin->>Bin: 1. parse PEM + size guard
    Bin->>Bin: 2. resolve KeyID → public key
    Bin->>Bin: 3. ed25519.Verify(domain_tag || body)
    Bin->>Bin: 4. read HMAC state file
    Bin->>Bin: 5. NotBefore / NotAfter (with skew)
    Bin->>Bin: 6. audience / issuer match
    Bin->>Bin: 7. bindings (machine, password, custom)
    Bin->>Bin: 8. pinning (BinarySHA256 / IdentitySHA256)
    Bin->>Rev: 9a. fetch signed revocation list (or cache)
    Rev-->>Bin: signed list + serverTime
    Bin->>Bin: 9b. check sequence ≥ last, IsRevoked(lic.ID)
    Bin->>Hb: 10a. POST heartbeat {license_id, nonce}
    Hb-->>Bin: signed reply
    Bin->>Bin: 10b. verify signature, nonce echo, ok==true
    Bin->>NTP: 11. SNTPv4 query (soft warning)
    Bin->>Bin: 12. atomic write state file
    Bin-->>Op: Verified{License, Payload, Warnings} | ErrLicenseInvalid

Quick start

pub, priv, _ := license.GenerateKey()
data, _ := license.New(priv, "alice@example.com", 24*time.Hour)
v, err := license.Verify(data, license.Trusted{Keys: license.SingleKey("default", pub)})

Voir le cookbook pour 8 recettes complètes copier-coller.

Référence des champs

type License

Le corps signé d'une licence. Tous les champs sont couverts par la signature.

Note règle de pinning : si les deux BinarySHA256 et IdentitySHA256 sont définis ET que WithBinaryPinning() est passé, les deux doivent matcher (AND). Définir un seul des deux ne vérifie que celui-là. Aucun = warning sans refus.

type Binding

Les helpers BindMachineIDs(ids...), BindPassword(p), BindPasswordWithParams(p, params), BindTOTP(secret), BindCustom(name, vals...) construisent ces bindings correctement.

type IssueOptions

Tous les champs sauf PrivateKey et Subject sont optionnels.

type Verified (retour de Verify)

Options VerifyOption

Toutes les options sont des fonctions func(*verifyState) à passer en variadique à Verify. Plusieurs options peuvent se combiner librement.

Sous-packages

Erreurs

ErrLicenseInvalid est la seule erreur publique. Discrimination via errors.Is(err, ErrLicenseInvalid). La cause précise (signature, expired, binding mismatch, etc.) part vers le logueur ; elle est volontairement absente de err.Error() pour ne pas guider un attaquant.

Causes internes loguées (non exportées) : bad-format, bad-signature, unknown-key, not-yet-valid, expired, clock-rollback, audience-mismatch, issuer-mismatch, binding-machine-mismatch, binding-password-mismatch, binding-custom-mismatch, binary-hash-mismatch, identity-mismatch, revoked, revocation-stale, heartbeat-failed, state-corrupted.

OPSEC & détection

Limitations

Résiste à

• Forgerie de signature (Ed25519).
• Modification post-émission (toute la License est couverte par la signature).
• Replay cross-audience (aud est signé).
• Réutilisation cross-binaire (aud + binary/identity pinning).
• Substitution de revocation list ancienne (sequence monotone + signed expiry + chain hash).
• Brute-force de password binding (argon2id : t=3, m=64MiB, p=4).
• Rollback de l'horloge sous le TrustedFloor.
• Algorithm-confusion (un seul algo signé, domain-separated par message type).

Ne résiste PAS à

• Un attaquant qui patche Verify dans le binaire pour return nil. Mitigation hors scope — combiner avec cmd/packer + intégrité OS (Authenticode / Sigstore).
• Tamper d'horloge parfait sur une machine totalement offline qui n'a jamais contacté le serveur (= aucun TrustedFloor jamais établi).
• Usage offline indéfini au-delà du GracePeriod après rotation de clé.
• Modification simultanée du binaire et de l'identity embarquée.
• Spoofing de hostid sur une machine que l'attaquant contrôle entièrement.
• Partage de seat (deux machines avec le même hostid + binding password).

Voir threat-model.md pour le détail complet par classe de menace.

Voir aussi

• Cookbook (8 recettes copier-coller)
• Threat model détaillé
• Spec de design — décisions architecturales et trade-offs explicités.