Swarmauri Step-ca Certificate Service
Community plugin providing a step-ca backed certificate service for Swarmauri. It turns the generic ICertService workflows into calls against the smallstep step-ca REST API so agents can request certificates without hand-crafting HTTP payloads.
Features
- Generate RFC 2986-compliant PKCS#10 certificate signing requests with SANs, challenge passwords, and custom extensions.
- Exchange CSRs for signed certificates through the step-ca
/1.0/signendpoint, including provisioner selection and template data. - Asynchronous HTTP client with configurable TLS verification, timeouts, and one-time token (OTT) acquisition via a pluggable
token_provider. - Structured capability introspection through
supports()so orchestrators can negotiate key algorithms and features.
Prerequisites
- Python 3.10 or newer.
- Reachable step-ca instance (hosted or self-managed) exposing the
/1.0/signAPI. - Provisioner configured in step-ca with one-time token authentication. Either supply OTTs directly at request time or provide an async
token_providerfunction that returns them when asked. - Local private key material for each CSR you plan to submit; embed it in
KeyRef.materialor wire in your own key management layer.
Installation
# pip
pip install swarmauri_certservice_stepca
# poetry
poetry add swarmauri_certservice_stepca
# uv (pyproject-based projects)
uv add swarmauri_certservice_stepca
Quickstart: Issue a Certificate via step-ca
import asyncio
from pathlib import Path
from swarmauri_certservice_stepca import StepCaCertService
from swarmauri_core.certs.ICertService import SubjectSpec
from swarmauri_core.crypto.types import ExportPolicy, KeyRef, KeyType, KeyUse
async def enroll() -> None:
async def fetch_ott(claims):
# Look up the device-specific token issued by step-ca (KV store, API call, etc).
device_id = claims["sub"] or "default"
return Path(f"otts/{device_id}.txt").read_text().strip()
service = StepCaCertService(
ca_url="https://ca.example",
provisioner="devices",
token_provider=fetch_ott,
timeout_s=10.0,
)
key_bytes = Path("device.key.pem").read_bytes()
key_ref = KeyRef(
kid="device-key",
version=1,
type=KeyType.RSA,
uses=(KeyUse.SIGN,),
export_policy=ExportPolicy.SECRET_WHEN_ALLOWED,
material=key_bytes,
)
subject: SubjectSpec = {
"C": "US",
"O": "Example Corp",
"CN": "device-001.example.com",
}
csr_pem = await service.create_csr(
key=key_ref,
subject=subject,
san={"dns": ["device-001.example.com", "device-001"]},
extensions={
"extended_key_usage": {"oids": ["serverAuth", "clientAuth"]},
},
)
cert_pem = await service.sign_cert(csr_pem, ca_key=key_ref)
Path("device.pem").write_bytes(cert_pem)
await service.aclose()
print("Certificate written to device.pem")
if __name__ == "__main__":
asyncio.run(enroll())
The service extracts the subject name from the CSR and passes it to the token_provider, making it easy to map devices to their OTTs. If you already possess the token, skip the provider and pass it in via opts={"ott": "..."} when calling sign_cert.
Control Validity Windows and Template Data
import asyncio
from datetime import datetime, timedelta, timezone
from pathlib import Path
from swarmauri_certservice_stepca import StepCaCertService
from swarmauri_core.crypto.types import ExportPolicy, KeyRef, KeyType, KeyUse
async def request_short_lived_cert(ott: str) -> bytes:
service = StepCaCertService("https://ca.example", verify_tls="/etc/ssl/ca.pem")
key_ref = KeyRef(
kid="build-runner",
version=1,
type=KeyType.EC,
uses=(KeyUse.SIGN,),
export_policy=ExportPolicy.SECRET_WHEN_ALLOWED,
material=Path("runner-key.pem").read_bytes(),
)
csr = await service.create_csr(
key_ref,
{"CN": "ci-runner", "O": "Example Corp"},
)
now = datetime.now(timezone.utc)
cert = await service.sign_cert(
csr,
key_ref,
not_before=int(now.timestamp()),
not_after=int((now + timedelta(hours=8)).timestamp()),
opts={
"ott": ott,
"template_data": {"env": "ci", "workload": "runner"},
},
)
await service.aclose()
return cert
# Usage
# asyncio.run(request_short_lived_cert(os.environ["STEPCA_OTT"]))
sign_cert automatically normalizes DER and PEM inputs, propagates custom template data, and honors explicit validity windows when your provisioner allows overrides.
Operational Tips
- Close the underlying HTTP client with
aclose()once you are done issuing certificates to release sockets. - Provisioners can restrict key algorithms and SAN contents—call
supports()to check compatibility before presenting the service to end users. - Store OTTs in a secure vault or request them just-in-time from step-ca’s ACME/JWT machinery; never hard-code long-lived tokens in scripts.
- Combine this service with Swarmauri verification agents (CRL/OCSP) or your preferred PKI lints to track certificate health after issuance.
Metadata
Release files for swarmauri_certservice_stepca 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| swarmauri_certservice_stepca-0.3.3.tar.gz | 11.4 kB | Without provenance | Details for swarmauri_certservice_stepca-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swarmauri_certservice_stepca-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for swarmauri_certservice_stepca-0.3.3-py3-none-any.whl |
Total release size: 23.9 kB
Release files / swarmauri_certservice_stepca-0.3.3.tar.gz
| Download URL | swarmauri_certservice_stepca-0.3.3.tar.gz |
|---|---|
| Size | 11.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
511f4569d39ddd1f2c37bf402518c641f7f9e7272168c5cabeb0b709c57cd83e
|
|
BLAKE2b-256 checksum How to use checksums |
03bb543c65b94db22d238228ecb7bca903e5818587d0d47d31419a9cf28cae79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.0 {"installer":{"name":"uv","version":"0.11.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / swarmauri_certservice_stepca-0.3.3-py3-none-any.whl
| Download URL | swarmauri_certservice_stepca-0.3.3-py3-none-any.whl |
|---|---|
| Size | 12.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4b7c5f365798e0a2a2bfc3ce188a4cbe1fd92cb81f66a7ccc83da424fb6676c
|
|
BLAKE2b-256 checksum How to use checksums |
f99430b86a55df5ed57da776eb92a9ebe53d0c0729aff37822c79f4b6bf60f09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.0 {"installer":{"name":"uv","version":"0.11.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for swarmauri_certservice_stepca 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.