Anwendungsfälle
Entitlements
Entitlements sind signierte Schlüssel/Wert-Zuweisungen, die in jeder Keyright-Lizenz und jedem Lease mitgeführt werden. Verwenden Sie sie, um Funktionszugriff, numerische Kontingente und die Produktversionen zu steuern, die eine Lizenz ausführt — alles aus einem einzigen Signaturschlüsselpaar, sodass Sie eine neue Hauptversion durch erneutes Ausstellen eines Schlüssels ausliefern, nie durch das Rotieren von Schlüsseln und das Ausliefern eines neuen öffentlichen Schlüssels.
Ziel. Ändern, was ein Kunde tun darf — welche Funktionen er erhält, wie viel von etwas er nutzen darf und welche Versionen Ihres Produkts er ausführen darf — ohne einen neuen Build auszuliefern und ohne jemals Ihre Signaturschlüssel zu rotieren. Entitlements sind der eine Mechanismus hinter allen dreien.
Was ein Entitlement ist
Ein Entitlement ist ein Paar name → value, das Sie an eine Lizenz anhängen. Keyright signiert es mit dem privaten Schlüssel Ihres Tenants in die Lizenz und liefert es auf zwei Wegen, die Ihre Anwendung bereits verifiziert, an die Maschine des Kunden:
- innerhalb der Offline-Lizenzdatei und
- innerhalb des kurzlebigen Online-Aktivierungs-Lease.
Beide sind RSA-signiert und werden gegen den in Ihre Anwendung eingebetteten öffentlichen Schlüssel geprüft, sodass ein Kunde weder ein Entitlement hinzufügen noch eines einschalten noch eine Zahl erhöhen kann — jede Bearbeitung bricht die Signatur, und das SDK verweigert das Ganze. Nichts an einem Entitlement ist geheim; die Sicherheit ist die Signatur, nicht das Verbergen des Werts.
Da jedes SDK (.NET, Node, Python, Java) und das rohe HTTP-Format dieselbe signierte Nutzlast verifizieren, werden dieselben Entitlements über eine Produktlinie mit gemischten Sprachen hinweg auf dieselbe Weise aus einem öffentlichen Schlüssel gelesen.
Das Prinzip: ein Schlüsselpaar, jede Version
Der häufigste Lizenzierungsfehler ist, das Signaturschlüsselpaar an eine Produktversion zu binden — 3.0-Lizenzen unter einem neuen Schlüssel auszustellen und einen neuen öffentlichen Schlüssel im 3.0-Build auszuliefern. Das bricht ältere Builds (sie können den neuen Schlüssel nicht verifizieren), erzwingt die Migration jedes zahlenden Kunden auf einmal und gibt Ihnen keine Steuerung pro Kunde.
Das Modell von Keyright ist das Gegenteil:
Behalten Sie ein Schlüsselpaar für die gesamte Lebensdauer des Produkts. Führen Sie das, was eine Lizenz darf, in signierten Entitlements mit und ändern Sie es durch erneutes Ausstellen des Schlüssels — nie durch das Rotieren von Schlüsseln.
Der öffentliche Schlüssel in Ihrer Anwendung bewegt sich nie. Die Auslieferung von 4.0 rührt ihn nicht an. Ob eine bestimmte Lizenz 4.0 ausführen darf, ist eine Entitlement-Frage, die lokal gegen den Schlüssel beantwortet wird, den Sie bereits einbetten.
Die drei Muster
Lesen Sie Entitlements aus dem aufgelösten LicenseInfo. Das .NET-SDK stellt ein EntitlementSet mit typisierten Zugriffsmethoden bereit; die anderen SDKs stellen das Äquivalent bereit.
1. Funktions-Flags — eine Fähigkeit freischalten
Eine boolesche Zuweisung: an oder aus. IsEnabled akzeptiert true, 1, yes oder enabled.
var info = client.Validate(); // offline, from the cached lease/license
if (info.Entitlements.IsEnabled("feature.pdf_export"))
EnablePdfExport();
Das ist die klassische Freischaltung pro Edition. Für die vollständige Behandlung — Funktionen auf einer Edition definieren, die Bezahlt-vs.-Frei-Schranke, die Kombination mit operativen Funktions-Flags — siehe Funktionen & Editionen schützen.
2. Numerische Kontingente — ein Limit durchsetzen
Eine Zahl, für die der Kunde bezahlt hat: Plätze, Projekte, API-Aufrufe, Geräte. GetLimit parst den Wert und behandelt "unlimited" als praktisch unendlich; der Fallback ist das, was ein nicht lizenzierter oder fehlender Wert erhält (fail-closed).
long maxProjects = info.Entitlements.GetLimit("max_projects", fallback: 3);
if (currentProjectCount >= maxProjects)
throw new QuotaExceeded($"Your plan allows {maxProjects} projects.");
Ändern Sie das Limit eines Kunden, indem Sie seinen Schlüssel mit einem neuen max_projects neu ausstellen — kein Build, kein Schlüsselwechsel.
3. Versionsdurchsetzung — welche Releases eine Lizenz ausführt
Ihre Anwendung kennt ihre eigene Hauptversion. Die Lizenz trägt die höchste Hauptversion, die sie abdeckt. Führen Sie nur auf oder unter dieser Obergrenze aus:
const int runningMajor = 4; // this build's major version
var raw = info.Entitlements.GetRaw("max_major_version"); // e.g. "3" or "4"
int ceiling = int.TryParse(raw, out var m) ? m : 3; // absent => your pre-coverage default
if (runningMajor > ceiling)
ShowUpgradeRequired($"Your license covers up to v{ceiling}.x.");
So liefern Sie eine neue Hauptversion aus, ohne Schlüssel zu rotieren: Eine für die 3.x-Linie verkaufte Lizenz trägt max_major_version: "3" (oder nichts, wenn sie dem Schema vorausgeht), sodass 4.0 sie lokal ablehnt; eine Lizenz, die das 4.0-Upgrade einschließt, trägt "4". Eine höhere Obergrenze läuft weiterhin auf älteren Builds, sodass eine 4.x-Lizenz auf 3.x weiter funktioniert.
max_major_versionist ein Name, den Sie wählen. Nehmen Sie einen beliebigen Schlüssel, auf den sich Ihre Anwendung einigt. Der Wert ist eine schlichte Zeichenkette; parsen Sie ihn so, wie Sie versionieren.
Brauchen Sie feinere Steuerung als „eine Hauptversion”? Wenn Sie nach Release-Datum, Wartungsfenstern oder exakten Versionsbereichen verkaufen — „jedes 2.x-Release”, „alles, was im Jahr nach dem Kauf erscheint”, „was immer erscheint, solange das Abonnement aktiv ist” — verwenden Sie die erstklassige Release-Abdeckung-Engine von Keyright, die den vollständigen Abdeckungssatz aufzeichnet und signiert und die Berechtigung für jede Version beantwortet. Das obige Entitlement ist die leichtgewichtige, hauptversionsgrobe Variante derselben Idee; die Release-Abdeckung ist die präzise.
Entitlements setzen
Auf einer einzelnen Lizenz
Hängen Sie Entitlements an, wenn Sie einen Schlüssel ausstellen (oder aktualisieren) — Dashboard oder die Admin-API:
curl -X POST "https://keyright.example.com/admin/licenses" \
-H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{
"licensee": "Acme Ltd", "product": "your-product", "tier": "pro",
"entitlements": {
"feature.pdf_export": "true",
"max_projects": "10",
"max_major_version": "3"
}
}'
Im Dashboard erscheinen sie im Features-Editor des Issue-license-Drawers als key → value-Zeilen.
Auf einer Editions-/Tier-Vorlage (automatisch vererbt)
Setzen Sie die Standardwerte auf der Edition, damit jeder darunter ausgestellte Schlüssel sie erbt. So machen Sie es für die Zukunft automatisch: Setzen Sie max_major_version heute auf Ihrer aktuellen Edition, und wenn Sie die nächste Hauptversion ausliefern, heben Sie die Vorlage an (oder fügen eine neue Edition hinzu) — jeder danach geprägte Schlüssel trägt die neue Obergrenze, und jeder bereits im Feld befindliche Schlüssel behält, womit er ausgestellt wurde.
curl -X POST "https://keyright.example.com/admin/products/your-product/tiers" \
-H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{ "name": "Pro", "seats": 3,
"entitlements": { "feature.pdf_export": "true", "max_major_version": "3" } }'
Wie Entitlements die Anwendung erreichen
issue/update license ──signs──▶ offline license file ─┐
│ ├─▶ your app verifies against the
└──on activation──▶ signed online lease ────────┘ embedded public key, reads EntitlementSet
- Offline-Lizenzen tragen die Entitlements im signierten Dokument; netzgetrennte Maschinen lesen sie ohne Netzwerk.
- Online-Leases tragen dieselben Entitlements, bei der Aktivierung signiert, sodass der Online-Pfad genau das offenlegt, was der Offline-Pfad tut. Ein Lease erneuert sich gegen den Service, bevor er abläuft — so wird das erneute Ausstellen der Entitlements eines Kunden bei seiner nächsten Erneuerung wirksam, ohne erneute Schlüsseleingabe und ohne Reaktivierung.
Da die Werte in der signierten Nutzlast liegen, scheitert eine manipulierte oder von Hand bearbeitete Datei an der Verifizierung und wird vollständig verweigert — Sie lesen nie ein gefälschtes Entitlement.
Entitlements in jedem SDK lesen
Jedes SDK löst denselben signierten Satz auf. Die Zugriffsmethoden (die Namen können leicht abweichen) sind: eine boolesche Prüfung IsEnabled(name), eine numerische Lesung GetLimit(name, fallback) ("unlimited" ⇒ max), eine rohe Zeichenketten-Lesung und ein Listen-/Zugehörigkeits-Helfer für Zuweisungen mit mehreren Werten.
- .NET —
info.Entitlements.IsEnabled(...),.GetLimit(...),.GetRaw(...),.GetList(...),.IsListed(name, value). - Node / Python / Java — dieselben Lesungen auf den Entitlements der aufgelösten Lizenz.
- HTTP — die Entitlements sind ein JSON-Objekt auf dem signierten Lease / der signierten Lizenz; verifizieren Sie die Signatur und lesen Sie dann das Objekt direkt.
Siehe die sprachspezifischen Leitfäden unter SDK-Integration und das ausführbare Beispiel-Repository (Operation 7 demonstriert alle drei Muster).
Entitlement vs. Funktions-Flag vs. Release-Abdeckung
| Sie möchten … | Verwenden |
|---|---|
| Eine Fähigkeit freischalten, für die ein Kunde bezahlt hat | Entitlement (boolesch) — diese Seite / Funktionen schützen |
| Ein numerisches Limit durchsetzen (Plätze, Projekte, Aufrufe) | Entitlement (GetLimit) |
| Eine ganze Hauptversion schützen, schlicht | Entitlement (max_major_version) |
| Nach Release-Datum / Versionsbereich / Wartungsfenster schützen | Release-Abdeckung |
| Ein Rollout inszenieren, das Sie steuern (kein Kauf) | Ein operatives Funktions-Flag, innerhalb dessen überlagert, was das Entitlement bereits erlaubt |
Prüfen
- Stellen Sie zwei Schlüssel unter demselben Produkt und Schlüsselpaar aus — einen mit
max_major_version: "3", einen mit"4". - Bestätigen Sie in einem Build, dessen Hauptversion
4ist, dass der erste abgelehnt wird („Upgrade erforderlich”) und der zweite läuft — mit demselben öffentlichen Schlüssel in der Anwendung. - Bearbeiten Sie ein gespeichertes Lease / eine gespeicherte Lizenz, um
max_projectszu erhöhen oderfeature.pdf_exporthinzuzufügen; bestätigen Sie, dass das SDK es ablehnt (die Signatur passt nicht mehr). - Stellen Sie einen Schlüssel ohne
max_major_versionaus; bestätigen Sie, dass er sich wie Ihr dokumentierter Standard vor der Abdeckung verhält.