swarmauri_cipher_suite_yubikey 0.11.0.dev1

YubiKey-backed cipher suite for Swarmauri PIV signing and key transport

Swarmauri Cipher Suites YubiKey

YubiKeyCipherSuite models a conservative YubiKey configuration that focuses on PIV-backed signing and key transport. It exposes the algorithms commonly available on non-FIPS YubiKey models without promising token-side bulk encryption.

Features

• Normalizes YubiKey signing (sign/verify) and key wrap (wrap/unwrap) operations.
• Provides policy defaults for RSA-PSS and ECDSA, including default hash coupling and salt lengths.
• Surfaces dialect metadata so crypto providers can route requests to the PIV driver (piv:<alg>), including optional slot tagging.
• Documents token policy (allowed curves, hash functions, attestation expectations) in a single place.

Installation

pip

pip install swarmauri_cipher_suite_yubikey

uv (dependency)

uv add swarmauri_cipher_suite_yubikey

uv (environment)

uv pip install swarmauri_cipher_suite_yubikey

Usage

1. Instantiate the suite

from swarmauri_cipher_suite_yubikey import YubiKeyCipherSuite

suite = YubiKeyCipherSuite(name="piv-default")

The suite accepts a friendly name so you can register multiple policy variants if you run different tokens.

2. Normalize a signing request

from swarmauri_cipher_suite_yubikey import YubiKeyCipherSuite
from swarmauri_core.cipher_suites.types import KeyRef

suite = YubiKeyCipherSuite(name="piv-default")
key = KeyRef(kid="sig-slot-9c", slot="9c")
descriptor = suite.normalize(op="sign", alg="ES256", key=key)

print(descriptor["mapped"]["provider"])  # -> "piv:ES256:slot=9c"
print(descriptor["params"]["hash"])       # -> "SHA256" (defaulted)

normalize returns a dictionary with the canonical algorithm, provider identifier, defaulted parameter set, and suite policy. Crypto providers can forward these values directly to the PIV driver without re-implementing YubiKey-specific logic.

3. Wrap a key for transport

from swarmauri_cipher_suite_yubikey import YubiKeyCipherSuite

suite = YubiKeyCipherSuite(name="piv-default")
transport_descriptor = suite.normalize(op="wrap")
print(transport_descriptor["mapped"]["provider"])  # -> "piv:RSA-OAEP-256"
print(transport_descriptor["params"])              # -> {"mgf1Hash": "SHA256"}

When no algorithm is supplied, the suite picks sensible defaults (ES256 for signing, RSA-OAEP-256 for key wrap) while still respecting the policy limits.

4. Inspect supported algorithms and features

from swarmauri_cipher_suite_yubikey import YubiKeyCipherSuite

suite = YubiKeyCipherSuite(name="piv-default")

for op, algs in suite.supports().items():
    print(op, sorted(algs))

print(suite.features()["notes"][0])

These helpers allow orchestration layers to discover the token capabilities, render documentation, or validate client requests before invoking the hardware.

Entry Point

The suite registers under the swarmauri.cipher_suites entry point as YubiKeyCipherSuite.

Want to help?

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