Skip to content
← Alle Beiträge
· Delta1 Labs CachingKeyright

Bedingter Lizenz-Refresh mit ETag

Ein Keyright-Client aktualisiert seinen zwischengespeicherten Lease über einen Timer, und die überwältigende Mehrheit dieser Refreshes beantwortet dieselbe Frage mit derselben Antwort: nichts hat sich geändert. Den vollständigen signierten Lease jedes Mal erneut herunterzuladen verschwendet Bandbreite und wiederholt grundlos eine Signaturprüfung. HTTP besitzt bereits das passende Werkzeug für „hat sich diese Ressource seit meinem letzten Besuch geändert?" – das ETag und das bedingte GET. Dieser Beitrag zeigt, wie der Issuing Service jede Lizenzantwort mit einem starken Validator kennzeichnet, wie das SDK If-None-Match sendet, um einen Refresh in ein günstiges 304 Not Modified zu verwandeln, und welche Korrektheitsregeln verhindern, dass ein 304 jemals eine Sperrung verbirgt.

Ein Keyright-Client ruft nicht bei jeder Lizenzprüfung nach Hause. Er aktiviert sich einmal, legt den signierten Lease im Cache ab, und von da an ist jedes Validate() eine lokale, offline durchgeführte Operation gegen den eingebetteten öffentlichen Schlüssel. Was tatsächlich mit dem Issuing Service spricht, ist der Hintergrund-Refresh: über einen Timer – typischerweise alle paar Minuten bis paar Stunden – holt das SDK den Lease erneut, damit eine Verlängerung, eine Entitlement-Änderung oder eine Sperrung erfasst wird, ohne auf einen Neustart warten zu müssen.

Hier das Wesentliche an dieser Refresh-Schleife: Fast jede ihrer Iterationen ist ein Nichts-Tun. Eine Lizenz ist eine sich langsam verändernde Ressource. Sie ändert sich, wenn jemand verlängert, upgradet, einen Seat überträgt oder gesperrt wird – Ereignisse, die Tage oder Wochen auseinanderliegen. Zwischen diesen Ereignissen fragt ein Client, der alle fünf Minuten aktualisiert, den Service hunderte Male „was ist der aktuelle Zustand dieser Lizenz?” und erhält jedes einzelne Mal Byte für Byte denselben signierten Lease zurück. Jede dieser Antworten ist ein vollständiger Body, den der Service serialisiert und signiert, über das Netz geschoben hat, den der Client dann base64-dekodiert und über den er eine RSA-Prüfung ausgeführt hat – alles, um zu bestätigen, was er bereits wusste.

HTTP besitzt seit 1999 die passende Primitive dafür. Es ist das bedingte GET, aufgebaut auf dem Antwort-Header ETag und dem Anfrage-Header If-None-Match, und es in den Refresh-Pfad einzubauen verwandelt den häufigen Fall – nichts hat sich geändert – in einen reinen Header-Roundtrip, der 304 Not Modified mit leerem Body zurückgibt.

Kernaussage: Lassen Sie Ihren Issuing Service jede Lizenzantwort mit einem starken ETag versehen, das aus der Version und der Signatur der Lizenz abgeleitet ist. Lassen Sie das SDK dieses Tag merken und es beim nächsten Refresh als If-None-Match zurücksenden. Wenn sich nichts geändert hat, antwortet der Service mit 304 Not Modified ohne Body, der Client behält seinen zwischengespeicherten Lease unangetastet, und Sie haben einen vollständigen Download der signierten Nutzlast plus eine Signaturprüfung durch einige hundert Byte Header ersetzt – ohne jemals zuzulassen, dass ein veralteter Cache eine Sperrung verbirgt.

Wie das Abrufen einer Lizenz heute aussieht

Nimmt man das SDK weg, ist ein Refresh ein gewöhnliches HTTP-GET. Der Client fragt nach dem aktuellen Lease für einen Schlüssel; der Service gibt das signierte Dokument zurück.

GET /v1/licenses/current HTTP/1.1
Host: keyright.example.com
X-Keyright-Product: acme-suite
Authorization: Bearer AK-9f3c…            ← das Aktivierungstoken aus dem initialen Handshake

HTTP/1.1 200 OK
Content-Type: application/vnd.keyright.lease+json
Content-Length: 1184

{ "lease": "eyJhbGciOi…", "signature": "MEUCIQ…", "edition": "pro", "expiresAt": "2027-01-01T00:00:00Z" }

Dieser lease-Blob ist die kanonische, signierte Nutzlast, die der Client offline verifiziert. Mit über einem Kilobyte pro Aufruf, multipliziert mit einer Flotte von Clients, mal einem Refresh alle paar Minuten, mal der Tatsache, dass der Inhalt zwischen Lizenzereignissen identisch ist, ist das reine Verschwendung. Der Service hat echte Arbeit geleistet, um einen Body zu erzeugen, den niemand brauchte.

Das ETag: ein Fingerabdruck, den der Client zurückzitieren kann

Ein ETag („Entity-Tag”) ist ein opaker Validator, den der Server an eine Antwort anhängt. Sein einziger Vertrag ist dieser: Tragen zwei Antworten für dieselbe URL dasselbe ETag, sind ihre Repräsentationen identisch; ändert sich die Ressource, muss sich das ETag ändern. Der Client behandelt es als Blackbox – er parst es nie – und zitiert es bei der nächsten Anfrage einfach zurück, um zu fragen „hast du immer noch genau das?”.

Für eine Lizenz möchten Sie nicht den gesamten Antwort-Body hashen, um das Tag zu erzeugen (das funktioniert, kostet aber bei jeder Anfrage einen Hash über die Nutzlast). Sie haben bereits zwei Felder, die sich genau dann ändern, wenn sich die Lizenz ändert: eine monotone Version, die der Issuing Service bei jeder Mutation hochzählt, und die Signatur selbst. Kombinieren Sie beide zu einem starken Validator:

ETag: "v47-3b9a1f"      ← Lizenzversion 47, erste Bytes der Signatur, starkes Tag

Dies ist ein starkes ETag (ohne W/-Präfix), was hier die richtige Wahl ist: Eine bedingte Anfrage sollte nur dann übereinstimmen, wenn die Bytes wirklich identisch sind, denn der Client wird bei einer Übereinstimmung die Prüfung einer neuen Signatur überspringen. Ein schwaches Tag (W/"…"), das nur semantische Äquivalenz verspricht, ist hierfür falsch – „semantisch äquivalent” ist nicht gut genug, wenn der Unterschied eine Sperrung sein könnte.

Der Service berechnet das Tag aus Feldern, die er ohnehin zur Hand hat, sodass das Kennzeichnen einer Antwort im Wesentlichen kostenlos ist, und entscheidend: Das Tag ändert sich in dem Augenblick, in dem sich irgendetwas an der Lizenz ändert: Eine Verlängerung zählt die Version hoch, eine Sperrung zählt die Version hoch, eine Entitlement-Änderung zählt die Version hoch.

Das bedingte GET: If-None-Match verwandelt einen Refresh in ein 304

Sobald der Client ein ETag gesehen hat, sendet der nächste Refresh es in einem If-None-Match-Header. Die Semantik ist präzise: „gib die vollständige Ressource nur dann zurück, wenn ihr aktuelles ETag mit keinem von diesen übereinstimmt; andernfalls sag mir, dass sie unverändert ist.”

GET /v1/licenses/current HTTP/1.1
Host: keyright.example.com
X-Keyright-Product: acme-suite
Authorization: Bearer AK-9f3c…
If-None-Match: "v47-3b9a1f"             ← ich habe bereits genau das; du auch noch?

HTTP/1.1 304 Not Modified
ETag: "v47-3b9a1f"
Cache-Control: max-age=300

Kein Body. Der Client liest das 304, versteht „mein zwischengespeicherter Lease ist weiterhin aktuell”, setzt seinen Refresh-Timer zurück und tut nichts weiter – keine Dekodierung, keine Signaturprüfung, keine Zustandsänderung. Wenn sich die Lizenz doch geändert hat, scheitert die Übereinstimmung und der Service antwortet genau wie zuvor, mit einem 200, dem neuen Body und einem neuen ETag, das der Client für das nächste Mal speichert.

SDK clientissuing serviceFall A — nichts hat sich geändertGET /v1/licenses/current · If-None-Match: "v47-3b9a1f"304 Not Modified · (kein Body) · ETag "v47-3b9a1f"Lease im Cache behalten · keine Prüfung · Timer zurücksetzenFall B — die Lizenz hat sich geändertGET /v1/licenses/current · If-None-Match: "v47-3b9a1f"200 OK · signierter Lease · ETag "v48-c71d02"Signatur prüfen · Cache tauschen · neues ETag speichern

Den bedingten Refresh im SDK-Client implementieren

Wenn Sie den Keyright-Client über die Typed-Client-Registrierung konsumieren, sind bedingte Anfragen etwas, das Sie im Refresh-Pfad ergänzen: Das SDK speichert das letzte ETag neben dem zwischengespeicherten Lease und sendet es beim nächsten Poll. Hier die Form dieses Handlers, geschrieben gegen HttpClient, damit die Mechanik explizit ist.

public sealed class ConditionalLeaseFetcher(HttpClient http)
{
    // Der Validator, den der Service uns zuletzt gab, neben dem zwischengespeicherten Lease gehalten.
    private string? _etag;
    private SignedLease? _cached;

    public async Task<RefreshResult> RefreshAsync(CancellationToken ct)
    {
        using var req = new HttpRequestMessage(HttpMethod.Get, "/v1/licenses/current");

        // Zitiere das gespeicherte Tag zurück. EntityTagHeaderValue parst die Form in Anführungszeichen.
        if (_etag is not null)
            req.Headers.IfNoneMatch.Add(EntityTagHeaderValue.Parse(_etag));

        using var res = await http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead, ct);

        if (res.StatusCode == HttpStatusCode.NotModified)
        {
            // Der häufige Fall: Der Body ist laut Spezifikation leer. Behalte, was wir haben, unangetastet.
            return RefreshResult.Unchanged(_cached!);
        }

        res.EnsureSuccessStatusCode();

        // 200: eine wirklich neue Repräsentation. Erst jetzt zahlen wir für Dekodierung + Prüfung.
        var body  = await res.Content.ReadFromJsonAsync<LeaseResponse>(ct)
                    ?? throw new KeyrightException("empty lease body");
        var lease = SignedLease.VerifyAndParse(body, _publicKey);   // die RSA-Prüfung passiert hier

        _cached = lease;
        _etag   = res.Headers.ETag?.ToString();   // speichere den neuen Validator für das nächste Mal
        return RefreshResult.Updated(lease);
    }
}

Die beiden Zweige sind der ganze Kern. Ein 304 gibt RefreshResult.Unchanged zurück und berührt nie den Signaturpfad – das Teuerste, was ein Refresh tun kann, ist genau das Eine, das der schnelle Pfad überspringt. Ein 200 wird genau so behandelt, wie es ein Abruf ohne Cache täte: verifizieren, den Cache tauschen, das frische ETag speichern. Es gibt keinen dritten Zustand, den man falsch machen könnte.

Beachten Sie HttpCompletionOption.ResponseHeadersRead: Bei einem 304 gibt es keinen Body zu puffern, daher möchten Sie den Status aus den Headern inspizieren, bevor Sie überhaupt entscheiden, ob Content gelesen wird.

Lassen Sie max-age nicht die lokale Auswertung ersetzen

Das Cache-Control: max-age=300 der Antwort sagt dem Client, dass er den zwischengespeicherten Lease bis zu fünf Minuten lang ausliefern darf, ohne erneut nachzufragen – das setzt die Untergrenze Ihres Refresh-Intervalls. Was es nicht tun darf, ist den lokalen, zeitabhängigen Teil einer Lizenzprüfung zu unterdrücken. Ein Lease kann ein expiresAt tragen, das innerhalb des max-age-Fensters liegt; in dem Moment, in dem die Wanduhr es überschreitet, ist das Entitlement weg, auch wenn die zwischengespeicherten Bytes nach HTTPs Definition noch „frisch” sind. Das ist dieselbe Trennung, die in der Hot-Path-Caching-Arbeit behandelt wird: Cachen Sie die Signaturprüfung (das ETag schützt diese), cachen Sie niemals die Auswertung zum aktuellen Zeitpunkt. Validate() wertet den Ablauf stets gegen die validierte Uhr neu aus, ganz gleich, wie frisch der HTTP-Cache die Repräsentation glaubt.

Die Korrektheitsregel, die dies sicher macht

Eine bedingte Anfrage ist nur so sicher wie die Garantie, dass sich das ETag immer dann ändert, wenn sich die Lizenz ändert. Machen Sie das falsch, und ein 304 wird zur Lüge – der Client hält einen Lease, den der Service bereits gesperrt hat, und antwortet weiter mit 304, weil sich das Tag nie bewegt hat. Daher ist die Regel auf der Serverseite absolut:

