Skip to content

Intégration du SDK

Utiliser l'API HTTP directement (tout langage)

Pas de SDK pour votre langage ? Appelez l'API runtime de Keyright via HTTP : activez une machine, vérifiez vous-même la lease signée hors ligne (charge utile canonique + RSA/SHA-256), désactivez, et gérez les machines isolées (air-gapped) — avec des exemples copiables à porter en Go, Rust, C++, PHP et plus encore.

Keyright fournit des SDK officiels pour .NET, Node.js, Python et Java — si vous utilisez l’un de ceux-là, servez-vous-en. Chaque SDK implémente tout ce que décrit cette page (activation, vérification de lease hors ligne, mise en cache, liaison au nœud, révocation) et constitue le chemin pris en charge. Voir le guide Intégration du SDK .NET pour la forme qu’ils suivent tous.

Cette page s’adresse à tous les autres — Go, Rust, C++, PHP, Ruby, Swift, ou tout ce qui n’a pas de SDK Keyright. L’API runtime est du simple JSON sur HTTP, et les formats de licence et de lease sont des spécifications versionnées, indépendantes du langage. Vous pouvez lui parler directement. Cette page est à la fois un guide pratique et la référence exacte, à l’octet près, dont vous avez besoin pour vérifier correctement une lease dans votre langage.

Le modèle complet en deux mouvements

Tout ce que fait un client se réduit à deux choses :

  1. Activer — envoyez en POST une clé de licence plus un identifiant de machine stable, et recevez en retour une lease de courte durée, signée en RSA, liée à cette machine. C’est l’étape en ligne : elle consomme un siège et prouve que la clé est valide à cet instant.
  2. Vérifier la lease hors ligne — contrôlez vous-même la signature de la lease avec la clé publique de l’éditeur, puis vérifiez le produit, la machine et l’expiration. Une fois que vous savez faire cela, votre application continue de fonctionner sans réseau jusqu’à la fin de la fenêtre de grâce de la lease. Si vous n’appelez jamais qu’en ligne, vous pouvez sauter la vérification et faire confiance au champ status — mais alors une panne réseau bloque vos utilisateurs, c’est pourquoi la plupart des clients vérifient.

Les deux endpoints runtime (/v1/activate, /v1/validate) et /v1/free-seat sont sans authentification — pas de jeton, appelés directement par votre application. Ils sont limités en débit par adresse IP cliente (une fenêtre par minute généreuse ; un 429 porte Retry-After: 60).

$BASE ci-dessous est l’URL du service d’émission de votre éditeur, p. ex. https://keyright.delta1labs.com.

Activer

Envoyez du JSON en POST à /v1/activate. Les seuls champs obligatoires sont key, machineId et product ; le reste est constitué de métadonnées facultatives que l’éditeur voit dans son tableau de bord.

curl -s -X POST "$BASE/v1/activate" \
  -H "content-type: application/json" \
  -d '{
        "key": "LIC-9F3A...",
        "machineId": "b1946ac92492d2347c6235b4d2611184",
        "product": "acme-app",
        "os": "linux",
        "hostname": "build-07",
        "appVersion": "2.4.0"
      }'

Une réponse réussie :

{
  "status": "ok",
  "seats": 3,
  "used": 1,
  "license": {
    "licensee": "Acme GmbH",
    "product": "acme-app",
    "tier": "pro",
    "expiryUtc": "2027-01-01T00:00:00.0000000Z",
    "trial": false,
    "revoked": false
  },
  "lease": "{\"key\":\"LIC-9F3A...\",\"machineId\":\"b1946ac9...\",\"product\":\"acme-app\",\"licensee\":\"Acme GmbH\",\"tier\":\"pro\",\"licenseExpiryUtc\":\"2027-01-01T00:00:00.0000000Z\",\"leaseExpiresUtc\":\"2026-10-11T09:14:22.1030000Z\",\"entitlements\":{\"export\":\"true\",\"max-projects\":\"10\"},\"signature\":\"Base64Sig==\"}"
}

