====== X509StoreExtensions ======

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

Estensioni per ''X509Store'' con persistenza delle chiavi Post-Quantum. Consente di salvare e ripristinare le chiavi PQ nel Windows Certificate Store.

===== Panoramica =====

Il Windows Certificate Store non supporta nativamente le chiavi Post-Quantum. Queste estensioni salvano le chiavi PQ in un archivio file separato e crittografato:

<code>
%LOCALAPPDATA%\WvdS.Crypto\PqKeys\{thumbprint}.pqkey
</code>

Le chiavi vengono crittografate automaticamente con DPAPI (Windows) o AES-256 (Cross-Platform).

===== Metodi =====

^ Metodo ^ Descrizione ^
| ''Add(certificate, mode)'' | Aggiunge il certificato e persiste le chiavi PQ |
| ''AddRange(collection, mode)'' | Aggiunge più certificati |
| ''Remove(certificate, deletePqKeys)'' | Rimuove il certificato e opzionalmente le chiavi PQ |
| ''RemoveRange(collection, deletePqKeys)'' | Rimuove più certificati |
| ''Find(findType, findValue, validOnly, restorePqKeys)'' | Cerca certificati e ripristina le chiavi PQ |
| ''GetCertificatesWithPqKeys()'' | Tutti i certificati con chiavi PQ ripristinate |

===== Metodi statici =====

^ Metodo ^ Descrizione ^
| ''PersistPqKeys(certificate)'' | Persiste manualmente le chiavi PQ |
| ''RestorePqKeys(certificate)'' | Ripristina manualmente le chiavi PQ |
| ''DeletePqKeys(certificate)'' | Elimina le chiavi PQ persistite |
| ''HasPersistedPqKeys(certificate)'' | Verifica se le chiavi PQ sono presenti |
| ''GetPersistedPqKeyThumbprints()'' | Elenca tutti i thumbprint |

===== Aggiungere un certificato =====

<code csharp>
using var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadWrite);

// Aggiungere certificato con chiavi PQ
var hybridCert = CreateHybridCertificate();
store.Add(hybridCert, CryptoMode.Hybrid);

// Le chiavi PQ vengono persistite automaticamente
Console.WriteLine($"Chiavi PQ salvate: {X509StoreExtensions.HasPersistedPqKeys(hybridCert)}");
</code>

===== Cercare certificato con chiavi PQ =====

<code csharp>
using var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadOnly);

// Cercare e ripristinare le chiavi PQ
var certs = store.Find(
    X509FindType.FindBySubjectName,
    "MioCertificato",
    validOnly: true,
    restorePqKeys: true);  // Carica automaticamente le chiavi PQ

foreach (var cert in certs)
{
    Console.WriteLine($"Trovato: {cert.Subject}");
    Console.WriteLine($"Modalità: {cert.GetCryptoMode()}");

    // Le chiavi PQ sono ora disponibili
    if (PqKeyStore.TryGetPublicKey(cert, out var pqKey))
    {
        Console.WriteLine($"Chiave PQ: {pqKey.Length} Bytes");
    }
}
</code>

===== Tutti i certificati con chiavi PQ =====

<code csharp>
using var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadOnly);

var allCerts = store.GetCertificatesWithPqKeys();

foreach (var cert in allCerts)
{
    var hasPq = X509StoreExtensions.HasPersistedPqKeys(cert);
    Console.WriteLine($"{cert.Subject}: PQ={hasPq}");
}
</code>

===== Rimuovere un certificato =====

<code csharp>
using var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadWrite);

var certToRemove = FindCertificate(store);

// Con pulizia chiavi PQ (consigliato)
store.Remove(certToRemove, deletePqKeys: true);

// Senza pulizia chiavi PQ (le chiavi rimangono)
store.Remove(certToRemove, deletePqKeys: false);
</code>

===== PqKeyStoreManager =====

Classe aggiuntiva per la gestione dello store:

<code csharp>
// Pulizia chiavi orfane (chiavi senza certificato associato)
int deleted = PqKeyStoreManager.CleanupOrphanedKeys(
    StoreName.My,
    StoreLocation.CurrentUser);
Console.WriteLine($"{deleted} chiavi orfane eliminate");

// Backup di tutte le chiavi PQ
PqKeyStoreManager.BackupAllPqKeys(
    "pq-keys-backup.enc",
    "PasswordBackup123!");

// Ripristino da backup
int restored = PqKeyStoreManager.RestoreFromBackup(
    "pq-keys-backup.enc",
    "PasswordBackup123!");
Console.WriteLine($"{restored} chiavi ripristinate");
</code>

===== Crittografia delle chiavi =====

==== Windows (DPAPI) ====

<code>
DataProtectionScope.CurrentUser
- Solo l'utente corrente può decrittografare le chiavi
- Le chiavi sono legate al profilo utente
</code>

==== Cross-Platform (AES-256) ====

<code>
Key = SHA256(MachineName + UserName)
IV = generato casualmente
- Le chiavi sono legate a Machine + User
- Meno sicuro di DPAPI
</code>

===== Eliminazione sicura =====

Le chiavi PQ vengono eliminate in modo sicuro:

<code csharp>
// Internamente viene eseguito:
// 1. Sovrascrivere il file con dati casuali
var random = RandomNumberGenerator.GetBytes(fileLength);
File.WriteAllBytes(keyPath, random);

// 2. Eliminare il file
File.Delete(keyPath);
</code>

===== Esempio: Workflow completo =====

<code csharp>
// 1. Creare un certificato ibrido
CryptoConfig.EnablePostQuantum();
var cert = CreateHybridCertificate("CN=Test Ibrido");

// 2. Aggiungere allo store
using (var store = new X509Store(StoreName.My, StoreLocation.CurrentUser))
{
    store.Open(OpenFlags.ReadWrite);
    store.Add(cert, CryptoMode.Hybrid);
}

// 3. Riavviare l'applicazione...

// 4. Caricare successivamente
using (var store = new X509Store(StoreName.My, StoreLocation.CurrentUser))
{
    store.Open(OpenFlags.ReadOnly);
    var found = store.Find(
        X509FindType.FindBySubjectName,
        "Test Ibrido",
        true,
        restorePqKeys: true);

    var loadedCert = found[0];

    // Le chiavi PQ sono ripristinate!
    var pqPublicKey = PqKeyStore.GetPublicKey(loadedCert);
    Console.WriteLine($"Chiave PQ caricata: {pqPublicKey.Length} Bytes");
}
</code>

===== Percorso di archiviazione =====

^ Sistema operativo ^ Percorso ^
| Windows | ''%LOCALAPPDATA%\WvdS.Crypto\PqKeys\'' |
| Linux | ''~/.local/share/WvdS.Crypto/PqKeys/'' |
| macOS | ''~/Library/Application Support/WvdS.Crypto/PqKeys/'' |

===== Note sulla sicurezza =====

<note warning>
  * Le chiavi PQ sono accessibili solo all'utente corrente
  * Creare backup prima della migrazione del sistema
  * Eseguire regolarmente ''CleanupOrphanedKeys()''
  * La crittografia cross-platform è meno sicura di DPAPI
</note>

===== Vedere anche =====

  * [[.:x509certificate2exportextensions|X509Certificate2ExportExtensions]]
  * [[.:x509certificate2extensions|X509Certificate2Extensions]]
  * [[.:truststoreextensions|TrustStoreExtensions]]

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