swarmauri_keyprovider_aws_kms 0.11.0.dev1

AWS KMS-backed Swarmauri key provider for non-exportable key creation, alias-based rotation, KeyRef metadata, and public JWKS publishing.

Swarmauri AWS KMS Key Provider

swarmauri_keyprovider_aws_kms provides AwsKmsKeyProvider, a Swarmauri key provider backed by AWS Key Management Service. It creates non-exportable AWS KMS keys, maintains stable and versioned aliases, returns Swarmauri KeyRef metadata, publishes public JWK/JWKS material for asymmetric keys, and supports rotation and scheduled deletion workflows.

Why Swarmauri AWS KMS Key Provider?

Use this package when Swarmauri applications need AWS-managed key material without returning private keys to application memory. The provider maps Swarmauri KeySpec values to AWS KMS KeySpec and KeyUsage, keeps versioned aliases for rotation, and exposes public key metadata in a shape that downstream token, signing, and verifier components can consume.

FAQ

Q: Does this provider export private key material?

A: No. AWS KMS keys created by this provider are represented as non-exportable KeyRef objects. get_key(include_secret=True) still returns metadata and public material where available, not private material.

Q: Which AWS KMS key types are supported?

A: The provider supports symmetric AES-256-GCM through SYMMETRIC_DEFAULT, RSA OAEP SHA-256, RSA PSS SHA-256, and ECDSA P-256 SHA-256. RSA sizes map to AWS-supported 2048, 3072, or 4096 bit keys.

Q: How does rotation work?

A: rotate_key(kid) creates a new KMS key with the same algorithm metadata, creates a new alias/<prefix>/<kid>/vN alias, and repoints alias/<prefix>/<kid> to the latest version. Older version aliases remain available.

Q: Does this package call AWS KMS Sign, Encrypt, or Decrypt?

A: No. This package manages keys and public metadata. Use a signing, encryption, or envelope-encryption component for cryptographic operations that call KMS runtime APIs.

Features

• AwsKmsKeyProvider registered under the swarmauri.key_providers entry point.
• AWS KMS key creation through boto3.
• Stable latest aliases and version aliases per kid.
• Rotation by creating a new KMS key version and updating aliases.
• KeyRef metadata with KMS key ID, region, label, algorithm, version, public PEM when supported, and fingerprint.
• Public JWK conversion for RSA and P-256 public keys.
• JWKS aggregation for latest key versions.
• Scheduled key deletion with AWS KMS deletion windows.
• Local random_bytes() and HKDF helpers.
• Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.

Prerequisites

• AWS credentials resolvable by boto3.
• IAM permissions for the KMS operations you use, commonly kms:CreateKey, kms:CreateAlias, kms:UpdateAlias, kms:ListAliases, kms:DescribeKey, kms:ListResourceTags, kms:GetPublicKey, and kms:ScheduleKeyDeletion.
• An AWS region such as us-east-1.
• Optional custom key policy when account defaults are not enough for your access model.

Installation

Install with uv:

uv add swarmauri_keyprovider_aws_kms

Install with pip:

pip install swarmauri_keyprovider_aws_kms

Usage

Create and rotate a non-exportable AWS KMS key:

import asyncio

from swarmauri_keyprovider_aws_kms import AwsKmsKeyProvider
from swarmauri_core.key_providers.types import (
    ExportPolicy,
    KeyAlg,
    KeyClass,
    KeySpec,
)


async def main() -> None:
    provider = AwsKmsKeyProvider(
        region="us-east-1",
        alias_prefix="swarmauri-prod",
    )
    spec = KeySpec(
        klass=KeyClass.asymmetric,
        alg=KeyAlg.RSA_PSS_SHA256,
        size_bits=3072,
        export_policy=ExportPolicy.never_export_secret,
        label="jwt-signing",
    )

    key_ref = await provider.create_key(spec)
    rotated = await provider.rotate_key(key_ref.kid)

    print(key_ref.kid, key_ref.version)
    print(rotated.kid, rotated.version)


asyncio.run(main())

Publish public JWK metadata for verifiers:

import asyncio

from swarmauri_keyprovider_aws_kms import AwsKmsKeyProvider


async def main() -> None:
    provider = AwsKmsKeyProvider(region="us-east-1", alias_prefix="swarmauri-prod")

    jwk = await provider.get_public_jwk("jwt-signing-kid")
    jwks = await provider.jwks(prefix_kids="jwt")

    print(jwk["kid"])
    print([key["kid"] for key in jwks["keys"]])


asyncio.run(main())

Use local random bytes and HKDF helpers:

import asyncio

from swarmauri_keyprovider_aws_kms import AwsKmsKeyProvider


async def main() -> None:
    provider = AwsKmsKeyProvider(region="us-east-1")
    salt = await provider.random_bytes(32)
    secret = await provider.random_bytes(32)
    derived = await provider.hkdf(
        secret,
        salt=salt,
        info=b"swarmauri/aws-kms/example",
        length=32,
    )

    print(len(derived))


asyncio.run(main())

Related Packages

Key provider packages:

• swarmauri_keyprovider_gcpkms
• swarmauri_keyprovider_vaulttransit
• swarmauri_keyprovider_file
• swarmauri_keyprovider_local
• swarmauri_keyprovider_inmemory
• swarmauri_keyprovider_remote_jwks

Foundational packages:

• swarmauri_core defines key provider types.
• swarmauri_base provides KeyProviderBase.
• swarmauri_standard provides standard Swarmauri components.
• swarmauri provides namespace imports and plugin discovery.

Best Practices

• Use narrow IAM permissions and explicit key policies for production accounts.
• Treat scheduled deletion as destructive; inspect list_versions(kid) before calling destroy_key().
• Cache JWKS responses in verifier services, but refresh after planned rotations.
• Use clear alias_prefix values per environment to avoid mixing development and production keys.
• Keep cryptographic operations in dedicated signing or encryption components that can enforce operation-specific policy.

License

Apache-2.0