====== X509ChainExtensions ======

**Namespace:** ''WvdS.System.Security.Cryptography.X509Certificates''

Drop-in replacement extensions for ''X509Chain'' with post-quantum signature validation. Extends the standard chain validation with PQ signature checking in all three crypto modes.

===== Methods =====

^ Method ^ Description ^
| ''Build(certificate, mode)'' | Builds and validates the certificate chain with CryptoMode |
| ''Build(certificate, customTrustStore, mode)'' | Chain validation with custom trust store |
| ''Build(certificate, trustStore, mode)'' | Chain validation with PqTrustStore |
| ''BuildWithRevocationCheck(...)'' | Chain build with CRL/OCSP checking |
| ''BuildWithOfflineCrl(...)'' | Chain build with offline CRL data |
| ''IsFullyPqProtected()'' | Checks if entire chain is PQ protected |
| ''GetChainCryptoModes()'' | Returns CryptoModes of all chain elements |
| ''GetValidationReport()'' | Creates detailed validation report |

===== Build with CryptoMode =====

<code csharp>
using var chain = new X509Chain();
var cert = new X509Certificate2("certificate.pfx");

// With explicit CryptoMode
bool isValid = chain.Build(cert, CryptoMode.Hybrid);

// With default mode from CryptoConfig
bool isValid2 = chain.Build(cert, null);
</code>

==== Validation Behavior by Mode ====

^ Mode ^ Classical Signature ^ PQ Signature ^
| Classic | Verified | Ignored |
| Hybrid | Verified | Verified (if present) |
| PostQuantum | Verified (structure) | **Required** |

===== Build with Custom Trust Store =====

<code csharp>
// With X509Certificate2Collection
var trustAnchors = new X509Certificate2Collection();
trustAnchors.Add(rootCa);

using var chain = new X509Chain();
bool isValid = chain.Build(cert, trustAnchors, CryptoMode.Hybrid);

// With PqTrustStore
var trustStore = PqTrustStore.LoadFromPem("truststore.pem");
bool isValid2 = chain.Build(cert, trustStore, CryptoMode.Hybrid);
</code>

===== BuildWithRevocationCheck =====

<code csharp>
using var chain = new X509Chain();
bool isValid = chain.BuildWithRevocationCheck(
    certificate,
    customTrustStore,
    X509RevocationMode.Online,  // or Offline
    CryptoMode.Hybrid);
</code>

===== BuildWithOfflineCrl =====

For air-gapped environments or when CRL download is not possible:

<code csharp>
// Load CRLs
var crlData = new List<byte[]>
{
    File.ReadAllBytes("root-ca.crl"),
    File.ReadAllBytes("intermediate-ca.crl")
};

using var chain = new X509Chain();
bool isValid = chain.BuildWithOfflineCrl(
    certificate,
    customTrustStore,
    crlData,
    CryptoMode.Hybrid);
</code>

===== IsFullyPqProtected =====

<code csharp>
using var chain = new X509Chain();
chain.Build(cert, CryptoMode.Hybrid);

if (chain.IsFullyPqProtected())
{
    Console.WriteLine("Entire chain is PQ protected");
}
else
{
    // Which certificates are not PQ protected?
    var modes = chain.GetChainCryptoModes();
    for (int i = 0; i < modes.Length; i++)
    {
        if (modes[i] == CryptoMode.Classic)
        {
            Console.WriteLine($"Element {i} has no PQ protection");
        }
    }
}
</code>

===== GetValidationReport =====

Creates a detailed report about chain validation:

<code csharp>
using var chain = new X509Chain();
chain.Build(cert, CryptoMode.Hybrid);

var report = chain.GetValidationReport();
Console.WriteLine(report.ToString());

// Individual properties:
Console.WriteLine($"Valid: {report.IsValid}");
Console.WriteLine($"Chain length: {report.ChainLength}");
Console.WriteLine($"Fully PQ protected: {report.IsFullyPqProtected}");

// Details per element:
foreach (var element in report.Elements)
{
    Console.WriteLine($"  {element.Subject}");
    Console.WriteLine($"    Mode: {element.CryptoMode}");
    Console.WriteLine($"    Has PQ keys: {element.HasPqKeys}");
}
</code>

===== ChainValidationReport =====

^ Property ^ Type ^ Description ^
| ''IsValid'' | bool | Chain is valid |
| ''ChainLength'' | int | Number of chain elements |
| ''IsFullyPqProtected'' | bool | All certificates are PQ protected |
| ''OverallStatus'' | X509ChainStatusFlags[] | Overall status |
| ''Elements'' | ChainElementInfo[] | Details per element |

===== ChainElementInfo =====

^ Property ^ Type ^ Description ^
| ''Subject'' | string | Certificate subject |
| ''Issuer'' | string | Issuer |
| ''Thumbprint'' | string | SHA-1 fingerprint |
| ''NotBefore'' | DateTime | Valid from |
| ''NotAfter'' | DateTime | Valid until |
| ''CryptoMode'' | CryptoMode | Detected mode |
| ''HasPqKeys'' | bool | PQ keys in store |
| ''StatusFlags'' | X509ChainStatusFlags[] | Status flags |
| ''StatusMessages'' | string[] | Status messages |

===== See Also =====

  * [[.:x509certificate2extensions|X509Certificate2Extensions]]
  * [[.:truststoreextensions|TrustStoreExtensions]]
  * [[.:revocationextensions|RevocationExtensions]]
  * [[en:int:pqcrypt:konzepte:start|Crypto Modes Explained]]

----
//Wolfgang van der Stille @ EMSR DATA d.o.o. - Post-Quantum Cryptography Professional//