🏗️ AWS KMS Architecture Diagrams
Visual guide to the KMS + Hedera integration architecture
Table of Contents
System Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ LafaekStreet Backend │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ API Endpoint │ │ Hedera Service │ │
│ │ /api/v1/reports │────────▶│ │ │
│ │ │ │ - Initialize │ │
│ │ POST new report │ │ - Create TX │ │
│ └──────────────────┘ │ - Submit to HCS │ │
│ └────────┬─────────┘ │
│ │ │
│ │ calls │
│ ▼ │
│ ┌──────────────────┐ │
│ │ KMS Service │ │
│ │ │ │
│ │ 1. keccak256() │ │
│ │ 2. sign() │ │
│ │ 3. parse_der() │ │
│ └────────┬─────────┘ │
│ │ │
└─────────────────────────────────────────┼───────────────────────────────┘
│
│ AWS SDK (boto3)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AWS Cloud │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ AWS KMS │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────┐ │ │
│ │ │ KMS Key: ECC_SECG_P256K1 (SIGN_VERIFY) │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────────────────────────────────────┐ │ │ │
│ │ │ │ Private Key (NEVER leaves HSM) │ │ │ │
│ │ │ │ - Generated in HSM │ │ │ │
│ │ │ │ - Cannot be exported │ │ │ │
│ │ │ │ - Used only for signing │ │ │ │
│ │ │ └──────────────────────────────────────────────┘ │ │ │
│ │ └────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Operations: Sign(digest) → signature | GetPublicKey() → key │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ AWS CloudTrail: Logs all KMS operations for audit │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
│ Signed Transaction
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Hedera Network │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Hedera Consensus Service (HCS) │ │
│ │ Topic: 0.0.7855971 (Reports) │ │
│ │ │ │
│ │ 1. Verify signature with public key │ │
│ │ 2. Reach consensus across nodes │ │
│ │ 3. Record on blockchain (immutable) │ │
│ │ 4. Return transaction ID │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ HashScan Explorer: https://hashscan.io/testnet/transaction/{tx_id} │
└─────────────────────────────────────────────────────────────────────────┘Transaction Signing Flow
┌─────────────────────────────────────────────────────────────────────────┐
│ Step-by-Step Signing Process │
└─────────────────────────────────────────────────────────────────────────┘
1. CREATE REPORT
┌──────────────────────────────────────────────────────────┐
│ User submits report via API │
│ { "issue_type": "pothole", "severity": "high", ... } │
└──────────────────────────────────────────────────────────┘
↓
2. BUILD PAYLOAD
┌──────────────────────────────────────────────────────────┐
│ Hedera Service creates blockchain payload │
│ { "report_id": "LS-260220-0001", "timestamp": "...", ...}│
└──────────────────────────────────────────────────────────┘
↓
3. CREATE TRANSACTION
┌──────────────────────────────────────────────────────────┐
│ TopicMessageSubmitTransaction │
│ - Topic: 0.0.7855971 │
│ - Message: JSON payload │
│ - Freeze with client │
└──────────────────────────────────────────────────────────┘
↓
4. HASH TRANSACTION
┌──────────────────────────────────────────────────────────┐
│ KMS Service: keccak256(transaction_bytes) │
│ │
│ Input: [0x12, 0x34, 0x56, ...] (transaction bytes) │
│ Output: [0xa3, 0xf5, 0xe8, ...] (32-byte hash) │
└──────────────────────────────────────────────────────────┘
↓
5. SIGN WITH KMS
┌──────────────────────────────────────────────────────────┐
│ AWS KMS: Sign(hash, key_id) │
│ │
│ Request: │
│ KeyId: f903385b-86db-478f-b7d0-84e45b657c9c │
│ Message: a3f5e8d2... (digest) │
│ MessageType: DIGEST │
│ SigningAlgorithm: ECDSA_SHA_256 │
│ │
│ Response: DER-encoded signature (70-72 bytes) │
│ │
│ 🔐 Private key NEVER leaves AWS HSM │
└──────────────────────────────────────────────────────────┘
↓
6. PARSE SIGNATURE
┌──────────────────────────────────────────────────────────┐
│ KMS Service: parse_der_signature() │
│ │
│ Input: DER-encoded (70-72 bytes) │
│ Parse: Extract r and s integers (32 bytes each) │
│ Output: Raw signature r || s (64 bytes) │
└──────────────────────────────────────────────────────────┘
↓
7. SUBMIT TRANSACTION
┌──────────────────────────────────────────────────────────┐
│ Hedera Network: Execute transaction │
│ │
│ 1. Verify signature with public key │
│ 2. Reach consensus across nodes │
│ 3. Record on blockchain │
│ │
│ Receipt: │
│ Transaction ID: 0.0.6255873@1708473892.123456789 │
│ Status: SUCCESS │
│ │
│ ✅ Transaction recorded on blockchain │
└──────────────────────────────────────────────────────────┘
↓
8. RETURN RECEIPT
┌──────────────────────────────────────────────────────────┐
│ API Response to user │
│ { │
│ "report_id": "LS-260220-0001", │
│ "blockchain": { │
│ "transaction_id": "0.0.6255873@...", │
│ "explorer_url": "https://hashscan.io/..." │
│ } │
│ } │
│ 🎉 Report successfully submitted! │
└──────────────────────────────────────────────────────────┘Data Flow Diagram
┌──────────┐
│ Mobile │
│ App │
└────┬─────┘
│ POST /api/v1/reports
│ {issue_type, severity, location, ...}
▼
┌─────────────────────────────────────────────────────────────┐
│ Backend API │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Validate │───▶│ Store in │───▶│ Submit to │ │
│ │ Request │ │ PostgreSQL │ │ Hedera │ │
│ └──────────────┘ └──────────────┘ └──────┬───────┘ │
│ │ │
│ ┌───────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Hedera Service │ │
│ │ 1. Create payload │ │
│ │ 2. Hash user_id, images │ │
│ │ 3. Build transaction │ │
│ │ 4. Call KMS for signing │ │
│ │ 5. Submit to HCS │ │
│ └──────────────┬───────────────────────────────┘ │
│ │ │
│ │ sign_transaction(tx_bytes) │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ KMS Service │ │
│ │ 1. digest = keccak256(tx_bytes) │ │
│ │ 2. der_sig = kms.sign(digest) │ │
│ │ 3. raw_sig = parse_der(der_sig) │ │
│ │ 4. return raw_sig (64 bytes) │ │
│ └──────────────┬───────────────────────────────┘ │
│ │ │
└─────────────────┼───────────────────────────────────────────┘
│
│ boto3.kms.sign()
▼
┌─────────────────────────────────────────────────────────────┐
│ AWS KMS │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ HSM (Hardware Security Module) │ │
│ │ Private Key: [NEVER EXPORTED] │ │
│ │ ECDSA Sign(digest) using secp256k1 │ │
│ │ Output: DER Signature │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────┬───────────────────────────────────────────┘
│
│ Signed Transaction
▼
┌─────────────────────────────────────────────────────────────┐
│ Hedera Network │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Consensus Nodes: Verify → Consensus → Record │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Mirror Nodes: History → REST API → HashScan │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘Security Layers
┌─────────────────────────────────────────────────────────────────────────┐
│ 5 Security Layers │
└─────────────────────────────────────────────────────────────────────────┘
Layer 1: AWS IAM
┌──────────────────────────────────────────────────────────────┐
│ IAM User: hedera-kms-user │
│ Permissions: │
│ ✓ kms:Sign │
│ ✓ kms:GetPublicKey │
│ ✓ kms:DescribeKey │
│ ✗ kms:ScheduleKeyDeletion (denied) │
└──────────────────────────────────────────────────────────────┘
Layer 2: KMS Key Policy
┌──────────────────────────────────────────────────────────────┐
│ Key: ECC_SECG_P256K1 (Hedera-compatible) │
│ - Only specific IAM users can use │
│ - CloudTrail logging enabled │
│ - Key rotation enabled │
└──────────────────────────────────────────────────────────────┘
Layer 3: HSM (Hardware Security Module)
┌──────────────────────────────────────────────────────────────┐
│ ✓ Private key generated inside HSM │
│ ✓ Private key NEVER leaves HSM │
│ ✓ Cannot be exported │
│ ✓ FIPS 140-2 Level 2 validated │
│ ✓ Tamper-resistant hardware │
└──────────────────────────────────────────────────────────────┘
Layer 4: Application Security
┌──────────────────────────────────────────────────────────────┐
│ ✓ Environment variables for secrets │
│ ✓ No private keys in code │
│ ✓ TLS for all AWS communication │
│ ✓ Input validation & error handling │
└──────────────────────────────────────────────────────────────┘
Layer 5: Audit & Monitoring
┌──────────────────────────────────────────────────────────────┐
│ AWS CloudTrail logs every KMS operation: │
│ - Who (IAM user) | What (Sign, GetPublicKey) │
│ - When (timestamp) | Where (source IP) │
│ - Result (success/failure) │
└──────────────────────────────────────────────────────────────┘Related Documentation
- Overview - Documentation index
- Quick Start - 5-minute setup guide
- Technical Details - Complete implementation
🔐 Enterprise-Grade Security for Blockchain Transactions