stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/modules/sm-remote/architecture.md

3.4 KiB
Raw Permalink Blame History

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.