====== TrustStoreExtensions & PqTrustStore ======

Custom trust store management for PQ-compatible PKI infrastructures.

----

===== Overview =====

^  Class  ^  Description  ^
| ''PqTrustStore'' | Full-featured trust store with PQ support |
| ''TrustStoreExtensions'' | Extension methods for ''X509Certificate2Collection'' |
| ''TrustEntry'' | Metadata for trust store entries |
| ''TrustType'' | Enum: TrustAnchor, IntermediateCA, etc. |

----

===== PqTrustStore Class =====

<code csharp>
using WvdS.System.Security.Cryptography.X509Certificates;

// Create trust store
using var trustStore = new PqTrustStore();

// Add root CA
var rootCa = new X509Certificate2("root-ca.cer");
trustStore.AddTrustAnchor(rootCa, alias: "Company Root CA");

// Add intermediate CA
var intermediateCa = new X509Certificate2("intermediate-ca.cer");
trustStore.AddIntermediate(intermediateCa, alias: "Issuing CA");

// Use trust store
Console.WriteLine($"Trust store contains {trustStore.Count} entries");
</code>

----

===== Integration with X509Chain =====

**Validate with custom trust store:**

<code csharp>
using System.Security.Cryptography.X509Certificates;
using WvdS.System.Security.Cryptography;
using WvdS.System.Security.Cryptography.X509Certificates;

// Load trust store
using var trustStore = PqTrustStore.LoadFromPem("company-trust-store.pem");

// Validate certificate
var userCert = new X509Certificate2("user.cer");

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

if (isValid)
{
    Console.WriteLine("Certificate is valid");
}
else
{
    foreach (var status in chain.ChainStatus)
    {
        Console.WriteLine($"Error: {status.StatusInformation}");
    }
}
</code>

**With X509Certificate2Collection:**

<code csharp>
// Simpler: Directly with collection
var trustAnchors = TrustStoreExtensions.LoadFromPem("trust-anchors.pem");

using var chain = new X509Chain();
bool isValid = chain.Build(userCert, trustAnchors, CryptoMode.Hybrid);
</code>

----

===== Trust Store Import/Export =====

**PEM Bundle:**

<code csharp>
// Save
trustStore.SaveToPem("trust-store.pem");

// Load
var loadedStore = PqTrustStore.LoadFromPem("trust-store.pem");
</code>

**PKCS#7 (DER):**

<code csharp>
// Save as PKCS#7
trustStore.SaveToPkcs7("trust-store.p7b");

// Load
var loadedStore = PqTrustStore.LoadFromPkcs7("trust-store.p7b");
</code>

----

===== System Store Import =====

<code csharp>
// Populate trust store with system certificates
using var trustStore = new PqTrustStore();

// Import Windows root CAs
trustStore.ImportFromSystemRootStore();

// Import Windows intermediate CAs
trustStore.ImportFromSystemIntermediateStore();

// Export as PEM for air-gapped systems
trustStore.SaveToPem("system-trust-store.pem");
</code>

----

===== TrustType Enum =====

^  Value  ^  Description  ^
| ''TrustAnchor'' | Trust anchor (root CA) |
| ''IntermediateCA'' | Intermediate certificate authority |
| ''CrossCertifiedCA'' | Cross-certified CA |
| ''EndEntity'' | End entity (not a CA) |

----

===== Trust Store Queries =====

<code csharp>
// Trust anchors only
var roots = trustStore.TrustAnchors;

// Intermediate CAs only
var intermediates = trustStore.IntermediateCAs;

// Search by subject
var found = trustStore.FindBySubjectName("Company");

// Search by thumbprint
var entry = trustStore.FindByThumbprint("A1B2C3...");

// Check if contained
bool exists = trustStore.Contains(certificate);
</code>

----

===== Validation Report =====

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

// Create detailed report
var report = chain.GetValidationReport();

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

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

**Example output:**

<code>
Chain Validation: VALID
Chain Length: 3
Fully PQ Protected: True
Elements:
  [0] CN=User Certificate
      Mode: Hybrid, PQ Keys: True
  [1] CN=Issuing CA
      Mode: Hybrid, PQ Keys: True
  [2] CN=Root CA
      Mode: Hybrid, PQ Keys: True
</code>

----

===== Offline CRL Checking =====

For air-gapped systems with preloaded CRLs:

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

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

----

===== Collection Extensions =====

<code csharp>
// Filter collection
var collection = new X509Certificate2Collection();
collection.Import("certificates.p7b");

// CAs only
var cas = collection.FilterCertificateAuthorities();

// Root CAs only (self-signed)
var roots = collection.FilterRootCertificates();

// Search by subject
var found = collection.FindBySubjectName("Company");

// Check PQ status
bool hasPq = collection.HasPqProtectedCertificates();

// Save as PEM
collection.SaveToPem("output.pem");
</code>

----

===== Best Practices =====

**Trust Store Hierarchy:**

<code>
PqTrustStore
+-- TrustAnchors (Root CAs)
|   +-- -> chain.ChainPolicy.CustomTrustStore
+-- IntermediateCAs
    +-- -> chain.ChainPolicy.ExtraStore
</code>

**Recommendations:**

  * **Principle of least privilege:** Only include required CAs
  * **PQ migration:** Gradually add PQ keys to existing CAs
  * **Backup:** Regularly back up trust store
  * **Validation:** Verify new CAs before adding

----

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

  * [[.:x509chainextensions|X509ChainExtensions]] - Chain validation
  * [[.:revocationextensions|RevocationExtensions]] - Revocation checking
  * [[en:int:pqcrypt:konzepte:pki|PKI Concepts]]

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

{{tag>truststore pki ca chain}}