swarmauri_certservice_aws_kms 0.3.4.dev3

AWS KMS backed CertService for Swarmauri

swarmauri_certservice_aws_kms

AWS KMS backed certificate service for Swarmauri.

This package provides an implementation of CertServiceBase that signs and verifies X.509 certificates using AWS Key Management Service.

Features

• Create CSRs from exportable key material.
• Issue certificates using AWS KMS Sign API.
• Create self‑signed certificates.
• Verify and parse certificates with RFC 5280 compliance.

Prerequisites

• Python 3.10 or newer.
• AWS account with KMS keys that allow the Sign operation (RSA or ECC_NIST_P256).
• AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY (or an IAM role/instance profile) granting kms:GetPublicKey and kms:Sign permissions.
• boto3 installed (automatically pulled in via this package) and network access to the target AWS region.
• For certificate signing: an issuer subject template and optional CA certificate bytes to embed in verification metadata.

Extras

• docs: documentation helpers.
• perf: benchmarking support.

Installation

# pip
pip install swarmauri_certservice_aws_kms

# poetry
poetry add swarmauri_certservice_aws_kms

# uv (pyproject-based projects)
uv add swarmauri_certservice_aws_kms

Testing

Run unit, functional and performance tests in isolation from the repository root:

uv run --package swarmauri_certservice_aws_kms --directory community/swarmauri_certservice_aws_kms pytest

Quickstart: Issue a Certificate with AWS KMS

The snippet below signs an incoming CSR using a customer-managed KMS key. Attach the key ARN to the KeyRef via kid or tags (aws_kms_key_id).

import asyncio
from datetime import datetime, timedelta, timezone
from pathlib import Path

from swarmauri_certservice_aws_kms import AwsKmsCertService
from swarmauri_core.crypto.types import KeyRef


async def main() -> None:
    service = AwsKmsCertService(region_name="us-east-1")

    csr_bytes = Path("tenant.csr").read_bytes()
    ca_cert = Path("ca.pem").read_bytes()

    kms_key = KeyRef(kid="arn:aws:kms:us-east-1:123456789012:key/abcd-1234")

    certificate_pem = await service.sign_cert(
        csr=csr_bytes,
        ca_key=kms_key,
        issuer={"CN": "Example KMS Issuing CA", "O": "Example Corp"},
        ca_cert=ca_cert,
        not_after=int((datetime.now(timezone.utc) + timedelta(days=365)).timestamp()),
    )

    Path("tenant.pem").write_bytes(certificate_pem)
    print("Issued certificate saved to tenant.pem")


if __name__ == "__main__":
    asyncio.run(main())

Generating CSRs and Self-Signed Roots

AwsKmsCertService can build CSRs from exportable key material and mint a self-signed certificate using the same KMS key.

import asyncio
from datetime import datetime, timedelta, timezone
from pathlib import Path

from swarmauri_certservice_aws_kms import AwsKmsCertService
from swarmauri_core.crypto.types import KeyRef


async def bootstrap_ca() -> None:
    service = AwsKmsCertService(region_name="us-east-1")

    # Generate CSR from a local private key
    key_ref = KeyRef(material=Path("intermediate-key.pem").read_bytes())
    csr_pem = await service.create_csr(
        key=key_ref,
        subject={"CN": "Example Intermediate CA", "O": "Example Corp"},
        san={"dns": ["intermediate.example.com"]},
    )
    Path("intermediate.csr").write_bytes(csr_pem)

    # Issue a self-signed root using a KMS key
    kms_key = KeyRef(kid="arn:aws:kms:us-east-1:123456789012:key/root-ca-key")
    root_pem = await service.create_self_signed(
        key=kms_key,
        subject={"CN": "Example Root CA", "O": "Example Corp"},
        not_after=int((datetime.now(timezone.utc) + timedelta(days=3650)).timestamp()),
    )
    Path("root-ca.pem").write_bytes(root_pem)


if __name__ == "__main__":
    asyncio.run(bootstrap_ca())

Best Practices

• Grant the KMS key limited permissions: kms:GetPublicKey, kms:DescribeKey, kms:Sign. Avoid broad grants (e.g., wildcard actions).
• Store KMS key ARNs in KeyRef.tags["aws_kms_key_id"] or KeyRef.kid for clarity and to avoid hard-coding ARNs throughout application logic.
• Coordinate certificate validity with KMS key rotation—renew certificates before rotating customer-managed keys.
• Cache returned certificates and metadata to minimize repeated calls to KMS and reduce signing latency.