@bsv/sdk/docs/tutorials/aes-encryption.md

BSV Blockchain Software Development Kit

# AES Symmetric Encryption

**Duration**: 60 minutes  
**Prerequisites**: Basic TypeScript knowledge, [First Transaction](./first-transaction.md) tutorial completed

## Learning Goals

- Understand AES-GCM symmetric encryption principles
- Use the `SymmetricKey` class for encryption and decryption
- Implement secure key generation and management
- Apply AES encryption in practical Bitcoin applications
- Combine AES with ECDH for secure communication
- Handle different data formats and encoding

## Introduction to AES Encryption

Advanced Encryption Standard (AES) is a symmetric encryption algorithm where the same key is used for both encryption and decryption. The BSV TypeScript SDK provides the `SymmetricKey` class that implements AES-GCM (Galois/Counter Mode), which provides both confidentiality and authenticity.

AES-GCM offers several advantages:

- **Confidentiality**: Data is encrypted and unreadable without the key
- **Authenticity**: Built-in authentication prevents tampering
- **Performance**: Fast encryption/decryption operations
- **Security**: Resistant to various cryptographic attacks

## Setting Up Your Environment

First, let's import the necessary classes from the SDK:

```typescript
import { SymmetricKey, Utils, Random } from '@bsv/sdk'

// Helper function to convert hex string to byte array
function hexToBytes(hex: string): number[] {
  const bytes = []
  for (let i = 0; i < hex.length; i += 2) {
    bytes.push(parseInt(hex.substr(i, 2), 16))
  }
  return bytes
}

// Helper function to convert byte array to hex string
function bytesToHex(bytes: number[]): string {
  const hex = []
  for (const byte of bytes) {
    hex.push(byte.toString(16).padStart(2, '0'))
  }
  return hex.join('')
}
```

## Basic AES Encryption

### Generating Encryption Keys

The `SymmetricKey` class provides methods to create secure encryption keys:

```typescript
// Generate a random 256-bit AES key
const symmetricKey = SymmetricKey.fromRandom()
console.log('Generated key:', symmetricKey.toHex())

// Create a key from existing data (32 bytes)
const keyData = Random(32)
const customKey = new SymmetricKey(keyData)
console.log('Custom key:', customKey.toHex())

// Create a key from hex string
const hexKey = 'a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456'
const keyFromHex = new SymmetricKey(hexToBytes(hexKey))
```

### Encrypting Data

The `encrypt` method supports both string and binary data:

```typescript
const symmetricKey = SymmetricKey.fromRandom()
const message = 'Hello, this is a secret message!'

// Encrypt a string (UTF-8 encoding)
const encryptedMessage = symmetricKey.encrypt(message) as number[]
console.log('Encrypted message length:', encryptedMessage.length)

// Encrypt binary data
const binaryData = Utils.toArray('Binary data example', 'utf8')
const encryptedBinary = symmetricKey.encrypt(binaryData) as number[]

// Encrypt with hex output (using manual conversion for clarity)
const encryptedBytes = symmetricKey.encrypt(message) as number[]
const hexEncrypted = bytesToHex(encryptedBytes)
console.log('Hex encrypted:', hexEncrypted)

// Alternative: SDK's built-in hex handling (for hex input data)
// Note: The 'hex' parameter treats the input as hex, not the output format
const messageAsHex = Buffer.from(message).toString('hex') // Convert message to hex first
const sdkHexEncrypted = symmetricKey.encrypt(messageAsHex, 'hex') as string
console.log('SDK hex encrypted:', sdkHexEncrypted)
```

### Decrypting Data

The `decrypt` method reverses the encryption process:

```typescript
// Decrypt to string (UTF-8)
const decryptedMessage = symmetricKey.decrypt(encryptedMessage, 'utf8') as string
console.log('Decrypted message:', decryptedMessage)

// Decrypt to binary array
const decryptedBinary = symmetricKey.decrypt(encryptedBinary) as number[]
console.log('Decrypted binary:', Utils.toUTF8(decryptedBinary))

// Decrypt hex-encoded data (manual conversion method)
const hexBytes = hexToBytes(hexEncrypted)
const decryptedFromHex = symmetricKey.decrypt(hexBytes, 'utf8') as string
console.log('Decrypted from hex:', decryptedFromHex)

// Alternative: SDK hex handling method
const sdkHexBytes = hexToBytes(sdkHexEncrypted)
const sdkDecryptedHex = symmetricKey.decrypt(sdkHexBytes, 'hex') as string
const sdkDecryptedMessage = Buffer.from(sdkDecryptedHex, 'hex').toString('utf8')
console.log('SDK decrypted from hex:', sdkDecryptedMessage)
```

