Knowledge Base — Signed & Encrypted Crypto Intelligence Package

dotnet add package CipherShift365.Core.Runtime

<PackageReference Include="CipherShift365.Core.Runtime" Version="1.0.0" />

using CipherShift365.Core.Runtime;

var encryptionKey = new byte[32]; // AES-256 key (32 bytes)
var signingKey = new byte[32];    // HMAC-SHA256 key (32 bytes)
RandomNumberGenerator.Fill(encryptionKey);
RandomNumberGenerator.Fill(signingKey);

var metadata = new KbPackageMetadata(
    KbVersion: new KbVersion(2, 1, 0),
    CreatedAt: DateTimeOffset.UtcNow,
    EncryptionAlgorithm: "AES-256-GCM",
    SigningAlgorithm: "HMAC-SHA256",
    Description: "Q1 2026 KB update — CNSA 2.0 + NIST PQC standards");

var entries = new List<KbEntry>
{
    new("ML-KEM-1024", CryptoRole.Kem, RiskLevel.QuantumSafe,
        StandardsReferences: new[] { "FIPS 203", "CNSA 2.0" },
        MigrationNotes: "Use as primary KEM."),
    new("ML-DSA-87", CryptoRole.Signature, RiskLevel.QuantumSafe,
        StandardsReferences: new[] { "FIPS 204", "CNSA 2.0" }),
    new("RSA", CryptoRole.Signature, RiskLevel.QuantumBroken,
        StandardsReferences: new[] { "CNSA 2.0" },
        MigrationNotes: "Replace with ML-DSA-87.")
};

var profiles = new[] { cnsaProfile };

var content = new KbPackageContent(metadata, entries.AsReadOnly(), profiles);

var builder = new KbBuilder(encryptionKey, signingKey);
byte[] package = builder.Build(content);

File.WriteAllBytes("knowledge-base.cskb", package);

var loader = new KbLoader(encryptionKey, signingKey);
byte[] package = File.ReadAllBytes("knowledge-base.cskb");

var result = loader.Load(package);

if (!result.IsValid)
{
    Console.WriteLine($"KB load failed: {result.Outcome} — {result.ErrorDetail}");
    // Possible outcomes:
    //   Tampered          — package was modified after signing
    //   InvalidSignature  — HMAC mismatch
    //   UnsupportedFormat — bad magic bytes or format version
    //   DecryptionFailed  — wrong decryption key or corrupted ciphertext
    return;
}

// Create an in-memory knowledge base for queries
var kb = new SignedKnowledgeBase(result.Content!);
Console.WriteLine($"KB v{kb.Version} loaded. {result.Content!.Entries.Count} entries.");

// Check if an algorithm is known
if (kb.TryGetEntry("RSA", out var entry))
{
    Console.WriteLine($"RSA: {entry.Risk} — {entry.Description}");
    Console.WriteLine($"Standards: {string.Join(", ", entry.StandardsReferences ?? Array.Empty<string>())}");
    Console.WriteLine($"Migration: {entry.MigrationNotes}");
}

// Get a PQC recommendation
var rec = kb.Recommend(CryptoRole.Signature, "ECDSA", new CryptoParameters());
Console.WriteLine($"Replace ECDSA with: {rec.Algorithm} — {rec.Rationale}");

// Enumerate compliance profiles
foreach (var profile in kb.ComplianceProfiles)
{
    Console.WriteLine($"{profile.Name} v{profile.Version}: " +
        $"requires {profile.RequiredAlgorithms.Count} algorithms, " +
        $"minimum risk: {profile.MinimumAcceptableRisk}");
}

new KbEntry(
    Algorithm: "ML-KEM-1024",         // Canonical algorithm name
    Role: CryptoRole.Kem,             // Cryptographic role
    Risk: RiskLevel.QuantumSafe,      // Risk classification
    Description: "CNSA 2.0 approved", // Human-readable
    StandardReference: "FIPS 203",    // Single primary standard
    SecurityLevel: 5,                 // NIST security level (1-5)
    Recommendations: new[] {          // PQC migration targets
        new Recommendation("ML-KEM-1024", ...)
    },
    StandardsReferences: new[] {      // All applicable standards
        "FIPS 203", "CNSA 2.0"
    },
    MigrationNotes: "Use ML-KEM-1024 as primary KEM.",
    ParametersConsidered: new CryptoParameters(...) // Key size, mode, etc.
);

new ComplianceProfile(
    Name: "CNSA 2.0",
    Version: "2024-09",
    RequiredAlgorithms: new[] { "ML-KEM-1024", "ML-DSA-87", "AES-256", "SHA-384", "SHA-512", "LMS", "XMSS" },
    MinimumAcceptableRisk: RiskLevel.QuantumSafe,
    Description: "CNSA 2.0 requires quantum-safe algorithms for all cryptographic operations.");

