====== KeyDerivation Namespace ======

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

Contains classes for key derivation (KDF) with PQ support.

----

===== Classes =====

^  Class  ^  Description  ^
| KeyDerivationExtensions | KDF functions (HKDF, PBKDF2, Argon2id) |
| HybridKeyMaterial | Container for derived keys |
| TlsKeyMaterial | TLS-style key material |
| Tls13KeySchedule | TLS 1.3 key schedule |

----

===== Supported KDFs =====

^  Function  ^  Standard  ^  Usage  ^
| HKDF | RFC 5869((RFC 5869: https://datatracker.ietf.org/doc/html/rfc5869)) | Session keys from shared secret |
| PBKDF2 | RFC 8018((RFC 8018: https://datatracker.ietf.org/doc/html/rfc8018)) | Password-based keys |
| Argon2id | RFC 9106((RFC 9106: https://datatracker.ietf.org/doc/html/rfc9106)) | Memory-hard KDF |

----

===== Example =====

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

byte[] sharedSecret = /* from ML-KEM */;
byte[] salt = RandomNumberGenerator.GetBytes(32);

// HKDF for session keys
byte[] aesKey = KeyDerivationExtensions.DeriveKey(
    sharedSecret,
    outputLength: 32,
    salt: salt,
    info: Encoding.UTF8.GetBytes("AES-256-GCM"));

// Hybrid key derivation
byte[] hybridKey = KeyDerivationExtensions.DeriveHybridKey(
    classicSecret: ecdhSecret,
    pqSecret: mlKemSecret,
    outputLength: 32);
</code>

----

===== Main Methods =====

==== HKDF ====

^ Method ^ Description ^
| ''DeriveKey'' | HKDF Extract-then-Expand |
| ''HkdfExtract'' | Extracts PRK from IKM |
| ''HkdfExpand'' | Expands PRK to output key |

==== Hybrid ====

^ Method ^ Description ^
| ''DeriveHybridKey'' | Combines classic + PQ secrets |
| ''DeriveHybridKeyMaterial'' | Derives multiple keys |

==== Password-based ====

^ Method ^ Description ^
| ''Pbkdf2'' | Standard PBKDF2 with optional PQ entropy |
| ''Pbkdf2WithPqSalt'' | PBKDF2 with PQ-enhanced salt |
| ''Argon2id'' | Memory-hard KDF via OpenSSL 3.6 |

==== TLS ====

^ Method ^ Description ^
| ''DeriveTlsKeys'' | TLS 1.2 style key material |
| ''DeriveTls13Keys'' | TLS 1.3 key schedule |

----

===== Recommended Argon2id Parameters =====

^ Application ^ Iterations (t) ^ Memory (m) ^ Parallelism (p) ^
| Password hashing | 3 | 64 MB | 4 |
| High security | 4 | 256 MB | 4 |
| Low memory | 4 | 16 MB | 4 |

----

===== Security Note =====

<WRAP important>
**Hybrid mode security:**

In hybrid mode, the final key is only compromised if BOTH secrets (classic AND PQ) are broken. This provides protection against both classical and quantum attacks.
</WRAP>

----

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

  * [[.:keyexchange|KeyExchange Namespace]]
  * [[.:encryption|Encryption Namespace]]
  * [[.:start|API Overview]]

{{tag>namespace kdf hkdf pbkdf2 argon2id}}

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