Skip to content

SDK-Integration

Die HTTP-API direkt nutzen (beliebige Sprache)

Kein SDK für Ihre Sprache? Rufen Sie die Keyright-Runtime-API über HTTP auf: eine Maschine aktivieren, den signierten Lease selbst offline prüfen (kanonische Payload + RSA/SHA-256), deaktivieren und netzwerkisolierte (air-gapped) Maschinen handhaben — mit kopierbaren Beispielen, die Sie nach Go, Rust, C++, PHP und mehr portieren können.

Keyright liefert offizielle SDKs für .NET, Node.js, Python und Java — wenn Sie eine dieser Plattformen verwenden, nutzen Sie das SDK. Jedes SDK implementiert alles auf dieser Seite (Aktivierung, Offline-Lease-Prüfung, Zwischenspeicherung, Node-Locking, Widerruf) und ist der unterstützte Weg. Siehe den Leitfaden .NET-SDK-Integration für die Form, der sie alle folgen.

Diese Seite ist für alle anderen — Go, Rust, C++, PHP, Ruby, Swift oder alles, wofür es kein Keyright-SDK gibt. Die Runtime-API ist schlichtes JSON über HTTP, und die Lizenz-/Lease-Formate sind versionierte, sprachunabhängige Spezifikationen. Sie können direkt mit ihr sprechen. Diese Seite ist zugleich eine Anleitung und die exakte Referenz auf Byte-Ebene, die Sie brauchen, um einen Lease in Ihrer Sprache korrekt zu prüfen.

Das gesamte Modell in zwei Zügen

Alles, was ein Client tut, reduziert sich auf zwei Dinge:

  1. Aktivieren — Senden Sie per POST einen Lizenzschlüssel plus eine stabile Maschinen-ID und erhalten Sie einen kurzlebigen, RSA-signierten Lease zurück, der an diese Maschine gebunden ist. Das ist der Online-Schritt: Er belegt einen Platz und beweist, dass der Schlüssel genau jetzt gültig ist.
  2. Den Lease offline prüfen — Prüfen Sie die Signatur des Lease selbst gegen den öffentlichen Schlüssel des Anbieters, dann Produkt/Maschine/Ablauf. Sobald Sie das können, arbeitet Ihre App ohne Netzwerk weiter, bis die Kulanzfrist des Lease endet. Wenn Sie ausschließlich online aufrufen, können Sie die Prüfung überspringen und dem Feld status vertrauen — dann sperrt aber ein Netzwerkausfall Ihre Benutzer aus, weshalb die meisten Clients prüfen.

Beide Runtime-Endpunkte (/v1/activate, /v1/validate) sowie /v1/free-seat sind ohne Auth — kein Token, direkt von Ihrer App aufgerufen. Sie sind pro Client-IP ratenbegrenzt (ein großzügiges Fenster pro Minute; ein 429 trägt Retry-After: 60).

$BASE steht unten für die URL des Issuing-Service Ihres Anbieters, z. B. https://keyright.delta1labs.com.

Aktivieren

Senden Sie JSON per POST an /v1/activate. Die einzigen Pflichtfelder sind key, machineId und product; der Rest sind optionale Metadaten, die der Anbieter in seinem Dashboard sieht.

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"
      }'

Eine erfolgreiche Antwort:

{
  "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==\"}"
}

Zwei Dinge sind zu beachten:

  • lease ist ein JSON-String — das gesamte signierte Lease-Dokument, serialisiert, als ein Feld innerhalb der Antwort. Sie speichern diesen String unverändert (er ist Ihr Offline-Nachweis) und parsen ihn als eigenes JSON-Objekt, um ihn zu prüfen. Formatieren Sie ihn vor dem Speichern nicht um.
  • Der Block license ist eine bequeme Zusammenfassung. Verlassen Sie sich beim Schützen von Funktionen nicht darauf — er ist nicht einzeln signiert. Der signierte Lease ist die maßgebliche Quelle; die Zusammenfassung dient nur der Anzeige.

status behandeln

status ist das Feld, auf dem Sie verzweigen. Werte:

