====== NativeCryptoProvider ======

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

P/Invoke-osnovan kriptografski ponudnik za strežnike in namizne aplikacije. Komunicira neposredno z OpenSSL 3.6 preko Platform Invocation Services.

===== Pregled =====

''NativeCryptoProvider'' je privzeti ponudnik za:

  * Blazor Server
  * ASP.NET Core
  * Namizne aplikacije (Windows, Linux, macOS)
  * Konzolne aplikacije
  * Windows Services / Linux Daemons

===== Lastnosti =====

^ Lastnost ^ Tip ^ Opis ^
| ''Name'' | string | ''%%"Native (P/Invoke)"%%'' |
| ''IsAvailable'' | bool | ''true'' če je OpenSSL 3.6 dosegljiv |

===== Inicializacija =====

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

// Ustvarjanje ponudnika
var provider = new NativeCryptoProvider();

// Inicializacija (naloži OpenSSL)
await provider.InitializeAsync();

// Preverjanje razpoložljivosti
if (provider.IsAvailable)
{
    Console.WriteLine($"Ponudnik: {provider.Name}");
    Console.WriteLine($"OpenSSL: {provider.GetOpenSslVersion()}");
}
</code>

===== Operacije ML-DSA =====

==== GenerateMlDsaKeyPairAsync ====

Generira ML-DSA par ključev.

<code csharp>
var (publicKey, privateKey) = await provider.GenerateMlDsaKeyPairAsync("ML-DSA-65");

// Podprti algoritmi:
// - "ML-DSA-44" (NIST Level 1)
// - "ML-DSA-65" (NIST Level 3, priporočeno)
// - "ML-DSA-87" (NIST Level 5)
</code>

==== SignMlDsaAsync ====

Podpiše podatke z ML-DSA.

<code csharp>
byte[] data = Encoding.UTF8.GetBytes("Pomembni podatki");
byte[] signature = await provider.SignMlDsaAsync(data, privateKey);
</code>

==== VerifyMlDsaAsync ====

Preveri ML-DSA podpis.

<code csharp>
bool isValid = await provider.VerifyMlDsaAsync(data, signature, publicKey);
</code>

===== Operacije ML-KEM =====

==== GenerateMlKemKeyPairAsync ====

Generira ML-KEM par ključev.

<code csharp>
var (publicKey, privateKey) = await provider.GenerateMlKemKeyPairAsync("ML-KEM-768");

// Podprti algoritmi:
// - "ML-KEM-512" (NIST Level 1)
// - "ML-KEM-768" (NIST Level 3, priporočeno)
// - "ML-KEM-1024" (NIST Level 5)
</code>

==== EncapsulateAsync ====

Enkapsulira skupno skrivnost z javnim ključem.

<code csharp>
var (sharedSecret, ciphertext) = await provider.EncapsulateAsync(recipientPublicKey);

// sharedSecret: 32 bajtov simetrični ključ
// ciphertext: Pošlji prejemniku
</code>

==== DecapsulateAsync ====

Dekapsulira skupno skrivnost.

<code csharp>
byte[] sharedSecret = await provider.DecapsulateAsync(ciphertext, privateKey);
</code>

===== Operacije s certifikati =====

==== CreateEphemeralCertificateAsync ====

Ustvari kratkoživ ML-DSA certifikat.

<code csharp>
var (pubKey, privKey) = await provider.GenerateMlDsaKeyPairAsync();

byte[] certBytes = await provider.CreateEphemeralCertificateAsync(
    "CN=Efemerni test",
    TimeSpan.FromHours(24),
    privKey);

var cert = new X509Certificate2(certBytes);
</code>

==== SignCertificateAsync ====

Podpiše TBS-podatke certifikata z ML-DSA.

<code csharp>
byte[] tbsCertificate = GetTbsCertificate();
byte[] signedCert = await provider.SignCertificateAsync(tbsCertificate, privateKey);
</code>

===== Pregled metod =====

^ Metoda ^ Parametri ^ Vrnjeno ^
| ''InitializeAsync()'' | - | Task |
| ''GetOpenSslVersion()'' | - | string |
| ''GenerateMlDsaKeyPairAsync'' | string algorithm | Task<(byte[], byte[])> |
| ''SignMlDsaAsync'' | byte[] data, byte[] privateKey | Task<byte[]> |
| ''VerifyMlDsaAsync'' | byte[] data, byte[] signature, byte[] publicKey | Task<bool> |
| ''GenerateMlKemKeyPairAsync'' | string algorithm | Task<(byte[], byte[])> |
| ''EncapsulateAsync'' | byte[] publicKey | Task<(byte[], byte[])> |
| ''DecapsulateAsync'' | byte[] ciphertext, byte[] privateKey | Task<byte[]> |
| ''CreateEphemeralCertificateAsync'' | string subject, TimeSpan validity, byte[] privateKey | Task<byte[]> |
| ''SignCertificateAsync'' | byte[] tbsCertificate, byte[] privateKey | Task<byte[]> |

===== Konfiguracija poti OpenSSL =====

<code csharp>
// Pred InitializeAsync() nastavite pot
CryptoConfig.OpenSslPath = @"C:\OpenSSL\bin";

var provider = new NativeCryptoProvider();
await provider.InitializeAsync();
</code>

**Privzete iskalne poti:**

^ Operacijski sistem ^ Poti ^
| Windows | ''%%.\%%'', ''%%C:\OpenSSL\bin%%'', ''%%PATH%%'' |
| Linux | ''%%/usr/local/lib64%%'', ''%%/usr/lib/x86_64-linux-gnu%%'' |
| macOS | ''%%/opt/homebrew/lib%%'', ''%%/usr/local/lib%%'' |

===== Nasveti glede zmogljivosti =====

<note tip>
**Zmogljivost P/Invoke:**

  * Sinhrona izvedba v izvorni kodi
  * Task-ovoj za konsistenco API-ja z WasmCryptoProvider
  * Minimalni stroški zaradi neposrednega dostopa do pomnilnika
  * Nitno-varno preko notranje sinhronizacije OpenSSL
</note>

===== Popoln primer =====

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

// 1. Inicializacija ponudnika
var provider = new NativeCryptoProvider();
await provider.InitializeAsync();

Console.WriteLine($"OpenSSL: {provider.GetOpenSslVersion()}");

// 2. ML-KEM izmenjava ključev
var (alicePublic, alicePrivate) = await provider.GenerateMlKemKeyPairAsync();
var (bobPublic, bobPrivate) = await provider.GenerateMlKemKeyPairAsync();

// Alice enkapsulira za Boba
var (aliceSecret, ciphertext) = await provider.EncapsulateAsync(bobPublic);

// Bob dekapsulira
var bobSecret = await provider.DecapsulateAsync(ciphertext, bobPrivate);

// Skupni skrivnosti sta enaki
Console.WriteLine($"Ključi se ujemajo: {aliceSecret.SequenceEqual(bobSecret)}");

// 3. ML-DSA podpis
var (sigPubKey, sigPrivKey) = await provider.GenerateMlDsaKeyPairAsync();

byte[] message = Encoding.UTF8.GetBytes("Pomembno sporočilo");
byte[] signature = await provider.SignMlDsaAsync(message, sigPrivKey);

bool isValid = await provider.VerifyMlDsaAsync(message, signature, sigPubKey);
Console.WriteLine($"Podpis veljaven: {isValid}");
</code>

===== Varnostni nasveti =====

<note warning>
  * Zahteva OpenSSL 3.6.0 ali novejši s PQ-algoritmi
  * Zasebni ključi so shranjeni v pomnilniku procesa
  * Ob koncu aplikacije ključi niso samodejno izbrisani
  * Za najvišjo varnost: Ključe eksplicitno izbrišite s ''CryptographicOperations.ZeroMemory''
</note>

===== Glej tudi =====

  * [[.:start|Providers Namespace]]
  * [[.:icryptoprovider|ICryptoProvider]]
  * [[.:wasmcryptoprovider|WasmCryptoProvider]]
  * [[.:cryptoproviderfactory|CryptoProviderFactory]]
  * [[..:interop:opensslinterop|OpenSslInterop]]

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