SM Remote (SM Cipher Suite Service)
Stateless cryptographic operations microservice for Chinese national standard algorithms (SM2/SM3/SM4).
Purpose
SM Remote provides Chinese national standard cryptographic algorithms (SM2 signing/verification, SM3 hashing, SM4 encryption/decryption) as a stateless microservice for regional compliance requirements. It enables Stella Ops deployments to satisfy GB/T standards by offering both soft-provider (BouncyCastle) and optional HSM/remote provider modes for production key management.
Quick Links
- Architecture
- Vendor adapter contract
- Cryptography module
- Signer module (consumer)
- AirGap module (consumer)
Status
| Attribute | Value |
|---|---|
| Maturity | Production |
| Source | src/SmRemote/ |
Key Features
- SM2 digital signatures (sm2p256v1 / SM2P256V1 recommended curve)
- SM3 cryptographic hashing
- SM4-ECB encryption/decryption with PKCS7 padding
- Operation-specific authorization scopes for hash, encrypt, decrypt, sign, and verify
- Ephemeral SM2 key management (gated by TTL + audit), restricted to explicit Development/Testing local harnesses
- Optional remote HSM/vendor-adapter bridge (
cn.sm.remote.http) with fail-closed vendor contract validation - Fail-closed production posture for software-only or unconfigured remote provider runtime
API Surface
The service exposes minimal-API HTTP endpoints. Routes are reached through the Stella Router under the smremote service name (see Program.cs AddRouterMicroservice(..., serviceName: "smremote", ...)).
| Method & Route | Auth | Scope (policy) | Algorithm / Behavior |
|---|---|---|---|
GET /health | Anonymous | — | Liveness; returns {status, provider, adapterId?, adapterKind?, contractVersion?}. In remote mode, probes the adapter and returns 503 on contract/HTTP/timeout failure. |
GET /status | Anonymous | — | Capability/availability; returns {available, provider, algorithms, adapterId?, adapterKind?, contractVersion?, keys?}. Default advertised algorithm is SM2. |
POST /hash | Bearer | sm-remote:hash (SmRemote.Hash) | SM3 digest. Returns {algorithmId, hashBase64, hashHex}. |
POST /encrypt | Bearer | sm-remote:encrypt (SmRemote.Encrypt) | SM4-ECB + PKCS7. Soft mode uses a 16-byte keyBase64; remote mode requires keyId. |
POST /decrypt | Bearer | sm-remote:decrypt (SmRemote.Decrypt) | SM4-ECB + PKCS7. Soft mode uses a 16-byte keyBase64; remote mode requires keyId. |
POST /sign | Bearer | sm-remote:sign (SmRemote.Sign) | SM2 signature over payloadBase64. Returns {signature}. |
POST /verify | Bearer | sm-remote:verify (SmRemote.Verify) | SM2 verification. Returns {valid}. |
Scopes are defined canonically in StellaOps.Auth.Abstractions/StellaOpsScopes.cs (SmRemoteHash, SmRemoteEncrypt, SmRemoteDecrypt, SmRemoteSign, SmRemoteVerify) and bound to named policies in Security/SmRemotePolicies.cs. The supported hash algorithm is SM3; the supported symmetric algorithm is SM4/SM4-ECB; the supported signature algorithm is SM2.
Configuration
Provider selection (SmRemote:Provider): cn.sm.remote.http (or remote) for the HSM bridge, cn.sm.soft (or soft) for the local soft provider. In Development/Testing the default is the soft provider; otherwise the default is the remote provider.
Remote (HSM bridge) keys, read by SmRemoteRuntimeOptions.ApplyConfiguration:
SMREMOTE_PROVIDER/SM_REMOTE_PROVIDERSM_REMOTE_HSM_URL— absolute HTTP(S) adapter endpointSMREMOTE_KEYS/SM_REMOTE_KEYS/SM_REMOTE_HSM_KEYS—localKeyId=remoteKeyIdlist (comma/semicolon separated)SM_REMOTE_HSM_API_KEYandSM_REMOTE_HSM_REQUIRE_API_KEYSM_REMOTE_HSM_TIMEOUT(milliseconds; default 30000)SM_REMOTE_HSM_ADAPTER_KIND/SMREMOTE_ADAPTER_KIND— one ofsm-hsm,sdf,pkcs11(defaultsm-hsm)SM_REMOTE_HSM_CONTRACT_VERSION/SMREMOTE_ADAPTER_CONTRACT_VERSION— defaultsm-remote-vendor-adapter.v1SM_REMOTE_HSM_REQUIRE_VENDOR_CONTRACT/SMREMOTE_REQUIRE_VENDOR_CONTRACTSMREMOTE_DURABLE_KEY_STORE
Soft / ephemeral runtime gates:
SMREMOTE_ALLOW_SOFTWARE_PROVIDER/SM_SOFT_ALLOWEDSMREMOTE_ALLOW_EPHEMERAL_KEYS/SM_EPHEMERAL_KEYS_ALLOWED(defaultfalse)SMREMOTE_EPHEMERAL_KEY_TTL/SM_EPHEMERAL_KEY_TTL(ISO-8601 duration, e.g.PT1H; required when ephemeral keys are enabled)SMREMOTE_RUNTIME_ID/SM_REMOTE_RUNTIME_ID
Vendor Adapter Contract
In remote mode the service bridges to an operator-controlled vendor HSM adapter and validates its responses fail-closed. Before sign/verify/encrypt/decrypt it probes the adapter /status and /keys and rejects mismatches (failure classes such as key_mapping_missing, key_usage_mismatch), returning 502/503 problem responses with a failureClass extension. Adapter kinds are validated against sm-hsm, sdf, and pkcs11. The contract is documented in the SM Remote vendor adapter contract.
Dependencies
Upstream
- Authority - authentication for service-to-service calls
- Cryptography - shared cryptographic primitives and abstractions
Downstream
- Signer - SM cipher operations for signing workflows
- AirGap - regional crypto support in offline environments
Storage & Background Workers
The service is stateless and owns no database schema. The only stateful surface is in-process: the EphemeralKeyRegistry (tracks minted ephemeral SM2 keys for this process lifetime) and the EphemeralKeyAuditLog. A single hosted BackgroundService, EphemeralKeyRotationService, sweeps the registry on an interval (default 30s), evicts expired ephemeral keys from the soft provider, and emits audit events. It is a no-op when ephemeral keys are disabled.
Ephemeral Key Lifecycle & Audit
When SMREMOTE_ALLOW_EPHEMERAL_KEYS is enabled (Development/Testing only) and a positive TTL is configured, the first /sign or /verify for an unknown key id mints an ephemeral SM2 key on the soft provider. Each key is stamped with ephemeral, expiresAt, seededBy (RuntimeId), seededAt, and ttl metadata. The audit log records sm-remote.key.seeded on mint and sm-remote.key.rotated on expiry-eviction. The audit log is process-local today (a future sprint may forward to the central audit chain).
Runtime Posture
Development and Testing may use cn.sm.soft with ephemeral key seeding for local deterministic harnesses (ephemeral seeding must be explicitly opted in via SMREMOTE_ALLOW_EPHEMERAL_KEYS=true plus a positive SMREMOTE_EPHEMERAL_KEY_TTL; the implicit-default seeding was removed). Production must disable software and ephemeral modes (SMREMOTE_ALLOW_SOFTWARE_PROVIDER=0, SMREMOTE_ALLOW_EPHEMERAL_KEYS=0) and register a hardware/remote provider adapter before cryptographic authority is available. Startup ValidateOnStart enforces these gates and rejects unsafe production configuration (e.g. soft provider, missing SM_REMOTE_HSM_URL, missing key mappings, or disabled vendor contract validation).