### Understanding the Hex Parameter

The `enc` parameter in the SDK's `encrypt()` and `decrypt()` methods can be confusing. Here's how it actually works:

**In `encrypt(data, enc)`:**

- `enc` specifies how to **interpret the input data**
- `enc: 'hex'` means the input data is a hex string that should be converted to bytes
- The output format is determined by the `enc` parameter (hex string if `enc: 'hex'`, byte array otherwise)

**In `decrypt(data, enc)`:**

- `enc` specifies the **output format**
- `enc: 'hex'` returns the decrypted data as a hex string
- `enc: 'utf8'` returns the decrypted data as a UTF-8 string

```typescript
// Example: Encrypting hex data with SDK's built-in hex handling
const message = 'Hello, World!'
const messageAsHex = Buffer.from(message).toString('hex') // '48656c6c6f2c20576f726c6421'

// Encrypt hex input data
const encrypted = key.encrypt(messageAsHex, 'hex') as string

// Decrypt and get result as hex
const decryptedHex = key.decrypt(hexToBytes(encrypted), 'hex') as string
console.log('Decrypted as hex:', decryptedHex) // '48656c6c6f2c20576f726c6421'

// Convert hex result back to UTF-8
const finalMessage = Buffer.from(decryptedHex, 'hex').toString('utf8')
console.log('Final message:', finalMessage) // 'Hello, World!'
```

## Complete Encryption Example

Here's a comprehensive example demonstrating the full encryption workflow:

```typescript
import { SymmetricKey, Utils } from '@bsv/sdk'

function demonstrateAESEncryption() {
  console.log('=== AES Encryption Demonstration ===')
  
  // 1. Generate a random encryption key
  const symmetricKey = SymmetricKey.fromRandom()
  console.log('Generated key:', symmetricKey.toHex().substring(0, 16) + '...')
  
  // 2. Prepare the message to encrypt
  const originalMessage = 'This is a confidential message that needs protection!'
  console.log('Original message:', originalMessage)
  
  // 3. Encrypt the message
  const encryptedData = symmetricKey.encrypt(originalMessage) as number[]
  console.log('Encrypted data length:', encryptedData.length, 'bytes')
  console.log('Encrypted (first 32 bytes):', encryptedData.slice(0, 32))
  
  // 4. Decrypt the message
  const decryptedMessage = symmetricKey.decrypt(encryptedData, 'utf8') as string
  
  // 5. Verify integrity
  const isValid = originalMessage === decryptedMessage
  console.log('Decryption successful:', isValid)
  
  return {
    key: symmetricKey,
    original: originalMessage,
    encrypted: encryptedData,
    decrypted: decryptedMessage,
    valid: isValid
  }
}

// Run the demonstration
const result = demonstrateAESEncryption()
```

## Working with Different Data Types

### Encrypting JSON Data

```typescript
function encryptJSON(data: any, key: SymmetricKey): number[] {
  const jsonString = JSON.stringify(data)
  return key.encrypt(jsonString) as number[]
}

function decryptJSON(encryptedData: number[], key: SymmetricKey): any {
  const jsonString = key.decrypt(encryptedData, 'utf8') as string
  return JSON.parse(jsonString)
}

// Example usage
const symmetricKey = SymmetricKey.fromRandom()
const userData = {
  name: 'Alice',
  email: 'alice@example.com',
  balance: 1000,
  transactions: ['tx1', 'tx2', 'tx3']
}

const encryptedJSON = encryptJSON(userData, symmetricKey)
const decryptedData = decryptJSON(encryptedJSON, symmetricKey)
console.log('Original data:', userData)
console.log('Decrypted data:', decryptedData)
```

### Encrypting Files and Large Data

