145 lines
4.9 KiB
Markdown
145 lines
4.9 KiB
Markdown
# Encryption Fix Summary
|
|
|
|
## Problem
|
|
The application was failing in production with the error:
|
|
```
|
|
Decryption error: TypeError: crypto.createDecipher is not a function
|
|
```
|
|
|
|
This occurred because `crypto.createDecipher` and `crypto.createCipher` have been deprecated and removed in newer versions of Node.js.
|
|
|
|
## Root Cause
|
|
- **Local Development**: Running on older Node.js version that still supports deprecated crypto methods
|
|
- **Production (Dokploy)**: Running on newer Node.js version where these methods have been removed
|
|
- **Deprecated Methods**: `crypto.createCipher()` and `crypto.createDecipher()` are no longer available
|
|
|
|
## Solution Implemented
|
|
|
|
### 1. **Updated Encryption Methods**
|
|
- **Before**: Used `crypto.createCipher(algorithm, key)`
|
|
- **After**: Using `crypto.createCipheriv(algorithm, key, iv)` with proper IV (Initialization Vector)
|
|
|
|
### 2. **Backward Compatibility**
|
|
- Added legacy decryption support for existing encrypted data
|
|
- Graceful fallback handling for corrupted or unreadable data
|
|
- Migration utility to convert old format to new format
|
|
|
|
### 3. **Enhanced Error Handling**
|
|
- Mail settings page won't crash if decryption fails
|
|
- Returns empty password instead of crashing the application
|
|
- Comprehensive error logging for debugging
|
|
|
|
### 4. **New Encryption Format**
|
|
- **Format**: `IV:EncryptedData` (both in hex)
|
|
- **Algorithm**: AES-256-CBC with random IV for each encryption
|
|
- **Security**: Each encryption uses a unique IV for better security
|
|
|
|
## Files Modified
|
|
|
|
### 1. **app/utils/encryption.server.ts**
|
|
- ✅ Updated `encrypt()` to use `crypto.createCipheriv()`
|
|
- ✅ Updated `decrypt()` to use `crypto.createDecipheriv()`
|
|
- ✅ Added backward compatibility for legacy encrypted data
|
|
- ✅ Added migration utility `migrateEncryption()`
|
|
- ✅ Enhanced error handling and validation
|
|
- ✅ Added format detection functions
|
|
|
|
### 2. **app/routes/mail-settings.tsx**
|
|
- ✅ Added graceful error handling in loader
|
|
- ✅ Enhanced action to handle password migration
|
|
- ✅ Better error messages for users
|
|
|
|
### 3. **app/routes/test-encryption.tsx**
|
|
- ✅ Added migration testing
|
|
- ✅ Enhanced test coverage
|
|
- ✅ Added environment information display
|
|
|
|
### 4. **.env.dokploy**
|
|
- ✅ Added missing `ENCRYPTION_KEY` environment variable
|
|
|
|
## Key Features
|
|
|
|
### 1. **Migration Support**
|
|
```typescript
|
|
// Automatically handles legacy format
|
|
const decrypted = decrypt(encryptedPassword); // Works with both old and new formats
|
|
const migrated = migrateEncryption(oldEncryptedData); // Converts to new format
|
|
```
|
|
|
|
### 2. **Format Detection**
|
|
```typescript
|
|
isEncrypted(text) // Detects new format (contains ':')
|
|
isLegacyEncrypted(text) // Detects old format (hex only)
|
|
```
|
|
|
|
### 3. **Graceful Degradation**
|
|
- If decryption fails, returns original text instead of crashing
|
|
- Mail settings page shows masked password if decryption fails
|
|
- Comprehensive error logging for debugging
|
|
|
|
## Environment Variables Required
|
|
|
|
### Production (.env.dokploy)
|
|
```bash
|
|
ENCRYPTION_KEY=production-secure-encryption-key!
|
|
```
|
|
|
|
**Important**: The encryption key should be exactly 32 characters for optimal security.
|
|
|
|
## Testing
|
|
|
|
### 1. **Test Encryption Route**
|
|
Visit `/test-encryption` (Super Admin only) to verify:
|
|
- ✅ Basic encryption/decryption works
|
|
- ✅ Migration functionality works
|
|
- ✅ Different password types work
|
|
- ✅ Environment information is correct
|
|
|
|
### 2. **Mail Settings**
|
|
- ✅ Existing encrypted passwords are handled gracefully
|
|
- ✅ New passwords are encrypted with new format
|
|
- ✅ Settings can be saved and loaded without errors
|
|
|
|
## Deployment Steps
|
|
|
|
### 1. **Update Environment Variables**
|
|
Make sure `ENCRYPTION_KEY` is set in your Dokploy environment variables:
|
|
```bash
|
|
ENCRYPTION_KEY=your-32-character-encryption-key
|
|
```
|
|
|
|
### 2. **Deploy Updated Code**
|
|
The updated encryption utility will:
|
|
- Handle existing encrypted data automatically
|
|
- Use new encryption format for new data
|
|
- Provide backward compatibility
|
|
|
|
### 3. **Verify Functionality**
|
|
1. Check mail settings page loads without errors
|
|
2. Test saving mail settings
|
|
3. Visit `/test-encryption` to verify encryption works
|
|
4. Check application logs for any encryption errors
|
|
|
|
## Security Improvements
|
|
|
|
### 1. **Better Encryption**
|
|
- Uses proper IV (Initialization Vector) for each encryption
|
|
- More secure than the deprecated methods
|
|
- Each encrypted value is unique even for same input
|
|
|
|
### 2. **Forward Compatibility**
|
|
- Code is compatible with current and future Node.js versions
|
|
- No dependency on deprecated crypto methods
|
|
|
|
### 3. **Error Resilience**
|
|
- Application won't crash due to encryption issues
|
|
- Graceful handling of corrupted encrypted data
|
|
- Comprehensive error logging
|
|
|
|
## Node.js Version Compatibility
|
|
- ✅ **Node.js 16+**: Full support
|
|
- ✅ **Node.js 18+**: Full support
|
|
- ✅ **Node.js 20+**: Full support
|
|
- ❌ **Node.js 14 and below**: May have issues with deprecated methods
|
|
|
|
The fix ensures your application works reliably across different Node.js versions in various deployment environments. |