statusBedeutungWas zu tun ist
okAktiviert; lease ist vorhandenLease prüfen und zwischenspeichern; Funktionen freischalten
not_foundSchlüssel unbekannt oder falsches Produkt„Schlüssel nicht erkannt“ anzeigen; im Modus Free bleiben
revokedSchlüssel wurde widerrufenIn den Modus Free zurückfallen
expiredLizenz (oder Testversion) ist abgelaufenIn den Modus Free zurückfallen; zur Verlängerung auffordern
seat_limitAlle Plätze dieses Schlüssels sind belegtBenutzer auffordern, auf einer anderen Maschine einen Platz freizugeben

Nur ok liefert einen lease. Fail-closed: Behandeln Sie jeden Status außer ok, jeden HTTP-Code außerhalb von 2xx, ein 429, einen fehlerhaften Body oder einen Lease, der die Prüfung nicht besteht, als nicht lizenziert. Fallen Sie bei einem Fehler niemals in einen freigeschalteten Zustand durch.

Plätze und Idempotenz

Plätze werden serverseitig durchgesetzt. Die seats-Anzahl des Schlüssels ist die Obergrenze; used sagt Ihnen, wie viele Maschinen aktuell einen Platz halten. Das erneute Aktivieren einer Maschine, die bereits an den Schlüssel gebunden ist, verbraucht keinen weiteren Platz — der Server schlüsselt nach (key, machineId), sodass ein erneuter Aufruf von /v1/activate für dieselbe Maschine idempotent ist und lediglich den Lease aktualisiert. Deshalb muss die Maschinen-ID stabil sein (nächster Abschnitt). Ändert sie sich, wirkt die Maschine neu, belegt einen frischen Platz, und der Benutzer stößt auf seat_limit.

Die Maschinen-ID

machineId ist Ihre Kennung für das Gerät — Sie wählen sie. Die offiziellen SDKs berechnen einen gesalzenen Node-Lock-Fingerabdruck (ihr internes KRM1-Schema) aus Hardware- und Betriebssystemsignalen, aber der Server behandelt machineId als opaken String. Ein Client ohne SDK muss diesem Schema nicht entsprechen. Sie brauchen lediglich eine ID, die:

  • Stabil über Neustarts, Updates und Reboots hinweg ist. Ändert sie sich, wirkt die Maschine neu, verbraucht einen Platz und läuft schließlich in seat_limit. Das ist die mit Abstand wichtigste Eigenschaft.
  • Pro Maschine vergeben wird, damit das Zählen der Plätze sinnvoll ist.
  • Nicht trivial fälschbar ist durch einen Endbenutzer, der eine Aktivierung auf viele Maschinen klonen möchte (ein Hash, kein Wert, den er eintippen kann).

Ein gutes Rezept: Sammeln Sie ein oder zwei stabile Betriebssystem-/Hardware-Kennungen (eine Maschinen-GUID, eine primäre MAC-Adresse, eine Festplattenseriennummer oder eine systemd-machine-id), verketten Sie sie mit einem konstanten, eigenen Salt-String, hashen Sie mit SHA-256 und kodieren Sie den Digest hex oder base64. Berechnen Sie sie einmal und verwenden Sie exakt denselben String jedes Mal wieder, wenn Sie aktivieren, validieren, prüfen oder einen Platz freigeben. Speichern Sie sie zusammen mit dem zwischengespeicherten Lease, damit Sie später vergleichen können.

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

Halten Sie sie für eine gegebene Installation dauerhaft konsistent. Mehr braucht der Server nicht.

Den Lease offline prüfen

Das ist der Teil ohne Abkürzungen. Der Lease ist mit dem privaten RSA-Schlüssel des Anbieters signiert, der dessen Server nie verlässt. Sie prüfen ihn mit dem passenden öffentlichen Schlüssel, den der Anbieter Ihnen gibt (Tab Integration im Dashboard oder GET $BASE/admin/public-key mit einem Admin-Token) als base64-kodierten SubjectPublicKeyInfo-String (SPKI). Dieser Schlüssel ist kein Geheimnis — er kann nur prüfen, nie signieren —, also betten Sie ihn in Ihre Binärdatei ein.

