swarmauri_crypto_nacl_pkcs11 0.11.0.dev2

Swarmauri Crypto NaCl PKCS#11

swarmauri_crypto_nacl_pkcs11 is a hybrid crypto provider that combines PyNaCl for X25519 sealed-box operations with python-pkcs11 for AES key wrapping. The provider implements the CryptoBase contract and is discoverable via the swarmauri.cryptos entry-point as NaClPkcs11Crypto.

Supported operations

• AES-GCM authenticated encryption via encrypt/decrypt using symmetric KeyRef material that is exactly 16, 24, or 32 bytes long.
• AES Key Wrap (AES-KW) via wrap/unwrap against an HSM-protected key. The PKCS#11 session is resolved from the KeyRef.tags (module, slot_label, user_pin, label) or the environment variables PKCS11_MODULE, PKCS11_SLOT_LABEL, PKCS11_USER_PIN, and PKCS11_KEK_LABEL.
• X25519 sealed boxes via seal/unseal and encrypt_for_many, enabling single or multi-recipient payload distribution. When additional authenticated data (AAD) is supplied the envelope is rebound with AES-GCM before delivery.

Installation

Choose the workflow that matches your project:

pip install swarmauri_crypto_nacl_pkcs11

poetry add swarmauri_crypto_nacl_pkcs11

uv add swarmauri_crypto_nacl_pkcs11

Usage

All cryptographic methods are asynchronous. The quick-start example below performs an AES-GCM round trip using a 256-bit symmetric key.

import asyncio

from swarmauri_crypto_nacl_pkcs11 import NaClPkcs11Crypto
from swarmauri_core.crypto.types import ExportPolicy, KeyRef, KeyType, KeyUse


async def main() -> None:
    crypto = NaClPkcs11Crypto()

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

    ciphertext = await crypto.encrypt(symmetric_key, b"hello")
    plaintext = await crypto.decrypt(symmetric_key, ciphertext)
    assert plaintext == b"hello"


asyncio.run(main())

Sealed box key exchange

seal and encrypt_for_many expect X25519 KeyRef instances. Provide the public key bytes via KeyRef.public for recipients and the private key bytes via KeyRef.material for unsealing. Each recipient receives an opaque sealed payload generated with nacl.public.SealedBox.

PKCS#11-backed key wrapping

wrap and unwrap require a key-encryption-key (KEK) stored in the configured PKCS#11 slot. Supply connection details through KeyRef.tags or environment variables as described above. The wrapped material is returned as a WrappedKey using the AES-KW algorithm.

Want to help?

If you want to contribute to swarmauri-sdk, read up on our guidelines for contributing that will help you get started.