Merge pull request #122 from BitGo/WP-5534

docs(awm): added aws implementation docs

Author: pranavjain97

demo-kms-script/aws-interface.md

@@ -0,0 +1,233 @@
+# AWS HSM KMS Implementation Documentation
+
+This document provides a reference implementation for integrating the 4 KMS API's with AWS HSM, covering the complete request-response flow from API handlers to HSM operations.
+
+## ⚠️ Security Recommendation
+
+**For production KMS implementations, consider implementing the KMS-API in a C++ like language, or use typed arrays like Uint8Array for all sensitive data because JavaScript does not support secure memory management.**
+
+**Recommended Alternatives:**
+- **C++/Rust**: Languages with explicit memory management and secure allocation
+- **Node.js Typed Arrays**: Use `Uint8Array` for sensitive data with explicit zeroing
+- **Native Addons**: Implement cryptographic operations in native C++ modules
+- **Hardware Security**: Use HSM-backed secure memory when available
+
+## API Overview
+
+The KMS API provides secure key management through four main endpoints that integrate with AWS HSM:
+
+- `POST /key` - Store private keys using envelope encryption
+- `GET /key/{pub}` - Retrieve private keys using envelope decryption  
+- `POST /generateDataKey` - Generate AES keys in HSM for encryption
+- `POST /decryptDataKey` - Decrypt data keys using root keys
+
+## Architecture Flow
+All 4 API's implementation should follow roughly the same dataflow as outlined bellow:
+
+```
+API Request → Handler → KMS Provider → AWS HSM → KMS Provider → Database (if required) → Response
+```
+
+A KMS provider is the implementation of the code that is in charge of making the necessary calls to the HSM directly. You might have multiple providers in your solution, one for each 3rd party HSM that you wish to use, for example.
+
+### Handler-to-Provider Mapping
+
+| API Endpoint | Handler File | Provider Method | HSM Operations |
+|--------------|--------------|-----------------|----------------|
+| `POST /key` | `storePrivateKey.ts` | `postKey()` | Create AES key, export, encrypt |
+| `GET /key/{pub}` | `getPrivateKey.ts` | `getKey()` | Decrypt data key locally |
+| `POST /generateDataKey` | `generateDataKey.ts` | `generateDataKey()` | Create/export AES key |
+| `POST /decryptDataKey` | `decryptDataKey.ts` | `decryptDataKey()` | Local SJCL decryption |
+
+## Envelope Encryption Pattern (Recommended) 
+
+We recommend using a 3 level key encryption to store and protect the private keys of your advanced wallets. 
+The 3 levels consist of the root-level key from the KMS, 2nd level data keys generated by the root level key, and the 3rd level private keys used by your wallets directly.
+
+### Layer 1: KMS Keys (AWS HSM)
+- **Key spec**: `SYMMETRIC_DEFAULT`
+- **Algorithm**: AES-256-GCM, used by keys generated using the specification `SYMMETRIC_DEFAULT`
+- **Generation**: AWS HSM
+- **Storage**: AWS HSM
+- **Identification**: via its Amazon Resource Name (ARN), stored in local database
+- **Usage**: Generate lower level data keys. The ARN needs to be passed into AWS to generate a data key.
+
+### Layer 2: Data Keys (Generated by HSM, Used Locally)
+- **Algorithm**: AES-256 symmetric keys
+- **Generation**: AWS HSM (temporary keys)
+- **Export**: Encrypted data key and plaintext data key, both as Uint8Arrays
+- **Storage**: AWS KMS Database (plaintext data key), local memory (encrypted data key)
+
+### Layer 3: Private Keys (Application Data)
+- **Encryption**: AES-256-CCM using SJCL
+- **Key**: Data key plaintext (from Layer 2)
+- **Storage**: Database (encrypted only)
+
+## Implementation Details
+
+### Root Key Creation
+
+This following needs to be only run once. The KMS should be functional with just one root-level key.
+
+```typescript
+import * as awskms from '@aws-sdk/client-kms';
+
+async createRootKey(): Promise<{ rootKey: string }> {
+  const kms: awskms.KMSClient = new awskms.KMSClient({
+    region: *YOUR_AWS_REGION*,
+    credentials: *YOUR_AWS_CREDENTIALS*
+  });
+
+  const input: awskms.CreateKeyRequest = {
+    KeySpec: 'SYMMETRIC_DEFAULT',
+  }
+  const command = new awskms.CreateKeyCommand(input);
+  const res = await kms.send(command);
+
+  return {
+    rootKey: res.KeyMetadata.KeyId
+  }
+}
+```
+
+### Data Key Generation/Decryption
+Note that the root key returned from the above method is required for AWS to create data keys.
+
+```typescript
+import * as awskms from '@aws-sdk/client-kms';
+
+async generateDataKey(rootKey: string) {
+  const kms: awskms.KMSClient = new awskms.KMSClient({
+    region: *YOUR_AWS_REGION*,
+    credentials: *YOUR_AWS_CREDENTIALS*
+  });
+
+  const input: awskms.GenerateDataKeyRequest = {
+    KeyId: rootKey,
+    KeySpec: awskms.DataKeySpec.AES_256,
+  }
+  const command = new awskms.GenerateDataKeyCommand(input);
+  const res = await kms.send(command);
+
+  if (
+    res.CiphertextBlob === undefined || 
+    res.Plaintext === undefined
+  ) throw {};
+
+  return {
+    encryptedKey: res.CiphertextBlob.toString(),
+    plaintextKey: res.Plaintext.toString(),
+  };
+}
+
+async decryptDataKey(rootKey: string, encryptedKey: string) {
+  // parse comma-seperating-integer string (i.e. "1,127,34,23,...") back into Uint8Array
+  const encryptedBuffer = Uint8Array.from(encryptedKey.split(',').map((x: any) => parseInt(x, 10)));
+  const kms: awskms.KMSClient = new awskms.KMSClient({
+    region: *YOUR_AWS_REGION*,
+    credentials: *YOUR_AWS_CREDENTIALS*
+  });
+
+  const input: awskms.DecryptRequest = {
+    CiphertextBlob: encryptedBuffer,
+    KeyId: rootKey,
+  };
+
+  const command = new awskms.DecryptCommand(input);
+
+  const res = await this.kms.send(command);
+  if (res.Plaintext === undefined) throw {};
+
+  return {
+    plaintextKey: res.Plaintext.toString(),
+  };
+}
+```
+**Security Considerations:**
+- **Immediate Use**: Plaintext keys should be used immediately after generation
+- **Memory Overwriting**: Overwrite memory locations with random data before deallocation
+- **Garbage Collection**: Force GC to clear memory pages containing sensitive data
+- **Process Isolation**: Consider using separate processes for key operations
+- **Hardware Security**: Use HSM-backed secure memory when available
+
+
+### Wallet Priate key storage/retrival
+```typescript
+async postKey(rootKey: string, prv: string, pub: string) {
+  const dataKey = await this.generateDataKey(rootKey);
+  const encryptedPrv = encrypt(dataKey.plaintextKey, prv);
+
+  // **CRITICAL**: Wipe plaintext data key from memory immediately after use
+  // Production code should implement secure memory wiping here
+
+  // subroutine to store necessary, ENCRYPTED, info in database
+  database.store(encryptedPrv, dataKey.encryptedKey, pub); 
+
+  return {
+    encryptedPrv
+    rootKeyId: res.KeyId,
+    metadata: res.$metadata,
+  };
+}
+
+async getKey(rootKey: string, pub: string) {
+  const { encryptedPrv, encryptedKey } = database.select(pub);
+  const { plaintextKey } = this.decryptDataKey(rootKey, encryptedKey);
+
+  const prv = decrypt(plaintextKey, encryptePrv);
+
+  // **CRITICAL**: Wipe plaintext data key from memory immediately after use
+  // Production code should implement secure memory wiping here
+
+  return { prv };
+}
+```
+**Memory Security Notes:**
+- **Immediate Encryption**: Use plaintext data key immediately for encryption
+- **Secure Disposal**: Wipe plaintext key from memory after single use
+- **No Persistence**: Never store plaintext data keys in variables or logs
+- **Error Handling**: Ensure memory wiping occurs even if encryption fails
+
+
+## Database Schema
+
+### private_keys Table
+
+```sql
+CREATE TABLE private_keys (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  pub TEXT NOT NULL,                    -- Public key of the wallet
+  source TEXT NOT NULL,                 -- 'user' or 'backup'
+  encryptedPrv TEXT NOT NULL,           -- Private key encrypted with data key
+  encryptedDataKey TEXT NOT NULL,       -- Data key encrypted with root key
+  rootKey TEXT NOT NULL,                -- Root key identifier (i.e. ARN)
+  coin TEXT NOT NULL,                   -- Cryptocurrency type
+  type TEXT NOT NULL,                   -- Key type (e.g. 'tss')
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+## SJCL Encryption Details
+
+### Configuration
+- **Algorithm**: AES-256-CCM
+- **Iterations**: 10,000 (PBKDF2)
+- **Key Size**: 256 bits
+- **Tag Size**: 128 bits
+- **Mode**: CCM (Counter with CBC-MAC)
+
+### Example SJCL Output
+```json
+{
+  "iv": "a1b2c3d4e5f6...",
+  "v": 1,
+  "iter": 10000,
+  "ks": 256,
+  "ts": 128,
+  "mode": "ccm",
+  "adata": "",
+  "cipher": "aes",
+  "salt": "f6e5d4c3b2a1...",
+  "ct": "base64-encrypted-data"
+}
+```