Die Prüfung lautet: Rekonstruieren Sie die exakten Bytes, die signiert wurden, und verifizieren Sie dann die Signatur darüber mit RSA. Die signierten Bytes sind nicht das Lease-JSON — sie sind ein kanonischer String, der aus bestimmten Feldern in einer bestimmten Reihenfolge zusammengesetzt wird.

Die kanonische Payload — byte-exakt hinbekommen

Der signierte String ist (Spezifikationsversion krlease1):

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

Anschließend werden, bedingt und in genau dieser Reihenfolge, zwei Suffixe angehängt:

  1. |ent=<entitlements> — wird nur dann angehängt, wenn der Lease ein nicht leeres entitlements-Objekt hat. Die Entitlements werden deterministisch serialisiert: Schlüssel in ordinaler (Byte-/Codepoint-)Reihenfolge sortiert, jeder als key=value dargestellt, kommagetrennt. Z. B. {"max-projects":"10","export":"true"} → export=true,max-projects=10.
  2. |trial — wird nur dann angehängt, wenn das Feld trial des Lease true ist. Ist es false, wird nichts angehängt.

Der gesamte String wird UTF-8-kodiert, und die Signatur ist RSA PKCS#1 v1.5 über SHA-256, base64-kodiert im Feld signature des Lease.

Dieser Reihenfolgefehler ist real — achten Sie darauf. |ent= kommt vor |trial. Vertauschen Sie die Reihenfolge, lassen Sie ein bedingtes Suffix weg, das vorhanden sein müsste, fügen Sie eines hinzu, das nicht hingehört, oder formatieren Sie ein Datum um, und die rekonstruierten Bytes weichen um ein einziges Zeichen ab — und die Signaturprüfung schlägt stillschweigend fehl. Es gibt keine Teilübereinstimmung. Genau dieser Reihenfolgefehler hat die SDKs während der Entwicklung erwischt; deshalb ist die Reihenfolge so präzise ausbuchstabiert. Wenn ein Lease, von dem Sie wissen, dass er gut ist, nicht verifiziert, ist der kanonische String die erste Stelle, an der Sie nachsehen sollten.

Kritische Details, über die Leute stolpern:

  • Verwenden Sie die Datums-Strings unverändert aus dem JSON. licenseExpiryUtc und leaseExpiresUtc sind Round-Trip-ISO-8601-Strings wie 2026-10-11T09:14:22.1030000Z (7 Nachkommastellen). Parsen und re-serialisieren Sie sie nicht für den kanonischen String — kopieren Sie die exakten Zeichen aus dem Lease. (Sie parsen sie separat, später, nur um sie mit „jetzt“ zu vergleichen.)
  • licenseExpiryUtc kann bei einer unbefristeten Lizenz fehlen/null sein. Setzen Sie in diesem Fall den leeren String an diese Stelle — die beiden |-Trennzeichen darum herum erscheinen weiterhin: ...|<tier>||<leaseExpiresUtc>.
  • Leere Entitlements = gar kein |ent=. Ein Lease ohne Entitlements signiert über exakt dieselben Bytes wie einer, der ausgestellt wurde, bevor es Entitlements gab. Hängen Sie |ent= nur an, wenn das Objekt vorhanden und nicht leer ist.

Konkretes Beispiel (Go — portieren Sie es in Ihre Sprache)

Gos Standardbibliothek deckt alles ab. Die Logik lässt sich direkt nach Rust (rsa + sha2), PHP (openssl_verify mit OPENSSL_ALGO_SHA256), Ruby (OpenSSL::PKey::RSA#verify), C++ (OpenSSL EVP_DigestVerify) usw. portieren — nur die Krypto-Aufrufe ändern sich.

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"` // Zeiger: kann null sein
	LeaseExpiresUtc  string            `json:"leaseExpiresUtc"`
	Entitlements     map[string]string `json:"entitlements"`
	Trial            bool              `json:"trial"`
	Signature        string            `json:"signature"`
}

