Wiaoj.Identifiers.Security 0.1.0-alpha.6

Wiaoj.Identifiers.Security

Encrypts Wiaoj.Identifiers under a Wiaoj.Security key ring, so identifier keys are stored, wrapped by the master key and rotated like the rest of your secrets.

Installation

dotnet add package Wiaoj.Identifiers.Security

Usage

public sealed class IdentifierContext : ISecretContext;

builder.Services.AddWiaojSecurity()
    .AddEnvironmentMasterKey()
    .AddEntityFrameworkKeyStore<AppDbContext>()
    .AddManagedProtector<IdentifierContext>();

builder.Services.AddIdentifiers().UseKeyRingCodec<IdentifierContext>();

Generated identifiers then work as usual (id.ToString(), UserId.Parse(text), JSON, binding), with their text written as usr_ + key version + 22 characters.

Compared with UseAesCodec()

How it works

• Per-version key: each key version gets an AesIdCodec, keyed by a 32-byte subkey derived with ISubkeyDeriver<TContext>.DeriveSubkey(version, "wiaoj.identifiers", …). The ring's keys are never exposed. The subkey is derived once per version and cached.
• Writing: uses CurrentKeyVersion.
• Reading: looks at the identifier's version character and decodes with every version in KeyVersions that has that character. The tag check refuses a version that didn't write the identifier.
• Version character: the base62 digit of the version modulo 62: 1…9, A…Z, a…z, then 0. After version 61 the characters repeat; versions sharing a character are both tried, so reading still works.

Rotation

AddManagedProtector<TContext>() reloads the key ring on rotation, and the codec follows the reload. No restart is needed.

await keyRotationService.ForceRotateAsync();   // KeyRotationService<IdentifierContext>

id.ToString();              // now "usr_2…"
UserId.Parse(oldText);      // an identifier written as "usr_1…" still parses

Keep retired versions in the ring for as long as their identifiers are in circulation: in URLs, in other systems' databases, in emails. An identifier whose version is removed from the ring can no longer be read.

This is different from secrets encrypted with ISecretProtector, which IDataRotator re-encrypts: identifiers are held by clients, so they can't be rewritten. What you store is Value, the Snowflake (see Wiaoj.Identifiers.EntityFrameworkCore), so rotation never touches your database.

Startup

Using UseKeyRingCodec<TContext>() without AddManagedProtector<TContext>() fails when the host starts, because there is no ISubkeyDeriver<TContext>. Keys are loaded lazily, on the first identifier written or read, and AddManagedProtector pre-warms them while the host starts.