Security Guide

This guide provides best practices for managing encryption keys and securing your data with Frostbite. Following these recommendations will help you maintain a high level of security for your sensitive information.

Encryption Details

Frostbite uses industry-standard encryption algorithms to protect your data:

Encryption Algorithm

Frostbite uses AES-256-GCM (Advanced Encryption Standard with 256-bit keys in Galois/Counter Mode) for all encryption operations. This provides:

  • Confidentiality: AES-256 is a symmetric encryption algorithm that ensures your data remains private.
  • Integrity: GCM mode provides authentication, ensuring that encrypted data hasn't been tampered with.
  • Performance: AES-256-GCM is hardware-accelerated on modern processors for efficient encryption/decryption.

Key Derivation

User-provided passwords or keys are processed using PBKDF2 (Password-Based Key Derivation Function 2) with the following parameters:

  • Iterations: 100,000 rounds to slow down brute-force attacks
  • Salt: A unique salt is generated for each key
  • Hash Function: SHA-256 for the underlying hash operations
  • Output Key Length: 256 bits (32 bytes)

File Format

Encrypted files use the .fbz extension and have the following structure:

  • IV (12 bytes): Initialization Vector for AES-GCM
  • Auth Tag (16 bytes): Authentication tag for verifying integrity
  • Encrypted Data (variable length): The encrypted content

Key Management

Proper key management is critical for maintaining the security of your encrypted data:

Choosing Strong Keys

Always use strong, high-entropy keys:

  • Use at least 16 characters for password-based keys
  • Include a mix of uppercase, lowercase, numbers, and special characters
  • Avoid dictionary words, names, or predictable patterns
  • Consider using a password manager to generate and store keys

Storing Keys Securely

Never store encryption keys in plaintext or in your source code:

  • Environment Variables: Use environment variables for development and production
  • Secret Management Services: Use AWS Secrets Manager, Google Secret Manager, or HashiCorp Vault for production environments
  • Hardware Security Modules (HSMs): For high-security environments, consider using HSMs to store keys

Using Environment Variables

# Set the encryption key as an environment variable
export FROSTBITE_KEY="your-secure-encryption-key"

# Use the environment variable in your application
frostbite lock config.json --env FROSTBITE_KEY

Using License Keys

License keys provide an additional layer of security:

  • They act as a second factor for encryption/decryption
  • They can be distributed separately from the main encryption key
  • They can be tied to specific environments or deployments
# Using both a key and a license
frostbite lock config.json --key mySecretKey --license my-license-key

Security Best Practices

Follow these best practices to maintain a high level of security:

File Management

  • Commit only encrypted files: Never commit decrypted sensitive files to your repository
  • Use .gitignore: Add patterns to your .gitignore to prevent accidentally committing decrypted files
  • Use .frostbiteignore: Create a .frostbiteignore file to specify which files should not be encrypted

Memory Management

  • Use the Runtime API: For live applications, use the Runtime API to decrypt files in memory without writing to disk
  • Clear sensitive data: Clear sensitive data from memory when it's no longer needed
  • Avoid logging sensitive data: Never log encryption keys or decrypted sensitive data

Access Control

  • Principle of least privilege: Only give access to encryption keys to those who need them
  • Separate duties: Consider using different keys for different environments or types of data
  • Audit access: Keep track of who has access to encryption keys and when they're used

CI/CD Security

Securely integrating Frostbite into your CI/CD pipeline:

Storing Secrets in CI/CD

Most CI/CD platforms provide secure ways to store secrets:

  • GitHub Actions: Use repository secrets
  • GitLab CI: Use CI/CD variables
  • Jenkins: Use the Credentials plugin
  • CircleCI: Use environment variables or contexts

Example GitHub Actions Workflow

name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install dependencies
        run: npm ci

      - name: Decrypt configuration
        run: npx frostbite unlock config/production.json.fbz --key ${{ secrets.FROSTBITE_KEY }}

      - name: Build application
        run: npm run build

      - name: Clean up decrypted files
        run: |
          find config -type f -not -name "*.fbz" -delete

      - name: Deploy
        run: npm run deploy

Temporary Decryption

In CI/CD pipelines, decrypt files only when needed and clean up afterward:

  • Decrypt files just before they're needed
  • Remove decrypted files as soon as they're no longer needed
  • Use separate build stages to isolate decrypted files

Key Rotation

Regularly rotating encryption keys is a security best practice:

When to Rotate Keys

  • Regularly scheduled rotation: Every 90-180 days
  • After personnel changes: When someone with key access leaves the team
  • After a suspected breach: If you suspect a key may have been compromised
  • When upgrading security: When moving to a more secure key management system

Key Rotation Process

Frostbite provides the rekey command to simplify key rotation:

# Re-encrypt files with a new key
frostbite rekey config/ --old-key oldSecretKey --new-key newSecretKey

# Using environment variables
export OLD_KEY="old-secret-key"
export NEW_KEY="new-secret-key"
frostbite rekey config/ --old-env OLD_KEY --new-env NEW_KEY

Programmatic Key Rotation

const frostbite = require('frostbite');

async function rotateKeys() {
  try {
    const result = await frostbite.rekey('./sensitive-data', {
      oldKey: process.env.OLD_FROSTBITE_KEY,
      newKey: process.env.NEW_FROSTBITE_KEY,
      oldLicense: process.env.OLD_LICENSE,
      newLicense: process.env.NEW_LICENSE
    });

    console.log(`Re-encrypted ${result.files.length} files with new key`);
  } catch (error) {
    console.error('Key rotation failed:', error);
  }
}

Threat Model

Understanding the security guarantees and limitations of Frostbite:

What Frostbite Protects Against

  • Data at rest exposure: Protects sensitive files stored in repositories or on disk
  • Unauthorized access: Prevents access without the correct encryption key
  • Accidental exposure: Reduces the risk of accidentally committing sensitive data
  • Data integrity violations: Detects if encrypted files have been tampered with

Limitations

  • Data in use: Once decrypted in memory, data protection depends on your application's security
  • Key security: Frostbite can't protect against compromised encryption keys
  • Memory attacks: Doesn't protect against memory dumping or side-channel attacks
  • Malicious code: Doesn't protect against malicious code that has access to your application's memory

Complementary Security Measures

Frostbite should be part of a comprehensive security strategy:

  • Access controls: Implement proper authentication and authorization
  • Network security: Use TLS/SSL for data in transit
  • Secure coding practices: Follow secure coding guidelines to prevent vulnerabilities
  • Regular security audits: Conduct security reviews and penetration testing
  • Monitoring and logging: Implement monitoring to detect suspicious activity