feat(transport): optional detached bundle signing with a pluggable key source (ScadaBridge#45)
Exports can now carry a detached ECDSA P-256 signature over the exact
manifest.json bytes in a new optional manifest.sig zip entry. The manifest
already pins the content hash, so a verified signature covers the whole
bundle, including the plaintext source environment the confirm step relies
on. Off by default (ScadaBridge:Transport:Signing): with the defaults,
exports are unsigned and imports accept signed and unsigned bundles.
- The bundle format does not change: bundleFormatVersion stays 1,
manifest.json and the AES-GCM associated data are untouched, and older
importers open entries by name and ignore manifest.sig. Three entries fit
within the default MaxBundleEntryCount of 4.
- Import policy runs after the content-hash check and before any passphrase
work. A signature that fails to verify against a trusted key is always
refused. RequireSignedBundles additionally refuses unsigned bundles and
bundles signed by an untrusted key. A refusal is BundleSignatureException
(Commons), shown on the UI upload step and on CLI preview/import.
- The signature status, key id and signer are recorded on BundleSession and
shown in the import wizard. They are also returned on PreviewBundleResult
and recorded on the BundleImported audit row. BundleExported records
Signed/SigningKeyId.
- Key material is pluggable. IBundleSigningKeySource and IBundleTrustStore
are TryAdd'd; the defaults read Signing:PrivateKey (meant to be a
${secret:} reference) and Signing:TrustedKeys. Key ids are SPKI
fingerprints. Startup validation rejects unparseable or non-P-256 keys.
- Compatibility proof: the checked-in fixtures pre-signing-plaintext and
pre-signing-encrypted were exported by origin/main 3ff463b6, before this
change, and are imported end to end with signing off and with signing
configured.
The design leaves key-per-env vs per-org, trust distribution and rotation,
and the production default for RequireSignedBundles open. These are listed
in Component-Transport.md.
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
@@ -72,6 +72,19 @@ public sealed record PreviewBundleResult(
|
||||
/// <summary>Connection references the operator must resolve before import. Never null.</summary>
|
||||
public IReadOnlyList<RequiredConnectionMapping> RequiredConnectionMappings { get; init; } =
|
||||
RequiredConnectionMappings ?? Array.Empty<RequiredConnectionMapping>();
|
||||
|
||||
/// <summary>
|
||||
/// ScadaBridge#45: the bundle's signature status — <c>Unsigned</c>, <c>Verified</c> or
|
||||
/// <c>UntrustedKey</c> (the <c>BundleSignatureStatus</c> name). Additive; defaults to
|
||||
/// <c>Unsigned</c>.
|
||||
/// </summary>
|
||||
public string SignatureStatus { get; init; } = nameof(BundleSignatureStatus.Unsigned);
|
||||
|
||||
/// <summary>ScadaBridge#45: the signing key's <c>sha256:</c> fingerprint; null when unsigned.</summary>
|
||||
public string? SignerKeyId { get; init; }
|
||||
|
||||
/// <summary>ScadaBridge#45: the trusted key's name when the signature verified; otherwise null.</summary>
|
||||
public string? SignerName { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
|
||||
@@ -23,6 +23,22 @@ public sealed class BundleSession
|
||||
/// session. Empty until the bundle is successfully unlocked.
|
||||
/// </summary>
|
||||
public byte[] DecryptedContent { get; init; } = Array.Empty<byte>();
|
||||
/// <summary>
|
||||
/// ScadaBridge#45: outcome of the detached-signature check made when the bundle was
|
||||
/// loaded. <see cref="BundleSignatureStatus.Unsigned"/> for every bundle produced before
|
||||
/// signing existed.
|
||||
/// </summary>
|
||||
public BundleSignatureStatus SignatureStatus { get; init; } = BundleSignatureStatus.Unsigned;
|
||||
/// <summary>
|
||||
/// ScadaBridge#45: the <c>sha256:</c> fingerprint of the key that signed the bundle, when
|
||||
/// it is signed (verified or not); <c>null</c> for an unsigned bundle.
|
||||
/// </summary>
|
||||
public string? SignerKeyId { get; init; }
|
||||
/// <summary>
|
||||
/// ScadaBridge#45: the trust-store name of the signing key when the signature verified;
|
||||
/// <c>null</c> otherwise.
|
||||
/// </summary>
|
||||
public string? SignerName { get; init; }
|
||||
/// <summary>UTC timestamp after which this session is considered expired and must be re-uploaded.</summary>
|
||||
public DateTimeOffset ExpiresAt { get; init; }
|
||||
/// <summary>
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Transport;
|
||||
|
||||
/// <summary>
|
||||
/// ScadaBridge#45: thrown by <c>IBundleImporter.LoadAsync</c> when a bundle fails the
|
||||
/// signature policy — a signature that does not verify against the trusted key it names,
|
||||
/// a malformed <c>manifest.sig</c>, or (with <c>Transport:Signing:RequireSignedBundles</c>
|
||||
/// on) an unsigned bundle or one signed by an untrusted key.
|
||||
/// <para>
|
||||
/// Lives in Commons, beside <see cref="BundleLockedException"/>, so the management surface — which
|
||||
/// references Commons but not Transport — can curate it for the CLI.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public sealed class BundleSignatureException : Exception
|
||||
{
|
||||
/// <summary>Initializes a new <see cref="BundleSignatureException"/>.</summary>
|
||||
/// <param name="message">Operator-facing reason the bundle was refused.</param>
|
||||
public BundleSignatureException(string message)
|
||||
: base(message)
|
||||
{
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Transport;
|
||||
|
||||
/// <summary>
|
||||
/// ScadaBridge#45: the outcome of checking a bundle's optional detached signature
|
||||
/// (<c>manifest.sig</c>) when it is loaded. A signature that is present, names a trusted
|
||||
/// key and does NOT verify is never a status — it is a hard
|
||||
/// <see cref="BundleSignatureException"/>, because it means the manifest (and therefore
|
||||
/// the content it hashes) was altered after signing.
|
||||
/// </summary>
|
||||
public enum BundleSignatureStatus
|
||||
{
|
||||
/// <summary>The bundle carries no signature (every bundle produced before signing existed).</summary>
|
||||
Unsigned = 0,
|
||||
|
||||
/// <summary>The signature verified against a key in this cluster's trust store.</summary>
|
||||
Verified = 1,
|
||||
|
||||
/// <summary>
|
||||
/// The bundle is signed, but by a key this cluster does not trust, so the signature
|
||||
/// could not be checked. Accepted only while <c>Transport:Signing:RequireSignedBundles</c>
|
||||
/// is off.
|
||||
/// </summary>
|
||||
UntrustedKey = 2,
|
||||
}
|
||||
Reference in New Issue
Block a user