Password Pusher uses the AES-GCM (Advanced Encryption Standard - Galois/Counter Mode) algorithm to encrypt sensitive data stored in the database. This ensures that push payloads (passwords, text, URLs, file metadata) are encrypted at rest.

Overview

Password Pusher uses two different encryption keys for different purposes:

  1. PWPUSH_MASTER_KEY - Encrypts sensitive push data in the database (passwords, text, URLs, etc.)
  2. SECRET_KEY_BASE - Used for session cookie encryption and Rails security features

Important: For production deployments, you should set both keys to unique, randomly generated values. Using the default keys is less secure and not recommended for production.

Database Encryption (PWPUSH_MASTER_KEY)

The PWPUSH_MASTER_KEY is used to encrypt sensitive push payloads before they are stored in the database. This includes:

  • Password push contents
  • Text push contents
  • URL push contents
  • File push metadata

What gets encrypted: The actual sensitive content of pushes is encrypted. Push metadata (expiration dates, view counts, etc.) is stored in plain text for functionality.

Encryption Algorithm: AES-GCM provides authenticated encryption, ensuring both confidentiality and integrity of the encrypted data.

Why Set a Custom Key?

Security: Using your own unique encryption key ensures that your encrypted data cannot be decrypted by anyone who has access to the default key. This is especially important for self-hosted instances.

Default Key Risk: If you don’t set a custom key, Password Pusher uses a default key that is the same across all instances. While this key is not publicly disclosed, using your own key provides better security.

Recommendation: Always generate and use your own unique encryption key for production deployments.

Generating an Encryption Key

You can generate a new encryption key using several methods:

Online Helper Tool (Easiest)

The easiest way to generate a key is using the online helper tool:

Generate Encryption Key

This tool generates a new random key on every page load and provides it in a format ready to copy.

Using Docker Container

If you have a Password Pusher container running:

# Access the container
docker exec -it <container_id> bundle exec rails console

# Generate a new key
Lockbox.generate_key

From Application Source

If you have the Password Pusher source code:

# Navigate to the application directory
cd /path/to/PasswordPusher

# Start the Rails console
bundle exec rails console

# Generate a new key
Lockbox.generate_key

The output will be a 64-character hexadecimal string like:

0c110f7f8d93d2123f36debf8a24bf835f33f248681714776b336849b801f693

Setting the Encryption Key

Once you have generated a key, set it using the PWPUSH_MASTER_KEY environment variable.

Docker Run

docker run -d \
  --env PWPUSH_MASTER_KEY=0c110f7f8d93d2123f36debf8a24bf835f33f248681714776b336849b801f693 \
  -p "80:80" -p "443:443" \
  pglombardo/pwpush:latest

Docker Compose

Add to your docker-compose.yml:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    environment:
      PWPUSH_MASTER_KEY: '0c110f7f8d93d2123f36debf8a24bf835f33f248681714776b336849b801f693'

For better security, store the key in a .env file (and add it to .gitignore):

.env file:

PWPUSH_MASTER_KEY=0c110f7f8d93d2123f36debf8a24bf835f33f248681714776b336849b801f693

docker-compose.yml:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    env_file:
      - .env

Shell/System Environment

For non-Docker deployments:

export PWPUSH_MASTER_KEY=0c110f7f8d93d2123f36debf8a24bf835f33f248681714776b336849b801f693

Important Security Notes

Default Key Behavior: If no encryption key is provided, Password Pusher will use a default key. While functional, this is not recommended for production as it’s the same across all instances using the default.

Changing Keys:

  • Warning: Changing the encryption key will make all existing encrypted pushes unreadable. The encrypted data cannot be decrypted with the new key.
  • New pushes created after the key change will work fine with the new key.
  • Old pushes encrypted with the previous key will be unreadable.
  • Plan key changes carefully and ensure all important pushes have been retrieved before changing keys.

Key Rotation: If you need to rotate keys while maintaining access to old pushes, you can use the PWPUSH_MASTER_KEY_PREVIOUS environment variable to support multiple keys during a transition period. Contact support or check the source code for details on this advanced feature.

Data Deletion: Once a push expires (by time or views), all encrypted data is permanently deleted from the database. This is by design for security.

Best Practices:

  • Generate a unique key for each instance
  • Store keys securely (use secrets management in production)
  • Never commit keys to version control
  • Use short expiration times if using the default key
  • Backup your key securely (losing it means losing access to encrypted data)

Session Encryption (SECRET_KEY_BASE)

The SECRET_KEY_BASE environment variable is used by Rails for:

  • Encrypting and signing session cookies
  • Generating secure tokens
  • Other Rails security features

Note: This is different from PWPUSH_MASTER_KEY. SECRET_KEY_BASE handles session and cookie security, while PWPUSH_MASTER_KEY handles database encryption of push payloads.

When to Set SECRET_KEY_BASE

You should set SECRET_KEY_BASE if:

  • Users are getting logged out after container restarts or deployments
  • You’re running multiple instances and need consistent sessions
  • You want to ensure session cookies remain valid across deployments

Default Behavior: If not set, Rails generates a random key on each application start, which invalidates all existing sessions. This is why users get logged out after restarts.

Generating SECRET_KEY_BASE

Using Docker Container

# Access the container
docker exec -it <container_id> /opt/PasswordPusher/bin/pwpush secret

From Application Source

# Navigate to the application directory
cd /path/to/PasswordPusher

# Generate a secret
./bin/pwpush secret

Example output:

$ ./bin/pwpush secret
f7af32f6f51fff9df4e0ae9dd127a6588ab07d0988bd805ba5e650cb5399z30cc225aec2848c9c763549c31260203a751601e7ef28c2b7aa353ee533644c0d05

$ ./bin/pwpush secret
df04f112ff508f8f8aa92e942ffb0ed8b252cbd9ae59fadc7b69e1d3190439796e62f20c7b431ae1285682857183fb55c567223210b98a7558de6975499468b6

Each run generates a new, unique secret key.

Setting SECRET_KEY_BASE

Docker Compose

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    environment:
      SECRET_KEY_BASE: 'f7af32f6f51fff9df4e0ae9dd127a6588ab07d0988bd805ba5e650cb5399z30cc225aec2848c9c763549c31260203a751601e7ef28c2b7aa353ee533644c0d05'

Using .env File

.env file:

SECRET_KEY_BASE=f7af32f6f51fff9df4e0ae9dd127a6588ab07d0988bd805ba5e650cb5399z30cc225aec2848c9c763549c31260203a751601e7ef28c2b7aa353ee533644c0d05

Note: Like PWPUSH_MASTER_KEY, store SECRET_KEY_BASE securely and never commit it to version control.

Key Management Best Practices

Security Recommendations

  1. Generate Unique Keys: Always generate unique keys for each instance
  2. Store Securely: Use secrets management systems in production (Docker secrets, Kubernetes secrets, etc.)
  3. Never Commit: Never commit encryption keys to version control
  4. Backup Safely: Backup keys securely - losing them means losing access to encrypted data
  5. Rotate Periodically: Consider rotating keys periodically, but plan carefully to avoid data loss

Production Deployment

For production deployments:

  1. Generate both PWPUSH_MASTER_KEY and SECRET_KEY_BASE
  2. Store them in a secure secrets management system
  3. Use environment variables or .env files (excluded from Git)
  4. Document key locations in a secure password manager (not in code)
  5. Have a disaster recovery plan for key loss

Development vs Production

  • Development: Default keys are acceptable for testing
  • Production: Always use custom, unique keys for both PWPUSH_MASTER_KEY and SECRET_KEY_BASE

See Also

Updated: