KeyWarden.Sdk 1.2.2

KeyWarden.Sdk

The official .NET client for Key-Warden. Validate a software licence online — seat-aware, revocation-aware — or verify a signed token offline against your embedded public key, with no network round-trip.

Targets net8.0 and netstandard2.0 (so it runs on .NET Framework 4.6.1+, .NET Core, .NET 5–8, Xamarin, Unity). Ed25519 verification is provided by BouncyCastle.Cryptography.

dotnet add package KeyWarden.Sdk

Validate online

The authoritative check. Ask the platform whether a licence is good right now.

using KeyWarden;

var res = await KeyWardenClient.ValidateAsync(customerLicenceKey, new ValidateOptions
{
    ApimKey   = Environment.GetEnvironmentVariable("KW_APIM_KEY"),   // your APIM subscription key
    ClientKey = Environment.GetEnvironmentVariable("KW_CLIENT_KEY"), // your validation key
    MachineId = KeyWardenClient.MachineIdFrom(Environment.MachineName, userId), // stable, hashed your side
});

if (!res.Valid) throw new Exception($"licence not valid: {res.Reason}");
// res.Token is a freshly signed proof - cache it for the offline path below.

A Valid == false (e.g. revoked, expired, seat_limit_exceeded) is data, not an exception. A wrong ClientKey throws a KeyWardenError with Code == "unauthorized_client" — that's your auth failing, and your customer should never see it as a licence problem.

Verify offline

No connection? Verify a token you already hold against your public key — the 32-byte raw key from your vendor console. Pure and synchronous.

var check = KeyWardenClient.VerifyToken(cachedToken, publicKeyBase64);
if (!check.Valid) LockFeatures(check.Reason); // "bad_signature" | "expired" | ...

The token is header.body.signature (compact JWT style) and the Ed25519 signature covers the exact bytes header.body. This client verifies over those bytes — it never decodes-then-reverifies, which is the one mistake that silently breaks offline checks. Expiry is honoured within the offline grace window you set at mint time.

Online, with an offline fallback

The pattern most desktop apps want: online is authoritative; if the network is down, keep working within grace.

var res = await KeyWardenClient.ValidateOrVerifyAsync(customerLicenceKey, new ValidateOrVerifyOptions
{
    ApimKey = apimKey, ClientKey = clientKey, MachineId = machineId,
    CachedToken = lastGoodToken,   // from a previous ValidateAsync
    PublicKey   = publicKeyBase64,
});
// res.Source == "online" | "offline"

A rejected ClientKey (401) is never masked by the offline path — only a genuine reachability failure falls back.

API

Any real failure (bad credentials, unreachable gateway, server error) throws KeyWardenError, which carries .Code and .Status.

Verify the build yourself

The repository ships a console self-test that mints tokens exactly the way the platform signs them, then runs the same 16 checks used to certify the Node and Python clients:

dotnet run --project selftest/KeyWarden.Sdk.SelfTest
#   16 passed, 0 failed

Security notes

• Your private signing key never leaves Key-Warden's Key Vault. You embed only the 32-byte public half.
• MachineId is hashed by the platform, but send an opaque, stable id — not a raw MAC address or a hostname you wouldn't want logged. MachineIdFrom() hashes on your side too.
• Two independent credentials gate every online call: the APIM subscription key gets you to the gateway, the validation key authenticates you as the vendor. A leaked validation key can be rotated without reissuing a single customer licence.

Code protection (Seal / Unlock / Unseal)

Lock part of your product so it only runs for a valid, activated licence. Get your content key (base64) from the vendor console → Protect your code.

// Build time — seal a file once:
var blob = KeyWardenClient.Seal(File.ReadAllBytes("secret.dll"), MyContentKeyBase64);
File.WriteAllText("secret.sealed", blob);   // ship this instead

// Runtime — the key rides in the validate token as `ck`, machine-bound:
var res  = await KeyWardenClient.ValidateAsync(licence,
             new ValidateOptions { ApimKey = apim, ClientKey = ck, MachineId = mid });
byte[] key  = KeyWardenClient.UnlockFromToken(res.Token, mid);   // content key
byte[] code = KeyWardenClient.Unseal(sealedBlob, key);           // decrypted bytes

// Or a live check every time (real-time revocation):
byte[] key2 = await KeyWardenClient.UnsealOnlineAsync(licence,
                new UnsealOptions { ApimKey = apim, MachineId = mid });

All AES-256-GCM. Unlock needs the SAME MachineId you validate with. A revoked licence stops getting the key.

Licence

MIT.