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