// Die EXAKTEN Bytes rekonstruieren, die signiert wurden. Die Reihenfolge ist entscheidend.
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 { // leerer String bei unbefristeter Lizenz (null)
		b.WriteString(*l.LicenseExpiryUtc)
	}
	b.WriteString("|")
	b.WriteString(l.LeaseExpiresUtc)

	// |ent=  ZUERST, nur wenn nicht leer. Schlüssel ordinal sortiert, k=v, kommagetrennt.
	if len(l.Entitlements) > 0 {
		keys := make([]string, 0, len(l.Entitlements))
		for k := range l.Entitlements {
			keys = append(keys, k)
		}
		sort.Strings(keys) // Gos sort.Strings sortiert ordinal (byteweise) — entspricht der Spezifikation
		parts := make([]string, len(keys))
		for i, k := range keys {
			parts[i] = k + "=" + l.Entitlements[k]
		}
		b.WriteString("|ent=" + strings.Join(parts, ","))
	}

	// |trial  ZULETZT, nur wenn true.
	if l.Trial {
		b.WriteString("|trial")
	}
	return []byte(b.String())
}

// publicKeyB64 ist der base64-kodierte SubjectPublicKeyInfo (SPKI) des Anbieters.
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 // fail-closed
	}

	// 1. Öffentlichen Schlüssel laden (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. Signatur über die kanonischen Bytes prüfen (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") // fail-closed
	}

	// 3. Semantische Prüfungen — alle müssen bestehen, sonst fail-closed.
	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") // Zeit, online neu zu aktivieren
	}
	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 // lizenziert — l.Tier / l.Entitlements lesen, um Funktionen zu schützen
}

Die Prüf-Checkliste (beliebige Sprache)

  1. Parsen Sie das Lease-JSON.
  2. Rekonstruieren Sie den kanonischen String exakt — achten Sie auf |ent= vor |trial, die Leerstring-Stelle für ein null licenseExpiryUtc, unveränderte Datumsangaben und ordinal sortierte Entitlement-Schlüssel.
  3. Dekodieren Sie signature aus base64, dekodieren Sie den öffentlichen SPKI-Schlüssel aus base64 und verifizieren Sie mit RSA (PKCS#1 v1.5 / SHA-256).
  4. Prüfen Sie, dass product Ihrem Produkt entspricht.
  5. Prüfen Sie, dass machineId der Maschinen-ID entspricht, die Sie bei der Aktivierung gespeichert haben.
  6. Prüfen Sie, dass leaseExpiresUtc in der Zukunft liegt (die Offline-Kulanzfrist — wenn sie verstreicht, online neu aktivieren).
  7. Prüfen Sie, dass licenseExpiryUtc, falls vorhanden, in der Zukunft liegt.
  8. Fail-closed bei allem — ein Parse-Fehler, eine falsche Signatur, eine Abweichung, ein Ablauf, eine Uhr, der Sie nicht trauen können. Nur ein Lease, der jeden Schritt besteht, ist lizenziert.

Sobald er besteht, lesen Sie tier für die Edition und entitlements für die Schutzprüfungen pro Funktion.

Eine Maschine deaktivieren

Um den Platz freizugeben, den diese Maschine hält (z. B. vor der Deinstallation oder bei der Migration auf neue Hardware), senden Sie per POST an /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"}'

Antwort: {"status":"ok"}. Der Platz wird freigegeben und used sinkt, sodass eine andere Maschine aktivieren kann. Löschen Sie gleichzeitig Ihren lokal zwischengespeicherten Lease.

Erneut validieren und aktualisieren

  • POST /v1/validate prüft einen Schlüssel + Maschine erneut gegen den aktuellen Serverzustand — es erkennt Widerruf und Ablauf, die nach der Aktivierung eingetreten sind — ohne einen neuen Platz zu belegen. Es nimmt denselben Request-Body wie /v1/activate entgegen und liefert dieselbe Antwortform (einschließlich eines frischen lease, solange der Status ok ist). Verwenden Sie es als periodische Zustandsprüfung.
  • Erneutes Aktivieren (/v1/activate) auf einer bereits gebundenen Maschine ist idempotent und aktualisiert den Lease mit einem neuen leaseExpiresUtc. In der Praxis ist das, was die meisten Clients nach Zeitplan tun.

Leases sind kurzlebig — die Standard-Kulanzfrist beträgt 14 Tage (der Anbieter kann sie konfigurieren). Ein Online-Client sollte daher periodisch neu aktivieren (oder validieren) — mit komfortablem Abstand vor dem leaseExpiresUtc des aktuellen Lease —, um Widerrufe mitzubekommen und einen frischen Lease im Cache zu halten. Zwischen den Aktualisierungen prüfen Sie den zwischengespeicherten Lease bei jedem Start offline und schützen Funktionen auf dieser Basis.

Offline-/netzwerkisolierte (air-gapped) Maschinen

Für eine Maschine, die den Service nie erreichen kann, erzeugt der Anbieter außerhalb des normalen Kanals einen langlebigen Lease für Sie. Ein Operator ruft auf (Admin-Token erforderlich, also ist das der Schritt des Anbieters, nicht Ihres Clients):

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}'

was { "machineId": "...", "ttlDays": 365, "lease": "{...signed lease JSON...}" } zurückgibt. Das Feld days ist standardmäßig 365 — eine viel längere TTL als die Kulanzfrist eines Online-Lease, da die Maschine nie aktualisieren wird.

Sie ermitteln zuerst die Maschinen-ID der Zielmaschine (berechnen Sie sie exakt so wie Ihr Client und übergeben Sie sie dem Anbieter), liefern den zurückgegebenen lease-String per Datei oder USB an die Maschine und prüfen ihn mit exakt demselben Code wie einen Online-Lease — dieselbe kanonische Payload, dieselbe Signaturprüfung, dieselben Produkt-/Maschinen-/Ablaufprüfungen. Ein Offline-Lease ist ein gewöhnlicher Lease mit einem langen leaseExpiresUtc; an der Prüfung ändert sich nichts. (Auf diese Weise erzeugte Offline-Leases sind nicht als trial markiert, also gilt kein |trial-Suffix.)

Eine Anmerkung zu Offline-Lizenzdateien

Aktivierung und Leases sind der Pfad „online, dann zwischengespeichert“. Keyright unterstützt außerdem vollständig offline nutzbare Lizenzdateien — ein signiertes JSON-Dokument (license.json) ganz ohne Aktivierungs-Roundtrip. Seine signierte kanonische Payload ist eine andere, einfachere Spezifikation (Version kr1):

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

wobei der optionale kr1:-Block semikolongetrennte Felder product=, id=, machine=, td= und ent= trägt (dieselbe ordinal sortierte, kommagetrennte Entitlement-Kodierung). Dieselbe Kryptografie — RSA PKCS#1 v1.5 / SHA-256, geprüft gegen denselben öffentlichen SPKI-Schlüssel. Wenn Ihr Anbieter Ihnen Lizenzdateien liefert, statt die Aktivierung zu verwenden, prüfen Sie sie auf dieselbe Weise: Rekonstruieren Sie diesen kanonischen String und verifizieren Sie mit RSA. Die meisten Integrationen ohne SDK brauchen nur den Lease-Pfad oben; greifen Sie zur Lizenzdatei-Prüfung nur, wenn Ihr Anbieter Dateien direkt verteilt.

Siehe auch

  • Erste Schritte — die Anbietereinrichtung (Produkt anlegen, öffentlichen Schlüssel holen, Schlüssel ausstellen).
  • Aktivierung & Lease-Lebenszyklus — wie Aktivierung, Leases, Kulanzfristen und Aktualisierung zusammenspielen.
  • Sicherheit & Leases — das Signaturmodell, warum der öffentliche Schlüssel sicher eingebettet werden kann, und die kanonischen Formate im Detail.
  • HTTP-API-Referenz — die vollständige Endpunktübersicht.