```typescript
function encryptLargeData(data: string, key: SymmetricKey): {
  encrypted: number[],
  size: number,
  checksum: string
} {
  // Convert to binary
  const binaryData = Utils.toArray(data, 'utf8')
  
  // Encrypt the data
  const encrypted = key.encrypt(binaryData) as number[]
  
  // Calculate checksum of original data for verification
  const checksum = Utils.toBase64(binaryData.slice(0, 32))
  
  return {
    encrypted,
    size: binaryData.length,
    checksum
  }
}

function decryptLargeData(encryptedData: {
  encrypted: number[],
  size: number,
  checksum: string
}, key: SymmetricKey): string {
  // Decrypt the data
  const decrypted = key.decrypt(encryptedData.encrypted) as number[]
  
  // Verify size
  if (decrypted.length !== encryptedData.size) {
    throw new Error('Decrypted data size mismatch')
  }
  
  // Verify checksum
  const checksum = Utils.toBase64(decrypted.slice(0, 32))
  if (checksum !== encryptedData.checksum) {
    console.warn('Checksum mismatch - data may be corrupted')
  }
  
  return Utils.toUTF8(decrypted)
}
```

## Key Derivation and Management

### Deriving Keys from Passwords

```typescript
import { Hash } from '@bsv/sdk'

function deriveKeyFromPassword(password: string, salt?: number[]): SymmetricKey {
  // Use provided salt or generate random one
  const keySalt = salt || Random(32)
  
  // Create key material by hashing password + salt
  const passwordBytes = Utils.toArray(password, 'utf8')
  const keyMaterial = [...passwordBytes, ...keySalt]
  
  // Hash to create 256-bit key
  const keyHash = Hash.sha256(keyMaterial)
  
  return new SymmetricKey(keyHash)
}

// Example usage
const password = 'MySecurePassword123!'
const salt = Random(32)
const derivedKey = deriveKeyFromPassword(password, salt)

// Store salt separately - needed for key recreation
console.log('Derived key:', derivedKey.toHex())
console.log('Salt (store this):', Utils.toBase64(salt))

// Recreate the same key later
const recreatedKey = deriveKeyFromPassword(password, salt)
console.log('Keys match:', derivedKey.toHex() === recreatedKey.toHex())
```

### Key Rotation and Versioning

```typescript
class KeyManager {
  private keys: Map<number, SymmetricKey> = new Map()
  private currentVersion: number = 1
  
  generateNewKey(): number {
    const newKey = SymmetricKey.fromRandom()
    this.keys.set(this.currentVersion, newKey)
    return this.currentVersion++
  }
  
  encrypt(data: string, version?: number): { 
    encrypted: number[], 
    version: number 
  } {
    const keyVersion = version || this.currentVersion - 1
    const key = this.keys.get(keyVersion)
    
    if (!key) {
      throw new Error(`Key version ${keyVersion} not found`)
    }
    
    return {
      encrypted: key.encrypt(data) as number[],
      version: keyVersion
    }
  }
  
  decrypt(encryptedData: {
    encrypted: number[], 
    version: number 
  }): string {
    const key = this.keys.get(encryptedData.version)
    
    if (!key) {
      throw new Error(`Key version ${encryptedData.version} not found`)
    }
    
    return key.decrypt(encryptedData.encrypted, 'utf8') as string
  }
}

// Example usage
const keyManager = new KeyManager()
const v1 = keyManager.generateNewKey()
const v2 = keyManager.generateNewKey()

const message = 'Data encrypted with version 1'
const encrypted = keyManager.encrypt(message, v1)
const decrypted = keyManager.decrypt(encrypted)
console.log('Decrypted:', decrypted)
```

## Combining AES with ECDH

For secure communication between parties, combine AES encryption with ECDH key exchange:

```typescript
import { PrivateKey, PublicKey } from '@bsv/sdk'

function createSecureChannel(
  senderPrivateKey: PrivateKey,
  recipientPublicKey: PublicKey
): SymmetricKey {
  // Derive shared secret using ECDH
  const sharedSecret = senderPrivateKey.deriveSharedSecret(recipientPublicKey)
  
  // Use shared secret as AES key material
  const keyMaterial = sharedSecret.encode(true).slice(1) // Remove prefix byte
  
  return new SymmetricKey(keyMaterial)
}

function secureMessageExchange() {
  // Generate key pairs for Alice and Bob
  const alicePrivate = PrivateKey.fromRandom()
  const alicePublic = alicePrivate.toPublicKey()
  
  const bobPrivate = PrivateKey.fromRandom()
  const bobPublic = bobPrivate.toPublicKey()
  
  // Alice creates encryption key using Bob's public key
  const aliceEncryptionKey = createSecureChannel(alicePrivate, bobPublic)
  
  // Bob creates the same encryption key using Alice's public key
  const bobDecryptionKey = createSecureChannel(bobPrivate, alicePublic)
  
  // Verify both parties have the same key
  console.log('Keys match:', 
    aliceEncryptionKey.toHex() === bobDecryptionKey.toHex())
  
  // Alice encrypts a message
  const message = 'Hello Bob, this is a secure message from Alice!'
  const encrypted = aliceEncryptionKey.encrypt(message) as number[]
  
  // Bob decrypts the message
  const decrypted = bobDecryptionKey.decrypt(encrypted, 'utf8') as string
  
  console.log('Original message:', message)
  console.log('Decrypted message:', decrypted)
  console.log('Secure communication successful:', message === decrypted)
  
  return { aliceEncryptionKey, bobDecryptionKey, message, decrypted }
}

// Run secure message exchange
secureMessageExchange()
```

## Error Handling and Security

### Robust Encryption with Error Handling

```typescript
class SecureAESManager {
  private key: SymmetricKey
  
  constructor(key?: SymmetricKey) {
    this.key = key || SymmetricKey.fromRandom()
  }
  
  safeEncrypt(data: string): { 
    success: boolean, 
    encrypted?: number[], 
    error?: string 
  } {
    try {
      if (!data || data.length === 0) {
        return { success: false, error: 'Data cannot be empty' }
      }
      
      const encrypted = this.key.encrypt(data) as number[]
      
      if (!encrypted || encrypted.length === 0) {
        return { success: false, error: 'Encryption failed' }
      }
      
      return { success: true, encrypted }
    } catch (error) {
      return { 
        success: false, 
        error: `Encryption error: ${error.message}` 
      }
    }
  }
  
  safeDecrypt(encryptedData: number[]): { 
    success: boolean, 
    decrypted?: string, 
    error?: string 
  } {
    try {
      if (!encryptedData || encryptedData.length === 0) {
        return { success: false, error: 'Encrypted data cannot be empty' }
      }
      
      const decrypted = this.key.decrypt(encryptedData, 'utf8') as string
      
      return { success: true, decrypted }
    } catch (error) {
      return { 
        success: false, 
        error: `Decryption failed: ${error.message}` 
      }
    }
  }
  
  rotateKey(): void {
    this.key = SymmetricKey.fromRandom()
  }
  
  getKeyFingerprint(): string {
    // Create a fingerprint of the key for identification
    const keyBytes = this.key.toArray()
    const hash = Hash.sha256(keyBytes)
    return Utils.toBase64(hash).substring(0, 16)
  }
}

// Example usage with error handling
const aesManager = new SecureAESManager()
console.log('Key fingerprint:', aesManager.getKeyFingerprint())

const testData = 'Sensitive information that needs protection'
const encryptResult = aesManager.safeEncrypt(testData)

if (encryptResult.success) {
  console.log('Encryption successful')
  
  const decryptResult = aesManager.safeDecrypt(encryptResult.encrypted!)
  
  if (decryptResult.success) {
    console.log('Decryption successful:', decryptResult.decrypted)
  } else {
    console.error('Decryption failed:', decryptResult.error)
  }
} else {
  console.error('Encryption failed:', encryptResult.error)
}
```

## Practical Applications

### Encrypting Transaction Metadata

```typescript
import { Transaction, PrivateKey } from '@bsv/sdk'

function encryptTransactionMetadata(
  transaction: Transaction,
  metadata: any,
  encryptionKey: SymmetricKey
): number[] {
  const metadataWithTx = {
    txid: Buffer.from(transaction.id()).toString('hex'),
    timestamp: Date.now(),
    metadata: metadata
  }
  
  const jsonString = JSON.stringify(metadataWithTx)
  return encryptionKey.encrypt(jsonString) as number[]
}

function decryptTransactionMetadata(
  encryptedMetadata: number[],
  encryptionKey: SymmetricKey
): any {
  const jsonString = encryptionKey.decrypt(encryptedMetadata, 'utf8') as string
  return JSON.parse(jsonString)
}

// Example: Encrypt private notes about a transaction
const privateKey = PrivateKey.fromRandom()
const encryptionKey = SymmetricKey.fromRandom()

// Create a simple transaction (placeholder)
const transaction = new Transaction()
// ... transaction setup ...

const privateMetadata = {
  purpose: 'Payment to supplier',
  invoiceNumber: 'INV-2024-001',
  notes: 'Quarterly payment for services',
  category: 'business-expense'
}

const encrypted = encryptTransactionMetadata(transaction, privateMetadata, encryptionKey)
const decrypted = decryptTransactionMetadata(encrypted, encryptionKey)

console.log('Original metadata:', privateMetadata)
console.log('Decrypted metadata:', decrypted)
```

### Secure Configuration Storage

```typescript
class SecureConfig {
  private encryptionKey: SymmetricKey
  private config: Map<string, number[]> = new Map()
  
  constructor(password: string) {
    // Derive encryption key from password
    const salt = Random(32)
    const passwordHash = Hash.sha256([
      ...Utils.toArray(password, 'utf8'),
      ...salt
    ])
    this.encryptionKey = new SymmetricKey(passwordHash)
  }
  
  set(key: string, value: any): void {
    const jsonValue = JSON.stringify(value)
    const encrypted = this.encryptionKey.encrypt(jsonValue) as number[]
    this.config.set(key, encrypted)
  }
  
  get(key: string): any {
    const encrypted = this.config.get(key)
    if (!encrypted) {
      return undefined
    }
    
    try {
      const decrypted = this.encryptionKey.decrypt(encrypted, 'utf8') as string
      return JSON.parse(decrypted)
    } catch (error) {
      console.error('Failed to decrypt config value:', error)
      return undefined
    }
  }
  
  has(key: string): boolean {
    return this.config.has(key)
  }
  
  delete(key: string): boolean {
    return this.config.delete(key)
  }
  
  export(): string {
    const exportData = {}
    for (const [key, encrypted] of this.config.entries()) {
      exportData[key] = Utils.toBase64(encrypted)
    }
    return JSON.stringify(exportData)
  }
  
  import(data: string): void {
    const importData = JSON.parse(data)
    for (const [key, base64Value] of Object.entries(importData)) {
      const encrypted = Utils.fromBase64(base64Value as string)
      this.config.set(key, encrypted)
    }
  }
}

// Example usage
const secureConfig = new SecureConfig('MySecurePassword123!')

// Store sensitive configuration
secureConfig.set('apiKey', 'sk-1234567890abcdef')
secureConfig.set('databaseUrl', 'postgresql://user:pass@host:5432/db')
secureConfig.set('walletSeed', 'abandon abandon abandon...')

// Retrieve configuration
console.log('API Key:', secureConfig.get('apiKey'))
console.log('Has database URL:', secureConfig.has('databaseUrl'))

// Export encrypted configuration
const exportedConfig = secureConfig.export()
console.log('Exported config length:', exportedConfig.length)
```

## Performance Considerations

### Benchmarking AES Operations

```typescript
function benchmarkAESPerformance() {
  const key = SymmetricKey.fromRandom()
  const testSizes = [100, 1000, 10000, 100000] // bytes
  
  console.log('=== AES Performance Benchmark ===')
  
  for (const size of testSizes) {
    const testData = 'x'.repeat(size)
    
    // Benchmark encryption
    const encryptStart = performance.now()
    const encrypted = key.encrypt(testData) as number[]
    const encryptTime = performance.now() - encryptStart
    
    // Benchmark decryption
    const decryptStart = performance.now()
    const decrypted = key.decrypt(encrypted, 'utf8') as string
    const decryptTime = performance.now() - decryptStart
    
    console.log(`Size: ${size} bytes`)
    console.log(`  Encrypt: ${encryptTime.toFixed(2)}ms`)
    console.log(`  Decrypt: ${decryptTime.toFixed(2)}ms`)
    console.log(`  Total: ${(encryptTime + decryptTime).toFixed(2)}ms`)
    console.log(`  Throughput: ${(size / (encryptTime + decryptTime) * 1000).toFixed(0)} bytes/sec`)
    console.log()
  }
}

// Run benchmark
benchmarkAESPerformance()
```

## Security Best Practices

### Key Security Guidelines

```typescript
class SecureKeyPractices {
  // Good: Generate random keys
  static generateSecureKey(): SymmetricKey {
    return SymmetricKey.fromRandom()
  }
  
  // Good: Derive keys from strong passwords
  static deriveFromPassword(password: string, salt: number[]): SymmetricKey {
    if (password.length < 12) {
      throw new Error('Password must be at least 12 characters')
    }
    
    const keyMaterial = Hash.sha256([
      ...Utils.toArray(password, 'utf8'),
      ...salt
    ])
    return new SymmetricKey(keyMaterial)
  }
  
  // Good: Secure key comparison
  static keysEqual(key1: SymmetricKey, key2: SymmetricKey): boolean {
    const bytes1 = key1.toArray()
    const bytes2 = key2.toArray()
    
    if (bytes1.length !== bytes2.length) {
      return false
    }
    
    // Constant-time comparison to prevent timing attacks
    let result = 0
    for (let i = 0; i < bytes1.length; i++) {
      result |= bytes1[i] ^ bytes2[i]
    }
    return result === 0
  }
  
  // Good: Secure key destruction
  static destroyKey(key: SymmetricKey): void {
    // Overwrite key material (note: this is conceptual in JavaScript)
    const keyArray = key.toArray()
    for (let i = 0; i < keyArray.length; i++) {
      keyArray[i] = 0
    }
  }
}

// Security validation example
function validateSecurityPractices() {
  console.log('=== Security Practices Validation ===')
  
  // Generate secure keys
  const key1 = SecureKeyPractices.generateSecureKey()
  const key2 = SecureKeyPractices.generateSecureKey()
  
  console.log('Keys are different:', !SecureKeyPractices.keysEqual(key1, key2))
  
  // Test password-based key derivation
  const password = 'MyVerySecurePassword123!'
  const salt = Random(32)
  const derivedKey1 = SecureKeyPractices.deriveFromPassword(password, salt)
  const derivedKey2 = SecureKeyPractices.deriveFromPassword(password, salt)
  
  console.log('Derived keys are identical:', 
    SecureKeyPractices.keysEqual(derivedKey1, derivedKey2))
  
  // Clean up
  SecureKeyPractices.destroyKey(key1)
  SecureKeyPractices.destroyKey(key2)
  
  console.log('Security validation complete')
}

validateSecurityPractices()
```

## Troubleshooting Common Issues

### Common Problems and Solutions

```typescript
function troubleshootAESIssues() {
  console.log('=== AES Troubleshooting Guide ===')
  
  // Issue 1: Decryption fails with "Decryption failed!" error
  try {
    const key = SymmetricKey.fromRandom()
    const message = 'Test message'
    const encrypted = key.encrypt(message) as number[]
    
    // Corrupt the encrypted data to simulate tampering
    encrypted[10] = encrypted[10] ^ 1
    
    const decrypted = key.decrypt(encrypted, 'utf8')
  } catch (error) {
    console.log('Detected tampered data:', error.message)
    console.log('  Solution: Verify data integrity, check for transmission errors')
  }
  
  // Issue 2: Wrong key used for decryption
  try {
    const key1 = SymmetricKey.fromRandom()
    const key2 = SymmetricKey.fromRandom()
    const message = 'Test message'
    
    const encrypted = key1.encrypt(message) as number[]
    const decrypted = key2.decrypt(encrypted, 'utf8') // Wrong key!
  } catch (error) {
    console.log('Detected wrong key usage:', error.message)
    console.log('  Solution: Ensure same key is used for encryption and decryption')
  }
  
  // Issue 3: Empty or invalid data
  try {
    const key = SymmetricKey.fromRandom()
    // Empty strings are actually supported and work fine
    const encrypted = key.encrypt('') as number[]
    const decrypted = key.decrypt(encrypted, 'utf8') as string
    console.log('Empty string encryption works:', decrypted === '')
    console.log('  Note: Empty strings are supported by the SDK')
  } catch (error) {
    console.log('Unexpected error with empty data:', error.message)
  }
  
  // Issue 4: Hex string handling
  try {
    const hexKey = 'a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456'
    // This will fail - constructor expects byte array, not hex string
    // const wrongKey = new SymmetricKey(hexKey)
    
    // Correct approach - convert hex to bytes first
    const correctKey = new SymmetricKey(hexToBytes(hexKey))
    console.log('Hex key creation works with helper function')
    console.log('  Solution: Use hexToBytes() helper function for hex strings')
    console.log('  Note: SDK does not provide Utils.fromHex() method')
  } catch (error) {
    console.log('Hex key creation issue:', error.message)
  }
  
  console.log('\nTroubleshooting complete')
}

troubleshootAESIssues()
```

## Testing Your Implementation

### Comprehensive Test Suite

```typescript
function runAESTests() {
  console.log('=== AES Implementation Tests ===')
  let passed = 0
  let total = 0
  
  function test(name: string, testFn: () => boolean) {
    total++
    try {
      const result = testFn()
      if (result) {
        console.log(` ${name}`)
        passed++
      } else {
        console.log(` ${name}`)
      }
    } catch (error) {
      console.log(` ${name} - Error: ${error.message}`)
    }
  }
  
  // Test 1: Basic encryption/decryption
  test('Basic encryption/decryption', () => {
    const key = SymmetricKey.fromRandom()
    const message = 'Hello, World!'
    const encrypted = key.encrypt(message) as number[]
    const decrypted = key.decrypt(encrypted, 'utf8') as string
    return message === decrypted
  })
  
  // Test 2: Binary data handling
  test('Binary data encryption', () => {
    const key = SymmetricKey.fromRandom()
    const binaryData = Random(100)
    const encrypted = key.encrypt(binaryData) as number[]
    const decrypted = key.decrypt(encrypted) as number[]
    return JSON.stringify(binaryData) === JSON.stringify(decrypted)
  })
  
  // Test 3: Large data encryption
  test('Large data encryption', () => {
    const key = SymmetricKey.fromRandom()
    const largeMessage = 'x'.repeat(10000)
    const encrypted = key.encrypt(largeMessage) as number[]
    const decrypted = key.decrypt(encrypted, 'utf8') as string
    return largeMessage === decrypted
  })
  
  // Test 4: Key derivation consistency
  test('Key derivation consistency', () => {
    const password = 'TestPassword123'
    const salt = Random(32)
    const key1 = new SymmetricKey(Hash.sha256([
      ...Utils.toArray(password, 'utf8'),
      ...salt
    ]))
    const key2 = new SymmetricKey(Hash.sha256([
      ...Utils.toArray(password, 'utf8'),
      ...salt
    ]))
    return key1.toHex() === key2.toHex()
  })
  
  // Test 5: Hex encoding/decoding
  test('Hex encoding support', () => {
    const key = SymmetricKey.fromRandom()
    const message = 'Test message'
    const encryptedBytes = key.encrypt(message) as number[]
    const encrypted = bytesToHex(encryptedBytes)
    const hexBytes = hexToBytes(encrypted)
    const decrypted = key.decrypt(hexBytes, 'utf8') as string
    return message === decrypted
  })
  
  console.log(`\nTests completed: ${passed}/${total} passed`)
  return passed === total
}

// Run the test suite
const allTestsPassed = runAESTests()
console.log('\nAll tests passed:', allTestsPassed)
```

## Summary

In this tutorial, you've learned how to:

1. **Generate secure AES encryption keys** using `SymmetricKey.fromRandom()`
2. **Encrypt and decrypt data** with the `encrypt()` and `decrypt()` methods
3. **Handle different data formats** including strings, binary data, and JSON
4. **Derive keys from passwords** using secure hashing techniques
5. **Implement key management** with versioning and rotation
6. **Combine AES with ECDH** for secure communication channels
7. **Apply security best practices** including error handling and validation
8. **Build practical applications** like secure configuration storage
9. **Optimize performance** and troubleshoot common issues

The BSV TypeScript SDK's `SymmetricKey` class provides a robust, secure implementation of AES-GCM encryption that's suitable for production applications. The built-in authentication prevents tampering, while the straightforward API makes it easy to integrate encryption into your Bitcoin applications.

## Next Steps

- Explore the [ECDH Key Exchange](./ecdh-key-exchange.md) tutorial for asymmetric encryption
- Learn about [Messages Reference](../reference/messages.md) for authentication
- Study [Advanced Transaction Construction](./advanced-transaction.md) for complex applications
- Review the [Security Best Practices](../guides/security-best-practices.md) guide

## Additional Resources

- [AES Wikipedia](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
- [GCM Mode Wikipedia](https://en.wikipedia.org/wiki/Galois/Counter_Mode)
- [BSV SDK Primitives Reference](../reference/primitives.md)