This service isolates cloud-vendor SDKs from the contract API. The Alibaba Cloud KMS Instance SDK is supplied by the reviewed compatibility build under vendor/alibaba-kms-modern; it must run in its own image or virtual environment.

The contract API calls POST /v1/encrypt, POST /v1/decrypt, POST /v1/sign, and POST /v1/public-key with a service bearer token loaded from a file. Envelope-encryption keys and asymmetric signing keys use separate allowlists. Cloud credentials, client keys and passwords are file-backed and are never accepted in request bodies; private signing material never leaves KMS.

The canonical build is the repository Dockerfile. It downloads hash-locked runtime inputs, builds the two Alibaba compatibility wheels from hash-verified upstream sources, and verifies the dependency closure without consulting global site-packages:

docker build -f yuqei-infra/docker/kms-gateway.Dockerfile .

Do not use pip install -e ".[test]" directly: the +yuqei distributions are intentionally absent from public package indexes. For a local Linux x86_64 Python 3.12 test environment, replay the kms-gateway job in .github/workflows/build-test-quality-gate.yml, including all three hash locks, then run PYTHONPATH=src python -m pytest -q.

GET /health is a non-secret liveness/configuration summary. Provider calls are not made by the health endpoint. Production readiness still requires a real round-trip recovery drill from the contract administration console.

The Alibaba Cloud credential set consists of the KMS instance ClientKey JSON, its password in a separate file, the KMS instance CA, and the dedicated instance endpoint. The Tencent Cloud credential file is a read-only JSON object with secret_id, secret_key, and an optional short-lived token; prefer STS credentials. Both deployments also require an independent gateway service token, TLS certificate/key, and a restrictive key allowlist.

Configure YUQEI_KMS_GATEWAY_ALLOWED_KEY_IDS for encryption keys and YUQEI_KMS_GATEWAY_ALLOWED_SIGNING_KEY_IDS for dedicated asymmetric signing keys. A signing key must not be reused for calendar credential encryption.

Production compose overlays:

yuqei-infra/compose/docker-compose.production.kms-aliyun.yml
yuqei-infra/compose/docker-compose.production.kms-tencent.yml

Run only one provider overlay at a time. See project-docs/playbook-cloud-kms-rewrap-fault-drill-runbook-2026-08-25.md for rollout, rewrap, failure-injection, and rollback gates.

Official contracts used by the adapters: