Lyo.KeyStore 3.0.0

Lyo.KeyStore

Key encryption key (KEK) storage and rotation contracts for Lyo.Encryption. Encryption services call IKeyStore by keyId and optional version string so ciphertext can outlive a single key-material rotation.

Vocabulary: the KEK lives in the store. Data encryption keys (DEKs) used by envelope / two-key flows are generated per operation by the encryption layer and are not persisted in the keystore. Only the KEK that wraps them is stored.

Examples

Register with DI

using Lyo.KeyStore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

// Unkeyed
services.AddLocalKeyStore(ks =>
{
    ks.UpdateKeyFromString("app", configuration["Encryption:CurrentKek"]!);
});

// Keyed (pair with AddEncryptionServiceKeyed / addon *ServiceKeyed)
const string storeKey = "primary";
services.AddKeyedLocalKeyStore(storeKey, ks =>
{
    ks.AddKeyFromString("app", "v1", configuration["Encryption:Kek:v1"]!);
    ks.SetCurrentVersion("app", "v1");
});

Register with DI (2)

{
  "Encryption": {
    "CurrentKek": "replace-in-user-secrets",
    "Kek": {
      "v1": "versioned-secret"
    }
  }
}

IKeyStore methods

Versions are strings, for example "1", "2025-01", or opaque ids from an HSM. GetCurrentVersion returns the version used when callers omit an explicit version on encrypt.

UpdateKey* allocates a new version, monotonic in LocalKeyStore, and sets it current. Use this for rotation. AddKey pins an exact (keyId, version) pair. Use that when importing known version labels from another system.

Exceptions

Failures surface as KeyNotFoundException, InvalidKeyException, KeyVersionNotFoundException, all rooted at EncryptionKeyException. Log with keyId. Never log raw key bytes. Pair with metrics so silent misconfiguration does not look like bad client data.

Key derivation (KeyDerivation/)

HKDF (RFC 5869), PBKDF2-SHA256 helpers, and Argon2 adapters live in this assembly so onboarding UIs can derive stable bytes from passphrases consistently with AddKeyFromString. Prefer SecureKeyGenerator when generating random material instead of ad-hoc RNG.

Implementations of IKeyDerivationService:

Key validation (KeyValidator)

• ValidateKeyOrThrow(byte[] keyMaterial, ISymmetricKeyMaterialSize spec). Rejects null/empty buffers and key lengths that aren't in the algorithm's accepted set.
• IsValid(...) / TryValidate(...). Non-throwing variants for UIs that report validation failures inline.
• Optional entropy/heuristic checks (e.g. all-zero buffers, repeating patterns) so that obviously bad imports fail early.

Inventory (IKeyInventoryStore)

Optional capability for admin UIs and audits: enumerate logical keyIds and versions. Not every store implements listing. Probe for IKeyInventoryStore or your cloud-specific API before assuming discovery works. KeyStoreMigrator requires it on the source.

Copying a store (KeyStoreMigrator)

KeyStoreMigrator.CopyAsync copies every version of the given key ids from a source that implements IKeyInventoryStore onto another IKeyStore. CopyInventoryAsync does that for every id the source lists, including keys no file uses. Both take an optional IProgress<KeyStoreMigrationProgress>. Null reports nothing. Each report is one version after it is verified: copied, skipped, or failed.

The copy uses AddKey, so version strings stay the ones already written into ciphertext ("1", "v1", "2025-01"). A destination version with the same bytes is skipped. Different bytes throw before AddKey overwrites them. The destination current pointer is set to the source pointer only when the destination had no pointer, or already pointed at the same version. A different pointer throws and is left where it was. After AddKey, the destination GetKey must match the source bytes or the copy stops before SetCurrentVersion.

FileStorageTransfer in Lyo.FileStorage calls CopyAsync for the key ids a transfer actually references. Use CopyInventoryAsync when the whole store should move.

Dependency injection

Configuration uses the configure => lambda. There is no AddLocalKeyStoreFromConfiguration. Read IConfiguration inside configure, the same pattern as other Lyo libraries:

Example appsettings.json values consumed manually in configure:

Local development (LocalKeyStore)

In-memory store for tests and local apps:

services.AddLocalKeyStore(ks =>
{
    ks.AddKeyFromString("app", "v1", "local-dev-secret");
    ks.SetCurrentVersion("app", "v1");
});

AddKeyedLocalKeyStore registers distinct LocalKeyStore instances per DI key. Useful when a single process hosts multiple logical tenants, if you are careful about keyed resolution and never cross-wire IKeyStore instances.

LocalKeyStore.RemoveKey(string keyId, string version) retires a non-current version and returns false when the version doesn't exist or matches GetCurrentVersion. Call SetCurrentVersion before pruning the previous current.

Production. LocalKeyStore is not durable and not audited. Swap for Lyo.KeyStore.Aws, Azure Key Vault, PKCS#11, or another IKeyStore that meets your retention and access policies.

Cloud bridge

See Lyo.KeyStore.Aws for AwsKeyStore and helpers that align with AWS Secrets Manager style payloads.

How encryption uses the store

Symmetric and envelope services resolve keyId on encrypt. Ciphertext and stream headers carry keyId and version so decrypt can call GetKey(keyId, version) even after rotation. Two-key flows wrap per-operation DEKs. KEK rotation can use ReEncryptDek on ITwoKeyEncryptionService without re-encrypting bulk payload. See the encryption README.

Operational checklist

• Thread safety. Custom stores must tolerate concurrent Get* while admins Add* / SetCurrentVersion.
• Rotation. Keep old versions until all ciphertext referencing them is re-encrypted or retired. Track GetCurrentVersion separately from the newest encrypt version.
• Backups. Database and blob snapshots do not replace key governance. Export and access control live in infra policy.
• Configuration. Prefer environment-specific keyId namespaces (tenant:prod:comic-files) to avoid accidental cross-environment decrypt.

Dependency injection

Microsoft.Extensions.DependencyInjection.Extensions in this package: AddLocalKeyStore() registers a shared LocalKeyStore as IKeyStore. AddLocalKeyStore(Action<LocalKeyStore>) configures keys before the container finishes building. Keyed encryption registration lives in EncryptionServiceExtensions, for example AddEncryptionServiceKeyed. See also Lyo.Encryption/README.md.

Encryption guide

Algorithm choice, stream formats, threat modeling, and long-form examples remain in ../README.md, the folder-level encryption guide.

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Common.Core (direct, lyo)
• Lyo.Exceptions (direct, lyo)
• Konscious.Security.Cryptography.Argon2 1.3.1 (direct, third-party)
• Microsoft.Extensions.DependencyInjection.Abstractions 10.0.5 (direct, microsoft, net10.0, netstandard2.0)
• Microsoft.Bcl.AsyncInterfaces 10.0.5 (transitive, microsoft, netstandard2.0)
• System.Memory 4.6.3 (transitive, microsoft, netstandard2.0)
• System.Text.Json 10.0.5 (transitive, microsoft, netstandard2.0)