swarmauri_crypto_paramiko 0.3.0.dev3__tar.gz → 0.3.0.dev32__tar.gz

{swarmauri_crypto_paramiko-0.3.0.dev3 → swarmauri_crypto_paramiko-0.3.0.dev32}/PKG-INFO

@@ -1,10 +1,12 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: swarmauri_crypto_paramiko
-Version: 0.3.0.dev3
+Version: 0.3.0.dev32
 Summary: Paramiko-backed RSA + AES-GCM crypto provider for Swarmauri
-License: Apache-2.0
-Author: Swarmauri
-Author-email: opensource@swarmauri.com
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: swarmauri,sdk,standards,crypto,paramiko,cryptography
+Author: Jacob Stewart
+Author-email: jacob@swarmauri.com
 Requires-Python: >=3.10,<3.13
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
@@ -15,13 +17,16 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Development Status :: 3 - Alpha
 Classifier: Topic :: Security :: Cryptography
 Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Dist: cryptography (>=41)
 Requires-Dist: paramiko (>=3.4)
 Requires-Dist: swarmauri_base
 Requires-Dist: swarmauri_core
 Description-Content-Type: text/markdown
 
-![Swamauri Logo](https://res.cloudinary.com/dbjmpekvl/image/upload/v1730099724/Swarmauri-logo-lockup-2048x757_hww01w.png)
+![Swarmauri Logo](https://github.com/swarmauri/swarmauri-sdk/blob/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)
 
 <p align="center">
     <a href="https://pypi.org/project/swarmauri_crypto_paramiko/">
@@ -40,16 +45,39 @@ Description-Content-Type: text/markdown
 
 ## Swarmauri Crypto Paramiko
 
-Paramiko-backed crypto provider implementing the `ICrypto` contract via `CryptoBase`.
+Paramiko-backed crypto provider implementing the `ICrypto` contract via
+`CryptoBase`. Built on top of [`paramiko`](https://www.paramiko.org/) and
+[`cryptography`](https://cryptography.io/), it exposes an asynchronous API for
+several cryptographic primitives using OpenSSH-formatted public keys and
+PEM-encoded private keys supplied through `KeyRef` objects.
 
-- AES-256-GCM symmetric encrypt/decrypt
-- RSA-OAEP(SHA-256) wrap/unwrap
+### Features
+
+- AES-256-GCM symmetric encrypt/decrypt (16/24/32 byte keys)
+- RSA-OAEP(SHA-256) wrap/unwrap for OpenSSH RSA key pairs
+- AES-256-GCM key wrap/unwrap when the KEK is symmetric
+- RSA-OAEP(SHA-256) sealing for small payloads
 - Multi-recipient hybrid envelopes using OpenSSH public keys
 
+Keys are represented by `KeyRef` objects. Public keys should be provided in
+OpenSSH format via `KeyRef.public`, while private keys are supplied as
+PEM-encoded bytes in `KeyRef.material`. RSA sealing is limited to inputs no
+larger than the modulus-dependent RSA-OAEP bound (`modulus_bytes - 2 * hash_len
+- 2`). For larger payloads use the hybrid envelope mode instead.
+
 ## Installation
 
+Choose the tool that matches your workflow:
+
 ```bash
+# pip
 pip install swarmauri_crypto_paramiko
+
+# Poetry
+poetry add swarmauri_crypto_paramiko
+
+# uv
+uv add swarmauri_crypto_paramiko
 ```
 
 ## Usage
@@ -106,13 +134,49 @@ wrapped = await crypto.wrap(recipient)
 unwrapped = await crypto.unwrap(recipient, wrapped)
 ```
 
+To wrap with a symmetric key-encryption key instead, provide the AES key bytes
+in `KeyRef.material` and set `wrap_alg="AES-256-GCM"`:
+
+```python
+sym_kek = KeyRef(
+    kid="kek1",
+    version=1,
+    type=KeyType.SYMMETRIC,
+    uses=(KeyUse.WRAP, KeyUse.UNWRAP),
+    export_policy=ExportPolicy.SECRET_WHEN_ALLOWED,
+    material=b"\x01" * 32,
+)
+
+wrapped = await crypto.wrap(sym_kek, wrap_alg="AES-256-GCM")
+plaintext_key = await crypto.unwrap(sym_kek, wrapped)
+```
+
+### RSA Sealing for Small Payloads
+
+```python
+# Using the `recipient` defined above
+sealed = await crypto.seal(recipient, b"tiny secret")
+plaintext = await crypto.unseal(recipient, sealed)
+```
+
 ### Hybrid Envelope for Multiple Recipients
 
 ```python
 env = await crypto.encrypt_for_many([recipient], b"secret")
 ```
 
+Calling `encrypt_for_many` without overrides produces an AES-256-GCM ciphertext
+shared by every recipient, while `env.recipients` holds RSA-OAEP-wrapped
+session keys. Use `enc_alg="RSA-OAEP-SHA256-SEAL"` to emit individual RSA-OAEP
+sealed payloads instead of a shared ciphertext when the plaintext fits within
+the sealing size limit.
+
 ## Entry point
 
 The provider is registered under the `swarmauri.cryptos` entry-point as `ParamikoCrypto`.
 
+## Want to help?
+
+If you want to contribute to swarmauri-sdk, read up on our
+[guidelines for contributing](https://github.com/swarmauri/swarmauri-sdk/blob/master/CONTRIBUTING.md)
+that will help you get started.

{swarmauri_crypto_paramiko-0.3.0.dev3 → swarmauri_crypto_paramiko-0.3.0.dev32}/README.md

@@ -1,4 +1,4 @@
-![Swamauri Logo](https://res.cloudinary.com/dbjmpekvl/image/upload/v1730099724/Swarmauri-logo-lockup-2048x757_hww01w.png)
+![Swarmauri Logo](https://github.com/swarmauri/swarmauri-sdk/blob/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)
 
 <p align="center">
     <a href="https://pypi.org/project/swarmauri_crypto_paramiko/">
@@ -17,16 +17,39 @@
 
 ## Swarmauri Crypto Paramiko
 
-Paramiko-backed crypto provider implementing the `ICrypto` contract via `CryptoBase`.
+Paramiko-backed crypto provider implementing the `ICrypto` contract via
+`CryptoBase`. Built on top of [`paramiko`](https://www.paramiko.org/) and
+[`cryptography`](https://cryptography.io/), it exposes an asynchronous API for
+several cryptographic primitives using OpenSSH-formatted public keys and
+PEM-encoded private keys supplied through `KeyRef` objects.
 
-- AES-256-GCM symmetric encrypt/decrypt
-- RSA-OAEP(SHA-256) wrap/unwrap
+### Features
+
+- AES-256-GCM symmetric encrypt/decrypt (16/24/32 byte keys)
+- RSA-OAEP(SHA-256) wrap/unwrap for OpenSSH RSA key pairs
+- AES-256-GCM key wrap/unwrap when the KEK is symmetric
+- RSA-OAEP(SHA-256) sealing for small payloads
 - Multi-recipient hybrid envelopes using OpenSSH public keys
 
+Keys are represented by `KeyRef` objects. Public keys should be provided in
+OpenSSH format via `KeyRef.public`, while private keys are supplied as
+PEM-encoded bytes in `KeyRef.material`. RSA sealing is limited to inputs no
+larger than the modulus-dependent RSA-OAEP bound (`modulus_bytes - 2 * hash_len
+- 2`). For larger payloads use the hybrid envelope mode instead.
+
 ## Installation
 
+Choose the tool that matches your workflow:
+
 ```bash
+# pip
 pip install swarmauri_crypto_paramiko
+
+# Poetry
+poetry add swarmauri_crypto_paramiko
+
+# uv
+uv add swarmauri_crypto_paramiko
 ```
 
 ## Usage
@@ -83,12 +106,49 @@ wrapped = await crypto.wrap(recipient)
 unwrapped = await crypto.unwrap(recipient, wrapped)
 ```
 
+To wrap with a symmetric key-encryption key instead, provide the AES key bytes
+in `KeyRef.material` and set `wrap_alg="AES-256-GCM"`:
+
+```python
+sym_kek = KeyRef(
+    kid="kek1",
+    version=1,
+    type=KeyType.SYMMETRIC,
+    uses=(KeyUse.WRAP, KeyUse.UNWRAP),
+    export_policy=ExportPolicy.SECRET_WHEN_ALLOWED,
+    material=b"\x01" * 32,
+)
+
+wrapped = await crypto.wrap(sym_kek, wrap_alg="AES-256-GCM")
+plaintext_key = await crypto.unwrap(sym_kek, wrapped)
+```
+
+### RSA Sealing for Small Payloads
+
+```python
+# Using the `recipient` defined above
+sealed = await crypto.seal(recipient, b"tiny secret")
+plaintext = await crypto.unseal(recipient, sealed)
+```
+
 ### Hybrid Envelope for Multiple Recipients
 
 ```python
 env = await crypto.encrypt_for_many([recipient], b"secret")
 ```
 
+Calling `encrypt_for_many` without overrides produces an AES-256-GCM ciphertext
+shared by every recipient, while `env.recipients` holds RSA-OAEP-wrapped
+session keys. Use `enc_alg="RSA-OAEP-SHA256-SEAL"` to emit individual RSA-OAEP
+sealed payloads instead of a shared ciphertext when the plaintext fits within
+the sealing size limit.
+
 ## Entry point
 
 The provider is registered under the `swarmauri.cryptos` entry-point as `ParamikoCrypto`.
+
+## Want to help?
+
+If you want to contribute to swarmauri-sdk, read up on our
+[guidelines for contributing](https://github.com/swarmauri/swarmauri-sdk/blob/master/CONTRIBUTING.md)
+that will help you get started.

{swarmauri_crypto_paramiko-0.3.0.dev3 → swarmauri_crypto_paramiko-0.3.0.dev32}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "swarmauri_crypto_paramiko"
-version = "0.3.0.dev3"
+version = "0.3.0.dev32"
 description = "Paramiko-backed RSA + AES-GCM crypto provider for Swarmauri"
 license = "Apache-2.0"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
-authors = [{ name = "Swarmauri", email = "opensource@swarmauri.com" }]
+authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
 classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Natural Language :: English",
@@ -16,6 +16,9 @@ classifiers = [
     "Development Status :: 3 - Alpha",
     "Topic :: Security :: Cryptography",
     "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
 ]
 dependencies = [
     "swarmauri_core",
@@ -23,6 +26,14 @@ dependencies = [
     "cryptography>=41",
     "paramiko>=3.4",
 ]
+keywords = [
+    'swarmauri',
+    'sdk',
+    'standards',
+    'crypto',
+    'paramiko',
+    'cryptography',
+]
 
 [tool.uv.sources]
 swarmauri_core = { workspace = true }

{swarmauri_crypto_paramiko-0.3.0.dev3 → swarmauri_crypto_paramiko-0.3.0.dev32}/swarmauri_crypto_paramiko/ParamikoCrypto.py

@@ -1,17 +1,16 @@
 """Paramiko-backed crypto provider with sealing support.
 
-Implements the ICrypto contract using:
-- AES-256-GCM for symmetric encrypt/decrypt
-- RSA-OAEP(SHA-256) for:
-    • wrapping the session key to many recipients (KEM+AEAD mode)
-    • sealing/unsealing (direct public-key encryption of plaintext) for small payloads
-
-Notes
------
-- This provider expects RSA public keys in OpenSSH format via ``KeyRef.public``.
-- For unwrap/unseal, a PEM-encoded RSA private key is expected in ``KeyRef.material``.
-- Sealing has a size limit: len(plaintext) <= (modulus_bytes - 2*hash_len - 2).
-  For larger payloads, use AES-GCM + RSA-OAEP key-wrap (encrypt_for_many with enc_alg="AES-256-GCM").
+This module implements the ``ICrypto`` contract using AES-256-GCM for
+symmetric encryption and RSA-OAEP (SHA-256) for key wrapping and direct
+sealing of small payloads.
+
+Notes:
+    - RSA public keys must be supplied in OpenSSH format via ``KeyRef.public``.
+    - For unwrap and unseal operations, ``KeyRef.material`` must contain a
+      PEM-encoded RSA private key.
+    - Sealing is limited to inputs no larger than ``modulus_bytes -
+      2*hash_len - 2``. For larger payloads use
+      ``encrypt_for_many(enc_alg="AES-256-GCM")``.
 """
 
 from __future__ import annotations
@@ -46,17 +45,27 @@ _AEAD_DEFAULT = "AES-256-GCM"
 
 @ComponentBase.register_type(CryptoBase, "ParamikoCrypto")
 class ParamikoCrypto(CryptoBase):
-    """Concrete implementation of the ICrypto contract using AES-GCM and RSA-OAEP."""
+    """Crypto provider backed by Paramiko and cryptography.
+
+    Implements AES-256-GCM for symmetric operations and RSA-OAEP for key
+    wrapping and sealing.
+    """
 
     type: Literal["ParamikoCrypto"] = "ParamikoCrypto"
 
     def supports(self) -> Dict[str, Iterable[Alg]]:
+        """Return the algorithms supported by this provider.
+
+        Returns:
+            Dict[str, Iterable[Alg]]: Mapping of operation names to the
+                algorithms the provider can execute.
+        """
+
         return {
             "encrypt": (_AEAD_DEFAULT,),
             "decrypt": (_AEAD_DEFAULT,),
             "wrap": (_WRAP_ALG,),
             "unwrap": (_WRAP_ALG,),
-            # NEW:
             "seal": (_SEAL_ALG,),
             "unseal": (_SEAL_ALG,),
         }
@@ -104,6 +113,24 @@ class ParamikoCrypto(CryptoBase):
         aad: Optional[bytes] = None,
         nonce: Optional[bytes] = None,
     ) -> AEADCiphertext:
+        """Encrypt plaintext with AES-GCM.
+
+        Args:
+            key (KeyRef): Symmetric key reference containing the key bytes.
+            pt (bytes): Plaintext to encrypt.
+            alg (Optional[Alg]): AEAD algorithm to use. Defaults to
+                ``AES-256-GCM`` when not provided.
+            aad (Optional[bytes]): Additional authenticated data.
+            nonce (Optional[bytes]): Nonce for AES-GCM. Random when omitted.
+
+        Returns:
+            AEADCiphertext: Ciphertext container with nonce and tag.
+
+        Raises:
+            UnsupportedAlgorithm: If an unsupported algorithm is requested.
+            ValueError: If the key material is missing or invalid.
+        """
+
         alg = self._normalize_aead_alg(alg)
         if alg != _AEAD_DEFAULT:
             raise UnsupportedAlgorithm(f"Unsupported AEAD algorithm: {alg}")
@@ -136,6 +163,22 @@ class ParamikoCrypto(CryptoBase):
         *,
         aad: Optional[bytes] = None,
     ) -> bytes:
+        """Decrypt ciphertext produced by :meth:`encrypt`.
+
+        Args:
+            key (KeyRef): Symmetric key reference containing the key bytes.
+            ct (AEADCiphertext): Ciphertext container to decrypt.
+            aad (Optional[bytes]): Additional authenticated data. Defaults to
+                the value stored in ``ct`` when omitted.
+
+        Returns:
+            bytes: Decrypted plaintext.
+
+        Raises:
+            UnsupportedAlgorithm: If an unsupported algorithm is requested.
+            ValueError: If the key material is missing.
+        """
+
         if self._normalize_aead_alg(ct.alg) != _AEAD_DEFAULT:
             raise UnsupportedAlgorithm(f"Unsupported AEAD algorithm: {ct.alg}")
         if key.material is None:
@@ -157,6 +200,24 @@ class ParamikoCrypto(CryptoBase):
         *,
         alg: Optional[Alg] = _SEAL_ALG,
     ) -> bytes:
+        """Seal a small plaintext to a recipient's RSA public key.
+
+        Args:
+            recipient (KeyRef): Recipient key reference with OpenSSH RSA
+                public key bytes in ``KeyRef.public``.
+            pt (bytes): Plaintext to encrypt.
+            alg (Optional[Alg]): Sealing algorithm identifier. Defaults to
+                ``RSA-OAEP-SHA256-SEAL``.
+
+        Returns:
+            bytes: Sealed ciphertext produced by RSA-OAEP.
+
+        Raises:
+            UnsupportedAlgorithm: If an unsupported algorithm is requested.
+            ValueError: If the recipient public key is missing.
+            IntegrityError: If the plaintext exceeds the RSA-OAEP size limit.
+        """
+
         if alg != _SEAL_ALG:
             raise UnsupportedAlgorithm(f"Unsupported seal alg: {alg}")
         if recipient.public is None:
@@ -182,6 +243,23 @@ class ParamikoCrypto(CryptoBase):
         *,
         alg: Optional[Alg] = _SEAL_ALG,
     ) -> bytes:
+        """Unseal ciphertext using the recipient's RSA private key.
+
+        Args:
+            recipient_priv (KeyRef): Recipient key reference containing a
+                PEM-encoded RSA private key in ``KeyRef.material``.
+            sealed (bytes): Ciphertext produced by :meth:`seal`.
+            alg (Optional[Alg]): Sealing algorithm identifier. Defaults to
+                ``RSA-OAEP-SHA256-SEAL``.
+
+        Returns:
+            bytes: Decrypted plaintext.
+
+        Raises:
+            UnsupportedAlgorithm: If an unsupported algorithm is requested.
+            ValueError: If the private key material is missing.
+        """
+
         if alg != _SEAL_ALG:
             raise UnsupportedAlgorithm(f"Unsupported seal alg: {alg}")
         if recipient_priv.material is None:
@@ -211,6 +289,33 @@ class ParamikoCrypto(CryptoBase):
         aad: Optional[bytes] = None,
         nonce: Optional[bytes] = None,
     ) -> MultiRecipientEnvelope:
+        """Encrypt plaintext for multiple recipients.
+
+        Operates in two modes:
+        1. **Sealed**: Each recipient receives an individual RSA-OAEP sealed
+           ciphertext when ``enc_alg`` is ``_SEAL_ALG``.
+        2. **KEM+AEAD**: Generates a shared AES-GCM ciphertext and wraps the
+           session key for each recipient using RSA-OAEP.
+
+        Args:
+            recipients (Iterable[KeyRef]): Sequence of recipients.
+            pt (bytes): Plaintext to encrypt.
+            enc_alg (Optional[Alg]): Encryption algorithm for the shared
+                ciphertext. Defaults to ``AES-256-GCM``.
+            recipient_wrap_alg (Optional[Alg]): Wrapping algorithm for the
+                session key. Defaults to ``RSA-OAEP-SHA256``.
+            aad (Optional[bytes]): Additional authenticated data for AES-GCM.
+            nonce (Optional[bytes]): Nonce for AES-GCM. Random when omitted.
+
+        Returns:
+            MultiRecipientEnvelope: Envelope containing ciphertext and per-
+                recipient wrapped keys.
+
+        Raises:
+            UnsupportedAlgorithm: If an unsupported algorithm is requested.
+            ValueError: If required key material is missing.
+        """
+
         # 1) Sealed-style variant (per-recipient ciphertext; no shared ct)
         if enc_alg == _SEAL_ALG:
             recip_infos: list[RecipientInfo] = []
@@ -307,13 +412,28 @@ class ParamikoCrypto(CryptoBase):
         nonce: Optional[bytes] = None,
         aad: Optional[bytes] = None,
     ) -> WrappedKey:
