dohertj2/scadaproj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(secrets): build G-8 KEK rotation (RewrapAll); design+plan G-7 clustered replication

Browse Source 
G-8 (KEK rotation) — built in ZB.MOM.WW.Secrets, lib 0.1.2->0.1.3:
- ISecretCipher.Rewrap(row, oldKek, newKek): re-wraps the per-secret DEK only
  (bodies never re-encrypted; revision/timestamps preserved -> invisible to
  cluster LWW). Fail-closed on wrong old-KEK id, wrong key bytes, and malformed
  wraps; DEK zeroed on all paths.
- ISecretStore.ApplyRewrapAsync(rewrappedRow, expectedCurrentWrappedDek):
  updates only the 4 wrap columns + kek_id, compare-and-swap on the current
  wrapped DEK so a concurrent set/rotate cannot corrupt a row (closes a
  review-caught TOCTOU).
- KekRotationService.RewrapAllAsync + RewrapReport: enumerate all rows incl.
  tombstones, idempotent/resumable skip-already-current, bounded CAS-retry,
  fail-closed on unknown/identical KEK.
- `secret rewrap-all` CLI verb: key material only via env-var name / file path,
  JSON counts report; README section + operator runbook.

Verified: full offline suite green (82 core + 15 UI, 0 regressions) + end-to-end
CLI smoke + adversarial crypto review (all 7 categories PASS; TOCTOU fixed).

G-7 (clustered replication) — designed + planned, no code:
- Fork resolved to build Option A (shared SQL-Server ISecretStore); Akka
  replicator ZB.MOM.WW.Secrets.Akka is a deferred phase-2. Design doc +
  executable plan + .tasks.json under docs/plans/2026-07-17-secrets-g7-*.

