Add Support for Argon2d and Argon2i Variants (#13715)

* Adding test vectors for argon2d and argon2i variants

* Initial support backend for Argon2d and Argon2i variants
- Adding python class stubs

* Updating pytests to cover Argon2d and Argon2i variants

* - Modify type hints to support py3.8
- Scope Argon2Variant enum to OpenSSL >=3.2

* Updating docs for Argon2 family

* Correcting typos

* Rename base attribute and remove "allow(unused)" tag

* Correct "versionadded" docstring for Argon2d and Argon2i

* Update error message to include helpful hint when using wrong Argon2 class

* Update unit tests to exercise all Argon2 variants for derive_into

* Removing empty spacing to appease ruff

* Add derive_into interface definitions for additional Argon2 variants

Author: greateggsgreg

docs/hazmat/primitives/key-derivation-functions.rst

@@ -30,17 +30,36 @@ Different KDFs are suitable for different tasks such as:
 Variable cost algorithms
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Argon2id
---------
+Argon2 Family
+-------------
 
 .. currentmodule:: cryptography.hazmat.primitives.kdf.argon2
 
+The Argon2 family of key derivation functions are designed for password storage and is described in :rfc:`9106`.
+It consists of three variants that differ only how they access an internal memory buffer, which leads to different
+trade-offs in resistance to hardware attacks.
+
+Each of the classes constructors and parameters are the same; only details of Argon2id are defined before, for brevity.
+
+.. class:: Argon2d(*, salt, length, iterations, lanes, memory_cost, ad=None, secret=None)
+
+    .. versionadded:: 47.0.0
+
+    This variant of the Argon2 family maximizes resistance to time-memory-trade-off attacks, but introduces possible side-channels
+
+
+.. class:: Argon2i(*, salt, length, iterations, lanes, memory_cost, ad=None, secret=None)
+
+    .. versionadded:: 47.0.0
+
+    This variant of the Argon2 family resists side-channel attacks, but is vulnerable to time-memory-trade-off attacks
+
+
 .. class:: Argon2id(*, salt, length, iterations, lanes, memory_cost, ad=None, secret=None)
 
     .. versionadded:: 44.0.0
 
-    Argon2id is a KDF designed for password storage. It is designed to be
-    resistant to hardware attacks and is described in :rfc:`9106`.
+    Argon2id is a blend of the previous two variants.  Argon2id should be used by most users, as recommended in :rfc:`9106`.
 
     This class conforms to the
     :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction`

src/cryptography/hazmat/bindings/_rust/openssl/kdf.pyi

@@ -34,6 +34,48 @@ class Scrypt:
     def derive_into(self, key_material: Buffer, buffer: Buffer) -> int: ...
     def verify(self, key_material: bytes, expected_key: bytes) -> None: ...
 
+class Argon2d:
+    def __init__(
+        self,
+        *,
+        salt: bytes,
+        length: int,
+        iterations: int,
+        lanes: int,
+        memory_cost: int,
+        ad: bytes | None = None,
+        secret: bytes | None = None,
+    ) -> None: ...
+    def derive(self, key_material: bytes) -> bytes: ...
+    def derive_into(self, key_material: bytes, buffer: Buffer) -> int: ...
+    def verify(self, key_material: bytes, expected_key: bytes) -> None: ...
+    def derive_phc_encoded(self, key_material: bytes) -> str: ...
+    @classmethod
+    def verify_phc_encoded(
+        cls, key_material: bytes, phc_encoded: str, secret: bytes | None = None
+    ) -> None: ...
+
+class Argon2i:
+    def __init__(
+        self,
+        *,
+        salt: bytes,
+        length: int,
+        iterations: int,
+        lanes: int,
+        memory_cost: int,
+        ad: bytes | None = None,
+        secret: bytes | None = None,
+    ) -> None: ...
+    def derive(self, key_material: bytes) -> bytes: ...
+    def derive_into(self, key_material: bytes, buffer: Buffer) -> int: ...
+    def verify(self, key_material: bytes, expected_key: bytes) -> None: ...
+    def derive_phc_encoded(self, key_material: bytes) -> str: ...
+    @classmethod
+    def verify_phc_encoded(
+        cls, key_material: bytes, phc_encoded: str, secret: bytes | None = None
+    ) -> None: ...
+
 class Argon2id:
     def __init__(
         self,

src/cryptography/hazmat/primitives/kdf/argon2.py

@@ -7,7 +7,11 @@
 from cryptography.hazmat.bindings._rust import openssl as rust_openssl
 from cryptography.hazmat.primitives.kdf import KeyDerivationFunction
 
+Argon2d = rust_openssl.kdf.Argon2d
+Argon2i = rust_openssl.kdf.Argon2i
 Argon2id = rust_openssl.kdf.Argon2id
+KeyDerivationFunction.register(Argon2d)
+KeyDerivationFunction.register(Argon2i)
 KeyDerivationFunction.register(Argon2id)
 
-__all__ = ["Argon2id"]
+__all__ = ["Argon2d", "Argon2i", "Argon2id"]