-        """Wrap a DEK with the given KEK.
-
-        Supports two modes:
-        * RSA-OAEP when ``wrap_alg`` is ``_WRAP_ALG`` (the legacy behaviour)
-        * AES-GCM when ``wrap_alg`` matches the default AEAD algorithm. In
-          this mode ``kek.material`` must provide the symmetric key bytes and
-          a random nonce will be generated when one isn't supplied.
+        """Wrap a data-encryption key with the given key-encryption key.
+
+        Args:
+            kek (KeyRef): Key-encryption key reference. Provide an OpenSSH
+                RSA public key in ``KeyRef.public`` for RSA-OAEP wrapping or
+                symmetric key bytes in ``KeyRef.material`` for AES-GCM.
+            dek (Optional[bytes]): Data-encryption key to wrap. A random key
+                is generated when omitted.
+            wrap_alg (Optional[Alg]): Wrapping algorithm to use. Defaults to
+                ``RSA-OAEP-SHA256``.
+            nonce (Optional[bytes]): Nonce for AES-GCM wrapping. Random when
+                omitted.
+            aad (Optional[bytes]): Additional authenticated data for AES-GCM
+                wrapping.
+
+        Returns:
+            WrappedKey: Container with the wrapped key material.
+
+        Raises:
+            UnsupportedAlgorithm: If an unsupported wrapping algorithm is
+                requested.
+            ValueError: If required key material is missing or invalid.
         """
 
         wrap_alg = wrap_alg or _WRAP_ALG
@@ -372,7 +492,24 @@ class ParamikoCrypto(CryptoBase):
         *,
         aad: Optional[bytes] = None,
     ) -> bytes:
-        """Unwrap a previously wrapped key."""
+        """Unwrap a previously wrapped key.
+
+        Args:
+            kek (KeyRef): Key-encryption key reference. Must contain the RSA
+                private key or symmetric key bytes corresponding to the
+                wrapping algorithm used.
+            wrapped (WrappedKey): Wrapped key to unwrap.
+            aad (Optional[bytes]): Additional authenticated data for AES-GCM
+                unwrapping.
+
+        Returns:
+            bytes: The unwrapped data-encryption key.
+
+        Raises:
+            UnsupportedAlgorithm: If an unsupported wrapping algorithm is
+                requested.
+            ValueError: If key material or required fields are missing.
+        """
 
         if wrapped.wrap_alg == _WRAP_ALG:
             if kek.material is None: