# 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.