Deux choses à remarquer :

  • lease est une chaîne JSON — le document de lease signé tout entier, sérialisé, sous la forme d’un seul champ de la réponse. Vous stockez cette chaîne telle quelle (c’est votre preuve hors ligne), et vous l’analysez comme son propre objet JSON pour la vérifier. Ne la reformatez pas avant de la stocker.
  • Le bloc license est un résumé de commodité. Ne vous y fiez pas pour verrouiller des fonctionnalités — il n’est pas signé individuellement. La lease signée est la source de vérité ; le résumé ne sert qu’à l’affichage.

Gérer status

status est le champ sur lequel vous branchez. Valeurs :

statusSignificationQue faire
okActivée ; lease est présenteVérifiez et mettez en cache la lease ; débloquez les fonctionnalités
not_foundClé inconnue, ou mauvais produitAffichez « clé non reconnue » ; restez en mode gratuit
revokedLa clé a été révoquéeRetombez en mode gratuit
expiredLa licence (ou l’essai) a expiréRetombez en mode gratuit ; invitez à renouveler
seat_limitTous les sièges de cette clé sont utilisésDites à l’utilisateur de libérer un siège sur une autre machine

Seul ok renvoie une lease. Échouez en mode fermé : traitez tout statut autre que ok, tout code HTTP non-2xx, un 429, un corps mal formé ou une lease qui échoue à la vérification comme non sous licence. Ne retombez jamais dans un état déverrouillé sur une erreur.

Sièges et idempotence

Les sièges sont appliqués côté serveur. Le nombre seats de la clé est le plafond ; used vous indique combien de machines détiennent actuellement un siège. Réactiver une machine déjà liée à la clé ne consomme pas un siège supplémentaire — le serveur indexe sur (key, machineId), de sorte qu’appeler de nouveau /v1/activate pour la même machine est idempotent et ne fait que rafraîchir la lease. C’est pourquoi l’identifiant de machine doit être stable (section suivante). S’il change, la machine paraît nouvelle et consomme un nouveau siège, et l’utilisateur se heurte à seat_limit.

L’identifiant de machine

machineId est votre identifiant pour l’appareil — c’est vous qui le choisissez. Les SDK officiels calculent une empreinte de liaison au nœud salée (leur schéma interne KRM1) à partir de signaux matériels et du système d’exploitation, mais le serveur traite machineId comme une chaîne opaque. Un client sans SDK n’a pas besoin de reproduire ce schéma. Il vous faut simplement un identifiant qui soit :

  • Stable à travers les redémarrages, les mises à jour et les reboots. S’il change, la machine paraît nouvelle, consomme un siège et finit par déclencher seat_limit. C’est la propriété la plus importante de toutes.
  • Propre à chaque machine, pour que le comptage des sièges ait un sens.
  • Pas trivialement falsifiable par un utilisateur final qui voudrait cloner une activation sur de nombreuses machines (un hachage, pas une valeur qu’il peut saisir).

Une bonne recette : rassemblez un ou deux identifiants stables du système ou du matériel (un GUID de machine, une adresse MAC principale, un numéro de série de disque, ou le machine-id de systemd), concaténez-les avec une chaîne de sel constante qui vous est propre, hachez le tout en SHA-256, et encodez le condensé en hexadécimal ou en base64. Calculez-le une fois, et réutilisez exactement la même chaîne à chaque fois que vous activez, validez, vérifiez ou libérez un siège. Stockez-le à côté de la lease en cache pour pouvoir le comparer plus tard.

machineId = hex( sha256( "acme-app-salt|" + stableHardwareId ) )

Gardez-le constant pour toujours pour une installation donnée. C’est tout ce dont le serveur a besoin.

Vérifier la lease hors ligne

C’est la partie sans raccourci. La lease est signée avec la clé RSA privée de l’éditeur, qui ne quitte jamais son serveur. Vous la vérifiez avec la clé publique correspondante, que l’éditeur vous fournit (onglet Integration du tableau de bord, ou GET $BASE/admin/public-key avec un jeton admin) sous la forme d’une chaîne SubjectPublicKeyInfo en base64 (SPKI). Cette clé n’est pas un secret — elle ne peut que vérifier, jamais signer — vous l’embarquez donc dans votre binaire.

La vérification consiste à : reconstruire les octets exacts qui ont été signés, puis vérifier en RSA la signature sur ceux-ci. Les octets signés ne sont pas le JSON de la lease — c’est une chaîne canonique assemblée à partir de champs précis dans un ordre précis.

