Files
ssw-mvp/scard/code/README.md
T
admin 3247e9fd15 init: ssw-mvp initial commit
- boot/ (Java/Maven, JNPF 7.0) — 移除旧的 boot/.git,源码直接纳入仓库
- web/ (Vue 3 + Vite + Ant Design Vue, pnpm)
- docs/, scard/, nax/
- refs/INDEX.md + refs/国标/(其余 refs/* 开源子仓库不纳入)
- 已忽略: connector_data/, jweb/, log/, web/{dist,node_modules,.pnpm}, boot/*/target/, .DS_Store, .idea, .vscode
2026-08-05 18:29:12 +08:00

4.3 KiB

security-connector

Secure Connector Backend System

A security-focused backend system for managing connector devices with TPM-based hardware security, ECDH key exchange, and policy-based access control.

Architecture

code/
├── server/          # Server-side components (x86 Linux)
│   ├── main.go      # Server entry point
│   ├── api/         # REST API handlers
│   ├── crypto/      # Server-side cryptographic operations
│   ├── auth/        # Device authentication
│   ├── keyring/     # KEK/DEK management
│   ├── policy/      # RBAC/ABAC policy engine
│   ├── audit/       # Audit logging
│   └── easytier/    # EasyTier tunnel coordination
│
├── connector/       # Connector-side components (Host x86)
│   ├── main.go      # Connector entry point
│   ├── tpm/         # TPM interface (mock for Phase 1)
│   ├── keys/        # Local key management
│   ├── k3s/         # k3s API gateway
│   └── register/    # Device registration flow
│
├── common/          # Shared modules
│   ├── proto/       # Protocol message definitions
│   ├── crypto/      # Shared cryptographic primitives
│   └── types/       # Shared type definitions
│
├── scripts/
│   └── cloudinit/  # Cloud-init configuration generator
│
└── tests/           # Tests

Key Protocols

1. Device Registration (AUTH_REGISTER)

  • Connector sends CSR with TPM public key
  • Server validates and derives KEK via ECDH
  • Server returns encrypted KEK and session certificate

2. Challenge-Response (Runtime Auth)

  • Server sends Nonce + Challenge
  • Connector signs with TPM private key
  • Server verifies signature and derives session key

3. Key Incremental Update

  • Partial key updates via offset/length
  • Server FPGA signature required
  • Version checking prevents rollback

Key Hierarchy

Layer 0: TPM SRK (device hardware root trust)
Layer 1: KEK (Key Encryption Key) - derived via ECDH
Layer 2: DEK (Data Encryption Key) - encrypted by KEK
Layer 3: Session Keys (mTLS) - short-lived
Layer 4: Server Root Key (HSM-level)

API Endpoints

Method Path Description
POST /api/v1/device/register Device registration
POST /api/v1/device/challenge Get challenge for auth
POST /api/v1/device/auth Submit challenge response
GET /api/v1/device/{id}/status Get device status
POST /api/v1/key/incremental-update Incremental key update
POST /api/v1/easytier/join Join EasyTier network
POST /api/v1/k3s/join Join k3s cluster

Building

# Server
cd server && go build -o security-server .

# Connector
cd connector && go build -o connector .

# Cloud-init generator
cd scripts/cloudinit && chmod +x generate.sh

Running

# Server
./security-server --listen :8443 --data-dir /var/lib/security-connector

# Connector
./connector --server https://localhost:8443 --device-id DEV_001 --register

Cloud-init Configuration

# Generate cloud-init for a new device
./scripts/cloudinit/generate.sh \
    --device-id DEV_host1_001 \
    --server-url https://connector-server:8443 \
    --network-id secure-net \
    --output cloud-init.yaml

Development

Phase 1 (Current)

  • Protocol message definitions (proto/)
  • Server API handlers (server/api/)
  • Server-side crypto (server/crypto/)
  • Device authentication (server/auth/)
  • Key management (server/keyring/)
  • Policy engine (server/policy/)
  • Audit logging (server/audit/)
  • EasyTier coordinator (server/easytier/)
  • Mock TPM (connector/tpm/)
  • Connector key manager (connector/keys/)
  • Registration flow (connector/register/)
  • Cloud-init generator (scripts/cloudinit/)

Phase 2 (Planned)

  • Real TPM interface implementation
  • k3s integration
  • PostgreSQL storage backend
  • Device revocation handling

Phase 3 (Future)

  • PQC algorithm support (ML-KEM/ML-DSA)
  • FPGA/SED integration
  • Production hardening

Security Notes

  • All cryptographic operations use ECDH P-256 and AES-256-GCM
  • KEK is derived per-device using ECDH
  • Session keys are short-lived and rotated
  • TPM Quote provides remote attestation
  • Incremental updates prevent rollback attacks