61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
# SM Remote Architecture
|
|
|
|
> Stateless microservice providing Chinese national standard cryptographic operations (SM2/SM3/SM4) via HTTP endpoints.
|
|
|
|
## Overview
|
|
|
|
SM Remote is a single-project ASP.NET Core microservice that exposes SM-series cryptographic operations over HTTP. It is designed to be stateless: no database is required, and ephemeral key pairs are seeded on demand per `keyId`. The service supports two provider modes -- a soft provider backed by BouncyCastle for development and testing, and a remote provider that delegates to an HSM for production deployments.
|
|
|
|
## Components
|
|
|
|
```
|
|
src/SmRemote/
|
|
StellaOps.SmRemote.Service/ # ASP.NET Core web service
|
|
Program.cs # Host configuration and endpoint registration
|
|
Providers/
|
|
SoftSmProvider.cs # BouncyCastle-based SM2/SM3/SM4 (cn.sm.soft)
|
|
RemoteSmProvider.cs # HSM-delegating provider (cn.sm.remote.http)
|
|
Models/ # Request/response DTOs
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
1. An upstream service (Signer, AirGap) sends a cryptographic operation request (sign, verify, hash, encrypt, decrypt) to SM Remote.
|
|
2. SM Remote selects the configured provider (soft or remote).
|
|
3. For signing/verification, the service seeds an ephemeral SM2 key pair on first use for the given `keyId` using EC domain parameters (SM2P256V1 curve).
|
|
4. The provider executes the operation and returns the result.
|
|
5. No state is persisted between requests; key material is ephemeral within the process lifecycle.
|
|
|
|
## Database Schema
|
|
|
|
Not applicable. SM Remote is a stateless service with no persistent storage.
|
|
|
|
## Dependencies
|
|
|
|
| Service/Library | Purpose |
|
|
|---------------------|----------------------------------------------|
|
|
| BouncyCastle | SM2/SM3/SM4 algorithm implementations (soft provider) |
|
|
| Pkcs11Interop | PKCS#11 interface for HSM integration (remote provider) |
|
|
| Router | Service mesh routing and discovery |
|
|
| Authority | JWT/OAuth token validation for inbound requests |
|
|
|
|
## Endpoints
|
|
|
|
| Method | Path | Description |
|
|
|--------|-------------|---------------------------------------------|
|
|
| POST | `/hash` | Compute SM3 hash of input data |
|
|
| POST | `/encrypt` | SM4-ECB encrypt with PKCS7 padding |
|
|
| POST | `/decrypt` | SM4-ECB decrypt with PKCS7 padding |
|
|
| POST | `/sign` | SM2 digital signature (P-256v1) |
|
|
| POST | `/verify` | SM2 signature verification |
|
|
| GET | `/status` | Provider status and configuration |
|
|
| GET | `/health` | Health check |
|
|
|
|
## Security Considerations
|
|
|
|
- **mTLS**: Inter-service calls use mutual TLS for transport security.
|
|
- **Ephemeral key lifecycle**: SM2 key pairs are generated per `keyId` and exist only in process memory. Key material is not persisted to disk.
|
|
- **HSM offloading**: Production deployments should use the remote provider (`cn.sm.remote.http`) to delegate key operations to a hardware security module, ensuring key material never leaves the HSM boundary.
|
|
- **No key export**: The service does not expose endpoints for exporting private key material.
|
|
- **Provider selection**: The active provider is configured at startup; switching providers requires a service restart to prevent mixed-mode operation.
|