⚡ Quick Start: AWS KMS Integration

Get KMS signing working in 5 minutes

---

🛡️ Why AWS KMS?

Without KMS	With AWS KMS
❌ Private key in plaintext file	✅ Key in tamper-proof hardware (HSM)
❌ Key can be stolen/copied	✅ Key cannot be exported
❌ No audit trail	✅ Every signing logged in CloudTrail
❌ Manual security	✅ FIPS 140-2 Level 2 certified

---

Prerequisites

• ✅ AWS account with KMS access
• ✅ KMS key created (ECC_SECG_P256K1, SIGN_VERIFY)
• ✅ IAM user with kms:Sign, kms:GetPublicKey, kms:DescribeKey permissions
• ✅ Hedera Testnet account

---

Step 1: Install Dependencies (1 min)

cd lafaekstreet_backend
./install_kms_dependencies.sh

Or manually:

pip install pycryptodome==3.19.1 ecdsa==0.18.0 asn1crypto==1.5.1

---

Step 2: Configure Environment (30 sec)

Add AWS KMS credentials to your .env file:

# AWS KMS Configuration (for secure transaction signing)
AWS_KMS_KEY_ID="arn:aws:kms:us-east-1:YOUR_ACCOUNT:key/YOUR_KEY_ID"
AWS_ACCESS_KEY_ID="AKIAXXXXXXXXXXXXXXXXX"
AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AWS_REGION="us-east-1"

Reference: This follows the official Hedera AWS KMS Workshop pattern. For complete .env setup including Hedera credentials, see the Backend README.

---

Step 3: Test Integration (1 min)

python test_kms_integration.py

Expected output:

✅ ALL KMS TESTS PASSED

---

Step 4: Start Backend (30 sec)

python run.py

Look for this startup message:

================================================================================
🔐 AWS KMS INTEGRATION ENABLED
================================================================================
✅ KMS configuration verified successfully

---

Step 5: Verify with Test Report (2 min)

# Create a test report
curl -X POST http://localhost:8000/api/v1/reports \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issue_type": "pothole",
    "severity": "high",
    "description": "Test KMS signing",
    "latitude": -8.5569,
    "longitude": 125.5603
  }'

Check logs for KMS signing:

🔐 SIGNING HEDERA TRANSACTION WITH AWS KMS
✅ KMS: Successfully signed transaction
🔐 Signed with AWS KMS
🔗 View on HashScan: https://hashscan.io/testnet/transaction/...

---

✅ Success Checklist

• [ ] Dependencies installed
• [ ] .env configured with KMS credentials
• [ ] python test_kms_integration.py passes
• [ ] Backend starts with "KMS INTEGRATION ENABLED"
• [ ] Report creation shows KMS signing in logs
• [ ] Transaction visible on HashScan

---

🔧 Quick Fixes

Error	Fix
Module not found: Crypto	pip install pycryptodome==3.19.1
AWS_KMS_KEY_ID not configured	Add KMS ARN to .env
AccessDeniedException	Add IAM permissions: kms:Sign, kms:GetPublicKey, kms:DescribeKey
Invalid key spec	KMS key must be ECC_SECG_P256K1 with SIGN_VERIFY usage

---

📚 Next Steps

• Need more details? → Technical Documentation
• Want to see the architecture? → Architecture Diagrams
• Back to overview → README

---

🎉 Done!

Your LafaekStreet backend now uses AWS KMS for secure Hedera transaction signing.

Every report is signed using hardware-backed keys with full audit trail in AWS CloudTrail.