swarmauri_crypto_paramiko 0.4.0.dev3

Paramiko-backed RSA + AES-GCM crypto provider for Swarmauri

---

Swarmauri Crypto Paramiko

Paramiko-backed crypto provider implementing the ICrypto contract via CryptoBase. Built on top of paramiko and cryptography, it exposes an asynchronous API for several cryptographic primitives using OpenSSH-formatted public keys and PEM-encoded private keys supplied through KeyRef objects.

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:

# pip
pip install swarmauri_crypto_paramiko

# Poetry
poetry add swarmauri_crypto_paramiko

# uv
uv add swarmauri_crypto_paramiko

Usage

Symmetric AEAD Encryption

from swarmauri_crypto_paramiko import ParamikoCrypto
from swarmauri_core.crypto.types import KeyRef, KeyType, KeyUse, ExportPolicy

crypto = ParamikoCrypto()

sym = KeyRef(
    kid="sym1",
    version=1,
    type=KeyType.SYMMETRIC,
    uses=(KeyUse.ENCRYPT, KeyUse.DECRYPT),
    export_policy=ExportPolicy.SECRET_WHEN_ALLOWED,
    material=b"\x00" * 32,
)

ct = await crypto.encrypt(sym, b"hello")
pt = await crypto.decrypt(sym, ct)

RSA Key Wrapping/Unwrapping

import paramiko
from cryptography.hazmat.primitives import serialization
from swarmauri_core.crypto.types import KeyRef, KeyType, KeyUse, ExportPolicy

crypto = ParamikoCrypto()

key = paramiko.RSAKey.generate(2048)
pub_line = f"{key.get_name()} {key.get_base64()}\n".encode()
priv_pem = key.key.private_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PrivateFormat.PKCS8,
    encryption_algorithm=serialization.NoEncryption(),
)

recipient = KeyRef(
    kid="rsa1",
    version=1,
    type=KeyType.RSA,
    uses=(KeyUse.WRAP, KeyUse.UNWRAP),
    export_policy=ExportPolicy.PUBLIC_ONLY,
    public=pub_line,
    material=priv_pem,
)

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":

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

# Using the `recipient` defined above
sealed = await crypto.seal(recipient, b"tiny secret")
plaintext = await crypto.unseal(recipient, sealed)

Hybrid Envelope for Multiple Recipients

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 that will help you get started.