Conditional license refresh with ETag
A Keyright client refreshes its cached lease on a timer, and the overwhelming majority of those refreshes answer the same question with the same answer: nothing changed. Re-downloading the full signed lease each time wastes bandwidth and re-runs a signature verify for no reason. HTTP already has the right tool for "has this resource changed since I last saw it" — the ETag and the conditional GET. This post shows how the issuing service tags each license response with a strong validator, how the SDK sends If-None-Match to turn a refresh into a cheap 304 Not Modified, and the correctness rules that keep a 304 from ever hiding a revocation.
A Keyright client does not call home on every license check. It activates once, caches the signed lease, and from then on every Validate() is a local, offline operation against the embedded public key. What does talk to the issuing service is the background refresh: on a timer — typically every few minutes to a few hours — the SDK re-fetches the lease so that a renewal, an entitlement change, or a revocation is picked up without waiting for a restart.
Here is the thing about that refresh loop: almost every iteration of it is a no-op. A license is a slow-moving resource. It changes when someone renews, upgrades, transfers a seat, or gets revoked — events that happen days or weeks apart. Between those events, a client that refreshes every five minutes asks the service “what is the current state of this license?” hundreds of times and gets back byte-for-byte the same signed lease every single time. Each of those answers is a full response body the service serialized and signed, pushed over the network, that the client then base64-decoded and ran an RSA verify over — all to confirm what it already knew.
HTTP has had the right primitive for this since 1999. It is the conditional GET, built on the ETag response header and the If-None-Match request header, and wiring it into the refresh path turns the common case — nothing changed — into a headers-only round trip that returns 304 Not Modified with an empty body.
Key takeaway: Have your issuing service stamp every license response with a strong ETag derived from the license’s version and signature. Have the SDK remember that tag and send it back as If-None-Match on the next refresh. When nothing has changed the service answers 304 Not Modified with no body, the client keeps its cached lease untouched, and you have replaced a full signed-payload download plus a signature verify with a few hundred bytes of headers — without ever letting a stale cache hide a revocation.
What a license fetch looks like today
Strip the SDK away and a refresh is an ordinary HTTP GET. The client asks for the current lease for a key; the service returns the signed document.
GET /v1/licenses/current HTTP/1.1
Host: keyright.example.com
X-Keyright-Product: acme-suite
Authorization: Bearer AK-9f3c… ← the activation token from the initial 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" }
That lease blob is the canonical, signed payload the client verifies offline. At a kilobyte-plus a shot, times a fleet of clients, times a refresh every few minutes, times the fact that the content is identical between license events, it is pure waste. The service did real work to produce a body nobody needed.
The ETag: a fingerprint the client can quote back
An ETag (“entity tag”) is an opaque validator the server attaches to a response. Its only contract is this: if two responses for the same URL carry the same ETag, their representations are identical; if the resource changes, the ETag must change. The client treats it as a black box — it never parses it — and simply quotes it back on the next request to ask “do you still have exactly this?”.
For a license, you do not want to hash the whole response body to produce the tag (that works, but it costs a hash over the payload on every request). You already have two fields that change if and only if the license changes: a monotonic version the issuing service bumps on every mutation, and the signature itself. Combine them into a strong validator:
ETag: "v47-3b9a1f" ← license version 47, first bytes of the signature, strong tag
This is a strong ETag (no W/ prefix), which is the correct choice here: a conditional request should match only when the bytes are genuinely identical, because the client is going to skip verifying a new signature on a match. A weak tag (W/"…"), which only promises semantic equivalence, is wrong for this — “semantically equivalent” is not good enough when the difference might be a revocation.
The service computes the tag from fields it already has in hand, so tagging a response is essentially free, and crucially the tag changes the instant anything about the license does: a renewal bumps the version, a revocation bumps the version, an entitlement edit bumps the version.
The conditional GET: If-None-Match turns a refresh into a 304
Once the client has seen an ETag, the next refresh sends it in an If-None-Match header. The semantics are precise: “return the full resource only if its current ETag does not match any of these; otherwise tell me it is unchanged.”
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" ← I already have exactly this; do you still?
HTTP/1.1 304 Not Modified
ETag: "v47-3b9a1f"
Cache-Control: max-age=300
No body. The client reads the 304, understands “my cached lease is still current,” resets its refresh timer, and does nothing else — no decode, no signature verify, no state change. When the license has changed, the match fails and the service answers exactly as before, with a 200, the new body, and a new ETag the client stores for next time.
Implementing conditional refresh in the SDK client
If you are consuming the Keyright client through the typed-client registration, conditional requests are something you add in the refresh path — the SDK stores the last ETag alongside the cached lease and sends it on the next poll. Here is the shape of that handler, written against HttpClient so the mechanics are explicit.
public sealed class ConditionalLeaseFetcher(HttpClient http)
{
// The validator the service last gave us, held next to the cached lease.
private string? _etag;
private SignedLease? _cached;
public async Task<RefreshResult> RefreshAsync(CancellationToken ct)
{
using var req = new HttpRequestMessage(HttpMethod.Get, "/v1/licenses/current");
// Quote the stored tag back. EntityTagHeaderValue parses the quoted form for us.
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)
{
// The common case: the body is empty by spec. Keep what we have, untouched.
return RefreshResult.Unchanged(_cached!);
}
res.EnsureSuccessStatusCode();
// 200: a genuinely new representation. Only now do we pay for decode + verify.
var body = await res.Content.ReadFromJsonAsync<LeaseResponse>(ct)
?? throw new KeyrightException("empty lease body");
var lease = SignedLease.VerifyAndParse(body, _publicKey); // RSA verify happens here
_cached = lease;
_etag = res.Headers.ETag?.ToString(); // store the new validator for next time
return RefreshResult.Updated(lease);
}
}
The two branches are the whole point. A 304 returns RefreshResult.Unchanged and never touches the signature path — the single most expensive thing a refresh can do is the one thing the fast path skips. A 200 is treated exactly as an uncached fetch would be: verify, swap the cache, store the fresh ETag. There is no third state to get wrong.
Notice HttpCompletionOption.ResponseHeadersRead: on a 304 there is no body to buffer, so you want to inspect the status from the headers before deciding whether to read content at all.
Do not let max-age replace the local evaluation
The Cache-Control: max-age=300 on the response tells the client it may serve the cached lease without re-asking for up to five minutes — that is what sets the floor on your refresh interval. What it must not do is suppress the local, time-dependent part of a license check. A lease can carry an expiresAt that falls inside the max-age window; the moment the wall clock passes it, the entitlement is gone even though the cached bytes are still “fresh” by HTTP’s definition. This is the same split covered in the hot-path caching work: cache the signature verification (the ETag protects that), never cache the evaluation at the current instant. Validate() always re-evaluates expiry against the validated clock, no matter how fresh the HTTP cache believes the representation to be.
The correctness rule that makes this safe
A conditional request is only as safe as the guarantee that the ETag changes whenever the license does. Get that wrong and a 304 becomes a lie — the client holds a lease the service has already revoked and keeps answering 304 because the tag never moved. So the rule on the service side is absolute:
Any mutation that changes what the license grants must change the ETag. Because the tag is derived from the monotonic version, and every mutation bumps the version, this falls out for free — a revocation increments the version like any other edit, the next If-None-Match fails to match, and the client gets a 200 carrying the now-revoked state (which resolves to the Community Edition fallback on verify). There is no path where a live license change is masked by a stale tag, provided the version is the single source of truth and the tag is strong, not weak.
The reverse failure — the tag changing when the license did not — is harmless. It just means an occasional unnecessary 200, the same cost you were paying on every request before. Conditional requests degrade toward “download the whole thing,” never toward “serve something stale.”
Testing it with curl
You can watch the whole exchange from the command line, which is the fastest way to confirm your service is tagging correctly before you touch the SDK. First fetch captures the tag; the second sends it back.
$ 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
A 304 on the second call proves the round trip works. Now force a change — renew the license, or bump its version in your test harness — and repeat the conditional call: you should get a 200, a new body, and a different ETag. If you get a 200 with the same ETag, your tag is not derived from a field that actually changed; if you get a 304 after a revocation, your revocation path is not bumping the version, which is a correctness bug, not a caching one.
One gotcha: proxies and header stripping
If your clients reach the issuing service through a reverse proxy or CDN, confirm it forwards If-None-Match upstream and does not answer the conditional request itself from a cache that is unaware of revocation. A licensing response should be marked Cache-Control: private precisely so that shared caches do not store it; the conditional validation belongs between the client and the issuing service, not in an intermediary that has no idea a license was pulled. Keep the validator end-to-end and the 304 means exactly what you think it means.
That is the whole mechanism. The refresh loop still runs on its timer, still picks up every renewal and revocation on schedule, and still verifies every genuinely new lease — but the overwhelmingly common case, “nothing changed since I last asked,” now costs a few hundred bytes of headers and a status-line read instead of a signed-payload download and a public-key verify. The license did not change, so the client does not do the work of pretending it might have.
Try Nebula.NET
Harden your .NET code in minutes — start with the free edition.