Jede Mutation, die ändert, was die Lizenz gewährt, muss das ETag ändern. Da das Tag aus der monotonen Version abgeleitet wird und jede Mutation die Version hochzählt, ergibt sich das von selbst: Eine Sperrung zählt die Version hoch wie jede andere Änderung, das nächste If-None-Match findet keine Übereinstimmung, und der Client erhält ein 200, das den nun gesperrten Zustand trägt (der bei der Prüfung auf den Community-Edition-Fallback auflöst). Es gibt keinen Pfad, auf dem eine laufende Lizenzänderung durch ein veraltetes Tag maskiert wird, sofern die Version die alleinige Quelle der Wahrheit und das Tag stark, nicht schwach, ist.

Der umgekehrte Fehler – das Tag ändert sich, obwohl sich die Lizenz nicht geändert hat – ist harmlos. Er bedeutet lediglich gelegentlich ein unnötiges 200, dieselben Kosten, die Sie zuvor bei jeder Anfrage zahlten. Bedingte Anfragen degradieren in Richtung „lade das Ganze herunter”, niemals in Richtung „liefere etwas Veraltetes aus”.

Es mit curl testen

Sie können den gesamten Austausch von der Kommandozeile aus beobachten, was der schnellste Weg ist, um zu bestätigen, dass Ihr Service korrekt kennzeichnet, bevor Sie das SDK anfassen. Der erste Abruf erfasst das Tag; der zweite sendet es zurück.

$ curl -s -D - -H "Authorization: Bearer AK-9f3c…" \
       https://keyright.example.com/v1/licenses/current -o /dev/null | grep -i etag
ETag: "v47-3b9a1f"

$ curl -s -D - -H "Authorization: Bearer AK-9f3c…" \
       -H 'If-None-Match: "v47-3b9a1f"' \
       https://keyright.example.com/v1/licenses/current -o /dev/null | head -1
HTTP/1.1 304 Not Modified

Ein 304 beim zweiten Aufruf beweist, dass der Roundtrip funktioniert. Erzwingen Sie nun eine Änderung – verlängern Sie die Lizenz oder zählen Sie ihre Version in Ihrem Test-Harness hoch – und wiederholen Sie den bedingten Aufruf: Sie sollten ein 200, einen neuen Body und ein anderes ETag erhalten. Erhalten Sie ein 200 mit demselben ETag, ist Ihr Tag nicht aus einem Feld abgeleitet, das sich tatsächlich geändert hat; erhalten Sie ein 304 nach einer Sperrung, zählt Ihr Sperrpfad die Version nicht hoch, was ein Korrektheits-Bug ist, kein Cache-Bug.

Ein Fallstrick: Proxies und das Entfernen von Headern

Wenn Ihre Clients den Issuing Service über einen Reverse-Proxy oder ein CDN erreichen, stellen Sie sicher, dass er If-None-Match stromaufwärts weiterleitet und die bedingte Anfrage nicht selbst aus einem Cache beantwortet, der nichts von der Sperrung weiß. Eine Lizenzantwort sollte mit Cache-Control: private gekennzeichnet werden, genau damit gemeinsame Caches sie nicht speichern; die bedingte Validierung gehört zwischen den Client und den Issuing Service, nicht in einen Vermittler, der keine Ahnung hat, dass eine Lizenz zurückgezogen wurde. Halten Sie den Validator Ende-zu-Ende, und das 304 bedeutet genau das, was Sie denken.

Das ist der gesamte Mechanismus. Die Refresh-Schleife läuft weiter auf ihrem Timer, erfasst weiterhin jede Verlängerung und Sperrung rechtzeitig und verifiziert weiterhin jeden wirklich neuen Lease – aber der überwältigend häufige Fall, „nichts hat sich geändert, seit ich zuletzt gefragt habe”, kostet nun einige hundert Byte Header und das Lesen einer Statuszeile statt eines Downloads der signierten Nutzlast und einer Prüfung mit öffentlichem Schlüssel. Die Lizenz hat sich nicht geändert, also leistet der Client nicht die Arbeit, so zu tun, als hätte sie es vielleicht getan.

Nebula.NET testen

Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.