Field-Level Encryption Service

A TypeScript-based service that provides field-level encryption capabilities using Google Cloud KMS and Secret Manager.

Features

• Field-level encryption for sensitive data
• Integration with Google Cloud KMS for key management
• Secure storage of encrypted data encryption keys (DEKs) in Google Cloud Secret Manager
• Support for multiple encryption algorithms (AES-256-GCM, AES-256-CBC)
• Automatic key rotation and versioning
• Comprehensive error handling and validation

Prerequisites

• Node.js (v14 or higher)
• TypeScript
• Google Cloud Platform account with:
  • Cloud KMS enabled
  • Secret Manager enabled
  • Appropriate IAM permissions
• Environment variables:
  • GOOGLE_CLOUD_PROJECT: Your GCP project ID
  • GOOGLE_APPLICATION_CREDENTIALS: Path to your service account key file

Project Structure

src/
├── services/
│   ├── encryptionService.ts    # Core encryption service
│   ├── kmsService.ts          # Google Cloud KMS integration
│   └── secretManagerService.ts # Google Cloud Secret Manager integration
├── types/
│   └── errors.ts              # Custom error types and codes
└── utils/
    └── encryptionUtils.ts     # Encryption utility functions

Core Components

Encryption Service (encryptionService.ts)

• Handles field-level encryption and decryption
• Manages data encryption keys (DEKs)
• Supports multiple encryption algorithms
• Provides key rotation capabilities

KMS Service (kmsService.ts)

• Manages encryption keys in Google Cloud KMS
• Handles key creation and rotation
• Provides key metadata management

Secret Manager Service (secretManagerService.ts)

• Stores encrypted DEKs securely
• Manages secret versions
• Handles secret retrieval and updates

Error Handling

The service implements a comprehensive error handling system with custom error types:

• ConfigurationError: For initialization and configuration issues
• EncryptionError: For encryption/decryption failures
• ValidationError: For input validation failures

Each error type includes specific error codes for better error tracking and handling.

Usage Example

Parameters

modelName (string)

The key identifier used in your encryption.json configuration file. This should match the model name you've configured for encryption.

sensitiveData (string)

The data you want to encrypt. This can be any string value that needs to be protected.

entityKeyDetails (object)

An object containing all required fields for encryption and decryption operations:

interface EntityKeyDetails {
    locationId: string | null;    // Google Cloud KMS location ID
    keyRingId: string | null;     // KMS key ring identifier
    keyId: string | null;         // KMS key identifier
    secretId: string | null;      // Secret Manager secret ID
    encryptedDEK?: Buffer | null; // Encrypted Data Encryption Key
    keyVersion: string | null;    // KMS key version
}

Example Usage

import encryptionService from './services/encryptionService';

// Encrypt a field
const encryptedField = await encryptionService.encryptField(
    'model-name',
    'sensitive-data',
    entityKeyDetails
);

// Decrypt a field
const decryptedField = await encryptionService.decryptField(
    'model-name',
    'encrypted-data',
    entityKeyDetails
);

Security Considerations

• All encryption keys are managed by Google Cloud KMS
• DEKs are encrypted before storage
• Automatic key rotation is supported
• Input validation and sanitization
• Comprehensive error handling
• No sensitive data in logs

Development

1. Clone the repository
2. Install dependencies:

   npm install

3. Set up environment variables
4. Run tests:

   npm test

Error Codes

Configuration Errors

• CONFIGURATION_MISSING_CONFIG: Required configuration is missing
• CONFIGURATION_MISSING_ENV_VAR: Required environment variable is missing
• CONFIGURATION_INITIALIZATION_ERROR: Service initialization failed

Encryption Errors

• ENCRYPTION_FIELD_ENCRYPTION_ERROR: Field encryption failed
• ENCRYPTION_FIELD_DECRYPTION_ERROR: Field decryption failed
• ENCRYPTION_DEK_RESOLUTION_ERROR: DEK resolution failed
• ENCRYPTION_DEK_DECRYPTION_ERROR: DEK decryption failed
• ENCRYPTION_DEK_ENCRYPTION_ERROR: DEK encryption failed
• ENCRYPTION_SECRET_RETRIEVAL_ERROR: Secret retrieval failed
• ENCRYPTION_UNKNOWN_ERROR: Unknown encryption error
• ENCRYPTION_KEY_DETAILS_ERROR: Key details retrieval failed
• ENCRYPTION_KEY_VERSION_ERROR: Key version error
• ENCRYPTION_KEY_CREATION_ERROR: Key creation failed
• ENCRYPTION_CREATION_ERROR: General creation error

Validation Errors

• VALIDATION_MISSING_REQUIRED_FIELD: Required field is missing
• VALIDATION_INVALID_DEK: Invalid DEK format or content

License

MIT