La charge utile canonique — à reproduire à l’octet près

La chaîne signée est (version de spécification krlease1) :

krlease1|<key>|<machineId>|<product>|<licensee>|<tier>|<licenseExpiryUtc-or-empty>|<leaseExpiresUtc>

Ensuite, de manière conditionnelle et dans cet ordre exact, deux suffixes sont ajoutés :

  1. |ent=<entitlements> — ajouté uniquement si la lease possède un objet entitlements non vide. Les droits sont sérialisés de façon déterministe : clés triées par ordre ordinal (octet/point de code), chacune rendue sous la forme key=value, jointes par des virgules. P. ex. {"max-projects":"10","export":"true"} → export=true,max-projects=10.
  2. |trial — ajouté uniquement si le champ trial de la lease vaut true. Rien n’est ajouté quand il vaut false.

La chaîne entière est encodée en UTF-8, et la signature est RSA PKCS#1 v1.5 sur SHA-256, encodée en base64 dans le champ signature de la lease.

Ce bug d’ordre est réel — faites-y attention. |ent= vient avant |trial. Inversez l’ordre, omettez un suffixe conditionnel qui devrait être présent, ajoutez-en un qui ne devrait pas l’être, ou reformatez une date, et les octets reconstruits diffèrent d’un seul caractère — et la signature échoue silencieusement à la vérification. Il n’y a pas de correspondance partielle. Ce bug d’ordre précis a piégé les SDK pendant le développement ; c’est pourquoi l’ordre est énoncé si précisément. Quand une lease que vous savez valide refuse de se vérifier, la chaîne canonique est le premier endroit où regarder.

Détails critiques qui piègent les gens :

  • Utilisez les chaînes de date telles quelles depuis le JSON. licenseExpiryUtc et leaseExpiresUtc sont des chaînes ISO-8601 aller-retour comme 2026-10-11T09:14:22.1030000Z (7 chiffres fractionnaires). Ne les analysez pas pour les resérialiser dans la chaîne canonique — copiez les caractères exacts de la lease. (Vous les analysez séparément, plus tard, uniquement pour les comparer à « maintenant ».)
  • licenseExpiryUtc peut être absent/null pour une licence perpétuelle. Dans ce cas, mettez la chaîne vide à cet emplacement — les deux séparateurs | qui l’entourent apparaissent toujours : ...|<tier>||<leaseExpiresUtc>.
  • Droits vides = aucun |ent= du tout. Une lease sans droits signe exactement les mêmes octets qu’une lease émise avant que les droits n’existent. N’ajoutez |ent= que lorsque l’objet est présent et non vide.

Exemple concret (Go — portez-le dans votre langage)

La bibliothèque standard de Go couvre tout. La logique se porte directement en Rust (rsa + sha2), PHP (openssl_verify avec OPENSSL_ALGO_SHA256), Ruby (OpenSSL::PKey::RSA#verify), C++ (OpenSSL EVP_DigestVerify), etc. — seuls les appels cryptographiques changent.

package main

import (
	"crypto"
	"crypto/rsa"
	"crypto/sha256"
	"crypto/x509"
	"encoding/base64"
	"encoding/json"
	"errors"
	"sort"
	"strings"
	"time"
)

type Lease struct {
	Key              string            `json:"key"`
	MachineID        string            `json:"machineId"`
	Product          string            `json:"product"`
	Licensee         string            `json:"licensee"`
	Tier             string            `json:"tier"`
	LicenseExpiryUtc *string           `json:"licenseExpiryUtc"` // pointeur : peut être null
	LeaseExpiresUtc  string            `json:"leaseExpiresUtc"`
	Entitlements     map[string]string `json:"entitlements"`
	Trial            bool              `json:"trial"`
	Signature        string            `json:"signature"`
}

// Reconstruit les octets EXACTS qui ont été signés. L'ordre est déterminant.
func canonical(l *Lease) []byte {
	var b strings.Builder
	b.WriteString("krlease1|")
	b.WriteString(l.Key + "|")
	b.WriteString(l.MachineID + "|")
	b.WriteString(l.Product + "|")
	b.WriteString(l.Licensee + "|")
	b.WriteString(l.Tier + "|")
	if l.LicenseExpiryUtc != nil { // chaîne vide quand perpétuelle (null)
		b.WriteString(*l.LicenseExpiryUtc)
	}
	b.WriteString("|")
	b.WriteString(l.LeaseExpiresUtc)

	// |ent=  EN PREMIER, seulement si non vide. Clés triées par ordre ordinal, k=v, jointes par des virgules.
	if len(l.Entitlements) > 0 {
		keys := make([]string, 0, len(l.Entitlements))
		for k := range l.Entitlements {
			keys = append(keys, k)
		}
		sort.Strings(keys) // sort.Strings de Go est ordinal (par octet) — conforme à la spécification
		parts := make([]string, len(keys))
		for i, k := range keys {
			parts[i] = k + "=" + l.Entitlements[k]
		}
		b.WriteString("|ent=" + strings.Join(parts, ","))
	}

	// |trial  EN DERNIER, seulement si true.
	if l.Trial {
		b.WriteString("|trial")
	}
	return []byte(b.String())
}

// publicKeyB64 est le SubjectPublicKeyInfo (SPKI) en base64 de l'éditeur.
func VerifyLease(leaseJSON, publicKeyB64, expectedProduct, ourMachineID string, now time.Time) (*Lease, error) {
	var l Lease
	if err := json.Unmarshal([]byte(leaseJSON), &l); err != nil {
		return nil, err // échec en mode fermé
	}

	// 1. Charger la clé publique (SPKI).
	der, err := base64.StdEncoding.DecodeString(publicKeyB64)
	if err != nil {
		return nil, err
	}
	pubAny, err := x509.ParsePKIXPublicKey(der)
	if err != nil {
		return nil, err
	}
	pub, ok := pubAny.(*rsa.PublicKey)
	if !ok {
		return nil, errors.New("not an RSA key")
	}

	// 2. Vérifier la signature sur les octets canoniques (PKCS#1 v1.5, SHA-256).
	sig, err := base64.StdEncoding.DecodeString(l.Signature)
	if err != nil {
		return nil, err
	}
	digest := sha256.Sum256(canonical(&l))
	if err := rsa.VerifyPKCS1v15(pub, crypto.SHA256, digest[:], sig); err != nil {
		return nil, errors.New("bad signature") // échec en mode fermé
	}

	// 3. Vérifications sémantiques — toutes doivent passer, sinon échec en mode fermé.
	if l.Product != expectedProduct {
		return nil, errors.New("wrong product")
	}
	if l.MachineID != ourMachineID {
		return nil, errors.New("lease bound to a different machine")
	}
	leaseExp, err := time.Parse(time.RFC3339Nano, l.LeaseExpiresUtc)
	if err != nil || !now.Before(leaseExp) {
		return nil, errors.New("lease grace window elapsed") // il est temps de réactiver en ligne
	}
	if l.LicenseExpiryUtc != nil {
		licExp, err := time.Parse(time.RFC3339Nano, *l.LicenseExpiryUtc)
		if err != nil || !now.Before(licExp) {
			return nil, errors.New("license expired")
		}
	}
	return &l, nil // sous licence — lisez l.Tier / l.Entitlements pour verrouiller les fonctionnalités
}

La liste de contrôle de vérification (tout langage)

  1. Analysez le JSON de la lease.
  2. Reconstruisez la chaîne canonique exactement — attention à |ent= avant |trial, à l’emplacement de chaîne vide pour un licenseExpiryUtc null, aux dates recopiées telles quelles et aux clés de droits triées par ordre ordinal.
  3. Décodez signature depuis le base64, décodez la clé publique SPKI depuis le base64, et vérifiez en RSA (PKCS#1 v1.5 / SHA-256).
  4. Vérifiez que product est égal à votre produit.
  5. Vérifiez que machineId est égal à l’identifiant de machine que vous avez stocké à l’activation.
  6. Vérifiez que leaseExpiresUtc est dans le futur (la fenêtre de grâce hors ligne — quand elle est dépassée, réactivez en ligne).
  7. Vérifiez que licenseExpiryUtc, s’il est présent, est dans le futur.
  8. Échouez en mode fermé sur quoi que ce soit — une erreur d’analyse, une mauvaise signature, une non-correspondance, une expiration, une horloge à laquelle vous ne pouvez pas vous fier. Seule une lease qui passe chaque étape est sous licence.

Une fois qu’elle passe, lisez tier pour l’édition et entitlements pour les verrous par fonctionnalité.

Désactiver une machine

Pour libérer le siège que cette machine détient (p. ex. avant une désinstallation, ou lors d’une migration vers un nouveau matériel), envoyez un POST à /v1/free-seat :

curl -s -X POST "$BASE/v1/free-seat" \
  -H "content-type: application/json" \
  -d '{"key":"LIC-9F3A...","machineId":"b1946ac9...","product":"acme-app"}'

Réponse : {"status":"ok"}. Le siège est libéré et used diminue, de sorte qu’une autre machine peut s’activer. Supprimez votre lease en cache locale au même moment.

Revalider et rafraîchir

  • POST /v1/validate revérifie une clé + machine par rapport à l’état actuel du serveur — il détecte la révocation et l’expiration survenues après l’activation — sans consommer de nouveau siège. Il prend le même corps de requête que /v1/activate et renvoie la même forme de réponse (y compris une lease fraîche quand le statut est toujours ok). Utilisez-le comme vérification de santé périodique.
  • Réactiver (/v1/activate) sur une machine déjà liée est idempotent et rafraîchit la lease avec un nouveau leaseExpiresUtc. En pratique, c’est ce que font la plupart des clients de manière planifiée.

Les leases sont de courte durée — la fenêtre de grâce par défaut est de 14 jours (l’éditeur peut la configurer). Un client en ligne doit donc réactiver (ou valider) périodiquement — confortablement avant le leaseExpiresUtc de la lease courante — pour prendre en compte les révocations et conserver une lease fraîche en cache. Entre deux rafraîchissements, vérifiez la lease en cache hors ligne à chaque démarrage et verrouillez sur cette base.

Machines hors ligne / isolées (air-gapped)

Pour une machine qui ne pourra jamais joindre le service, l’éditeur génère pour vous une lease de longue durée hors bande. Un opérateur appelle (jeton admin requis, c’est donc l’étape de l’éditeur, pas de votre client) :

curl -s -X POST "$BASE/admin/licenses/{licenseId}/offline-lease" \
  -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"machineId":"b1946ac9...","days":365}'

ce qui renvoie { "machineId": "...", "ttlDays": 365, "lease": "{...signed lease JSON...}" }. Le champ days vaut 365 par défaut — un TTL bien plus long que la fenêtre de grâce d’une lease en ligne, puisque la machine ne se rafraîchira jamais.

Vous obtenez d’abord l’identifiant de machine depuis la machine cible (calculez-le exactement comme le fait votre client, et transmettez-le à l’éditeur), vous livrez la chaîne lease renvoyée à la machine par fichier ou clé USB, et vous la vérifiez avec exactement le même code qu’une lease en ligne — même charge utile canonique, même contrôle de signature, mêmes vérifications de produit/machine/expiration. Une lease hors ligne est une lease ordinaire avec un leaseExpiresUtc lointain ; rien ne change dans la vérification. (Les leases hors ligne générées de cette façon ne sont pas marquées trial, aucun suffixe |trial ne s’applique donc.)

Une note sur les fichiers de licence hors ligne

L’activation et les leases constituent le chemin en-ligne-puis-en-cache. Keyright prend aussi en charge des fichiers de licence entièrement hors ligne — un document JSON signé (license.json) sans aucun aller-retour d’activation. Sa charge utile canonique signée est une spécification différente, plus simple (version kr1) :

<licensee>|<expiryUtc-or-empty>|<tier>[|trial][|kr1:<keyright-fields>]

où le bloc facultatif kr1: porte des champs product=, id=, machine=, td= et ent= joints par des points-virgules (même encodage des droits, triés par ordre ordinal et joints par des virgules). Même cryptographie — RSA PKCS#1 v1.5 / SHA-256, vérifiée avec la même clé publique SPKI. Si votre éditeur vous livre des fichiers de licence plutôt que d’utiliser l’activation, vérifiez-les de la même façon : reconstruisez cette chaîne canonique et vérifiez en RSA. La plupart des intégrations sans SDK n’ont besoin que du chemin de lease ci-dessus ; ne recourez à la vérification de fichiers de licence que si votre éditeur distribue directement des fichiers.

Voir aussi