foreach (var profile in kb.ComplianceProfiles)
{
    // Use profile to drive validation
    var validator = new CnsaValidator(kb, profile, timeline);
    var result = validator.Validate(cbom);
}

// Explicit entry in KB → returns first recommendation in the list
// No entry in KB → returns hardcoded defaults:
//   Signature → ML-DSA-65
//   KEM       → ML-KEM-768
//   Symmetric → AES-256-GCM
//   Hash      → SHA-512
//   Unknown   → ML-KEM-768
var rec = kb.Recommend(CryptoRole.Signature, "RSA", new CryptoParameters());
// rec.Algorithm = "ML-DSA-87" (if defined in KB entry)
// rec.Rationale = "CNSA 2.0 approved for digital signatures (FIPS 204)."

var builder = new KbBuilder(encryptionKey, signingKey);
byte[] runtimePackage = builder.BuildRuntimeSubset(fullContent);

// The runtime subset:
//   ✅ Algorithm entries with risk classification
//   ✅ Compliance profiles
//   ❌ Migration notes (removed)
//   ❌ Recommendations (set to null)

var v1 = KbVersion.Parse("2.0.0");
var v2 = KbVersion.Parse("2.1.0");
Console.WriteLine(v1 < v2); // True
Console.WriteLine(v1 == v2); // False

KbBuilder
  ├── Constructor: byte[] encryptionKey, byte[] signingKey
  ├── Build(KbPackageContent) → byte[]
  └── BuildRuntimeSubset(KbPackageContent) → byte[]

KbLoader
  ├── Constructor: byte[] encryptionKey, byte[] signingKey
  ├── Load(byte[] package) → KbLoadResult
  └── LoadAsKnowledgeBase(byte[] package) → SignedKnowledgeBase

KbPackageFormat (internal static)
  ├── Magic: 0x43534B42
  ├── FormatVersion: 1
  ├── NonceSize: 12, TagSize: 16, HmacSize: 32
  ├── Build(KbPackageContent, byte[] encKey, byte[] signKey) → byte[]
  └── Load(byte[] package, byte[] encKey, byte[] signKey) → KbLoadResult

SignedKnowledgeBase : IKnowledgeBase
  ├── Version: KbVersion
  ├── ComplianceProfiles: IReadOnlyList<ComplianceProfile>
  ├── TryGetEntry(string algorithm, out KbEntry entry) → bool
  └── Recommend(CryptoRole, string, CryptoParameters) → Recommendation

KbPackageContent (record)
  ├── Metadata: KbPackageMetadata
  ├── Entries: IReadOnlyList<KbEntry>
  └── ComplianceProfiles: IReadOnlyList<ComplianceProfile>?

KbPackageMetadata (record)
  ├── KbVersion: KbVersion
  ├── CreatedAt: DateTimeOffset
  ├── EncryptionAlgorithm: string
  ├── SigningAlgorithm: string
  └── Description: string?

KbLoadResult (readonly record struct)
  ├── Outcome: KbLoadOutcome { Valid, Tampered, InvalidSignature, UnsupportedFormat, DecryptionFailed, UnknownVersion }
  ├── Content: KbPackageContent?
  ├── ErrorDetail: string?
  └── IsValid: bool

KbBuildOutput (enum)
  ├── Full
  └── RuntimeClassificationOnly

// Build:
//   1. Serialize metadata → JSON → UTF-8 bytes (header)
//   2. Serialize content → JSON → UTF-8 bytes (payload)
//   3. Generate 12-byte random nonce
//   4. Encrypt payload with AES-256-GCM → ciphertext + 16-byte tag
//   5. Write: magic(4) + version(1) + headerLen(4) + header + nonce(12) + tag(16) + ciphertext
//   6. Compute HMAC-SHA256 over everything above → append 32 bytes

// Load:
//   1. Extract last 32 bytes → stored HMAC
//   2. Compute HMAC over preceding bytes → compare in constant time
//   3. Read magic bytes → verify 0x43534B42
//   4. Read format version → verify 0x01
//   5. Read header length → extract header JSON
//   6. Read nonce + tag + ciphertext
//   7. Decrypt with AES-256-GCM
//   8. Deserialize payload JSON

JsonSerializer.Serialize(content.Metadata, CbomSerializerContext.Default.KbPackageMetadata)

var entries = new List<KbEntry>
{
    new("ML-KEM-1024", CryptoRole.Kem, RiskLevel.QuantumSafe,
        Description: "CNSA 2.0 approved key establishment",
        StandardsReferences: new[] { "FIPS 203", "CNSA 2.0" },
        MigrationNotes: "Use ML-KEM-1024 as primary KEM"),
    new("ML-DSA-87", CryptoRole.Signature, RiskLevel.QuantumSafe,
        StandardsReferences: new[] { "FIPS 204", "CNSA 2.0" }),
    new("RSA", CryptoRole.Signature, RiskLevel.QuantumBroken,
        StandardsReferences: new[] { "CNSA 2.0" },
        MigrationNotes: "Replace with ML-DSA-87")
};

var profile = new ComplianceProfile("CNSA 2.0", "2024-09",
    new[] { "ML-KEM-1024", "ML-DSA-87", "AES-256", "SHA-384", "SHA-512" },
    RiskLevel.QuantumSafe);

var content = new KbPackageContent(
    new KbPackageMetadata(new KbVersion(1, 0, 0), DateTimeOffset.UtcNow,
        "AES-256-GCM", "HMAC-SHA256", "Initial CNSA 2.0 KB"),
    entries.AsReadOnly(),
    new[] { profile });

var builder = new KbBuilder(encKey, signKey);
byte[] kb = builder.Build(content);

var loader = new KbLoader(encKey, signKey);
var result = loader.Load(File.ReadAllBytes("kb.cskb"));

switch (result.Outcome)
{
    case KbLoadOutcome.Valid:
        var kb = new SignedKnowledgeBase(result.Content!);
        Console.WriteLine($"KB v{kb.Version} OK. {kb.ComplianceProfiles.Count} profiles.");
        break;
    case KbLoadOutcome.Tampered:
    case KbLoadOutcome.InvalidSignature:
        throw new SecurityException("KB integrity check failed!");
    case KbLoadOutcome.DecryptionFailed:
        throw new SecurityException("KB decryption failed — wrong key?");
    default:
        throw new InvalidOperationException($"Unexpected KB outcome: {result.Outcome}");
}

var builder = new KbBuilder(encryptionKey, signingKey);

// Full KB: 15 KB with migration notes, recommendations
byte[] fullKb = builder.Build(fullContent);
Console.WriteLine($"Full KB: {fullKb.Length} bytes");

// Runtime subset: ~8 KB, classification only
byte[] runtimeKb = builder.BuildRuntimeSubset(fullContent);
Console.WriteLine($"Runtime KB: {runtimeKb.Length} bytes");

// Distribute runtime subset to production instances
// Distribute full KB to Compass/Guardian Gate

var kb = new SignedKnowledgeBase(content);
var findings = new[] { "RSA", "ECDSA", "AES-128", "ML-KEM-1024" };

foreach (var algo in findings)
{
    if (!kb.TryGetEntry(algo, out var entry))
    {
        Console.WriteLine($"{algo}: UNKNOWN — manual review required");
        continue;
    }

    Console.WriteLine($"{algo}: {entry.Risk}");

    if (entry.Risk != RiskLevel.QuantumSafe)
    {
        var rec = kb.Recommend(entry.Role, algo, new CryptoParameters());
        Console.WriteLine($"  → Migrate to: {rec.Algorithm} ({rec.Rationale})");
        Console.WriteLine($"  → Notes: {entry.MigrationNotes}");
    }
}

RSA: QuantumBroken
  → Migrate to: ML-DSA-87 (CNSA 2.0 approved for digital signatures)
  → Notes: Replace with ML-DSA-87.
ECDSA: QuantumBroken
  → Migrate to: ML-DSA-87 (CNSA 2.0 approved for digital signatures)
  → Notes: (none)
AES-128: QuantumVulnerable
  → Migrate to: AES-256-GCM (Default symmetric recommendation.)
  → Notes: (none)
ML-KEM-1024: QuantumSafe

var expectedVersion = KbVersion.Parse("2.0.0");
var result = loader.Load(package);

if (result.IsValid && result.Content!.Metadata.KbVersion < expectedVersion)
{
    Console.WriteLine($"WARNING: KB version {result.Content.Metadata.KbVersion} " +
                      $"is older than required ({expectedVersion}). " +
                      "New algorithms may not be recognized.");
}

Q: "We need to update our crypto guidance for the new NIST standard."
A: "OK, let's update the hardcoded lists in Compass, Vault, Guardian Gate,
    Guardian Runtime, and the Portal. Schedule a release for each. 
    Estimated time: 2 sprints."
Risk: HIGH — inconsistent guidance across modules, slow propagation

Q: "We need to update our crypto guidance for the new NIST standard."
A: "Build a new KB package. Distribute the .cskb file. All modules 
    automatically pick up the new guidance on next load. 
    Estimated time: 10 minutes."
Risk: LOW — single source of truth, instant propagation