Tracking: components/secrets/GAPS.md + CLAUDE.md secrets row updated.
This commit is contained in:
Joseph Doherty
2026-07-17 02:55:43 -04:00
parent b009507e10
commit d82d3451e7
24 changed files with 1280 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ZB.MOM.WW.Secrets/src/ZB.MOM.WW.Secrets.Cli/Program.cs
+65
View File
@@ -1,9 +1,11 @@
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using ZB.MOM.WW.Secrets.Abstractions;
using ZB.MOM.WW.Secrets.Cli;
using ZB.MOM.WW.Secrets.DependencyInjection;
using ZB.MOM.WW.Secrets.MasterKey;
using ZB.MOM.WW.Secrets.Sqlite;
// Headless `secret` CLI: set / get / list / rm / rotate over the ZB.MOM.WW secrets store.
@@ -77,6 +79,41 @@ try
return await commands.RemoveAsync(args[1], actor, ct);
}
case "rewrap-all":
{
// Rotate the master KEK by re-wrapping every row's DEK. Key material is supplied ONLY by
// env-var NAME or file PATH — never as a literal argument (which would be echoed/logged).
string? oldKind = null, oldValue = null, oldKekId = null;
string? newKind = null, newValue = null, newKekId = null;
for (int i = 1; i < args.Length; i++)
{
switch (args[i])
{
case "--old-key-env": (oldKind, oldValue) = ("env", RequireValue(args, ref i)); break;
case "--old-key-file": (oldKind, oldValue) = ("file", RequireValue(args, ref i)); break;
case "--old-key-id": oldKekId = RequireValue(args, ref i); break;
case "--new-key-env": (newKind, newValue) = ("env", RequireValue(args, ref i)); break;
case "--new-key-file": (newKind, newValue) = ("file", RequireValue(args, ref i)); break;
case "--new-key-id": newKekId = RequireValue(args, ref i); break;
default: return Usage($"Unknown option '{args[i]}'.");
}
}
if (oldKind is null)
return Usage("rewrap-all requires --old-key-env <VAR> or --old-key-file <path>.");
if (newKind is null && newKekId is not null)
return Usage("--new-key-id requires --new-key-env <VAR> or --new-key-file <path>.");
IMasterKeyProvider oldKek = BuildProvider(oldKind, oldValue!, oldKekId);
// Default the new KEK to the app's configured provider (Secrets:MasterKey); override with flags.
IMasterKeyProvider newKek = newKind is null
? host.Services.GetRequiredService<IMasterKeyProvider>()
: BuildProvider(newKind, newValue!, newKekId);
return await commands.RewrapAllAsync(oldKek, newKek, ct);
}
default:
return Usage($"Unknown command '{args[0]}'.");
}
@@ -132,6 +169,26 @@ static SecretContentType ParseContentType(string value) => value switch
$"Unknown --content-type '{value}'; expected text|connection-string|json|binary-base64."),
};
// Reads the value that must follow an option flag at args[i], advancing i past it.
static string RequireValue(string[] args, ref int i)
{
if (i + 1 >= args.Length)
throw new ArgumentException($"{args[i]} requires a value.");
return args[++i];
}
// Builds a master-key provider from a source kind ("env" | "file") + its env-var name or file path,
// with an optional explicit KEK id (needed when the app configured Secrets:MasterKey:KekId rather
// than the derived sha256: id). The key VALUE itself is only ever read from the env var / file.
static IMasterKeyProvider BuildProvider(string kind, string value, string? kekId) => kind switch
{
"env" => MasterKeyProviderFactory.Create(
new MasterKeyOptions { Source = MasterKeySource.Environment, EnvVarName = value, KekId = kekId }),
"file" => MasterKeyProviderFactory.Create(
new MasterKeyOptions { Source = MasterKeySource.File, FilePath = value, KekId = kekId }),
_ => throw new ArgumentException($"Unknown key source '{kind}'."),
};
// Prints usage (optionally preceded by an error line) and returns the standard usage exit code.
int Usage(string? error = null)
{
@@ -147,6 +204,14 @@ int Usage(string? error = null)
get <name>
list [--include-deleted]
rm <name>
rewrap-all --old-key-env <VAR>|--old-key-file <path> [--old-key-id <id>]
[--new-key-env <VAR>|--new-key-file <path>] [--new-key-id <id>]
rewrap-all rotates the master KEK: it re-wraps every stored secret's data key from the old
KEK to the new one (bodies are never re-encrypted, no plaintext is exposed). The new KEK
defaults to the configured Secrets:MasterKey provider. Supply key material only by env-var
NAME or file PATH — never as a literal. Run it with resolve traffic quiesced; it is
idempotent and safe to re-run.
""");
return 2;
}
ZB.MOM.WW.Secrets/src/ZB.MOM.WW.Secrets.Cli/SecretCommands.cs
+42
View File
@@ -1,5 +1,6 @@
using System.Text.Json;
using ZB.MOM.WW.Secrets.Abstractions;
using ZB.MOM.WW.Secrets.Rotation;
namespace ZB.MOM.WW.Secrets.Cli;
@@ -156,6 +157,47 @@ public sealed class SecretCommands
return removed ? 0 : 1;
}
/// <summary>
/// rewrap-all: rotates the master KEK by re-wrapping every row's DEK from <paramref name="oldKek"/>
/// onto <paramref name="newKek"/> — bodies are never re-encrypted and no plaintext is exposed.
/// Prints a JSON report of the counts (total / rewrapped / already-current) and NEVER any key
/// material. Idempotent + resumable; fails closed (non-zero) on an identical-KEK mistake or a row
/// wrapped by an unrecognized KEK.
/// </summary>
/// <param name="oldKek">The provider for the KEK rows are currently wrapped under.</param>
/// <param name="newKek">The provider for the KEK rows should be re-wrapped onto.</param>
/// <param name="ct">A token to cancel the operation.</param>
/// <returns>0 on success; non-zero if the rotation was rejected or aborted.</returns>
public async Task<int> RewrapAllAsync(
IMasterKeyProvider oldKek, IMasterKeyProvider newKek, CancellationToken ct)
{
var service = new KekRotationService(_store, _cipher);
try
{
RewrapReport report = await service.RewrapAllAsync(oldKek, newKek, ct).ConfigureAwait(false);
WriteJson(new
{
action = "rewrap-all",
total = report.Total,
rewrapped = report.Rewrapped,
alreadyCurrent = report.AlreadyCurrent,
});
return 0;
}
catch (ArgumentException ex)
{
// Identical old/new KEK ids — nothing to rotate.
WriteJson(new { action = "rewrap-all", error = ex.Message });
return 1;
}
catch (SecretDecryptionException ex)
{
// A row on an unrecognized KEK aborted the pass, or a DEK failed to unwrap.
WriteJson(new { action = "rewrap-all", error = ex.Message });
return 1;
}
}
/// <summary>Seals a value under the cipher and upserts it, carrying description + actor stamps.</summary>
private async Task UpsertSealedAsync(
SecretName name, string value, SecretContentType contentType, string? description, string? actor, CancellationToken ct)