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

147 lines
4.3 KiB
Markdown

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
```bash
# 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
```bash
# 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
```bash
# 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)
- [x] Protocol message definitions (proto/)
- [x] Server API handlers (server/api/)
- [x] Server-side crypto (server/crypto/)
- [x] Device authentication (server/auth/)
- [x] Key management (server/keyring/)
- [x] Policy engine (server/policy/)
- [x] Audit logging (server/audit/)
- [x] EasyTier coordinator (server/easytier/)
- [x] Mock TPM (connector/tpm/)
- [x] Connector key manager (connector/keys/)
- [x] Registration flow (connector/register/)
- [x] 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