Command Line

Contents

• Step 1: Point it at your configuration
• Step 2: Encrypt and decrypt files
• Step 3: Encrypt strings for configuration files
• Step 4: Manage keys
• Option reference
  • Files and strings
  • Configuration and keys
  • Key rotation
  • General
• Next steps

The symmetric-encryption command generates configuration files and keys, rotates keys, and encrypts and decrypts files and strings.

symmetric-encryption --help

Each environment has its own keys, so most commands must be run in the environment they apply to. Generating a configuration file and rotating keys are the exceptions: run those once and copy the result to the environments that need it.

Step 1: Point it at your configuration

The command reads config/symmetric-encryption.yml in the current directory, for the environment in SYMMETRIC_ENCRYPTION_ENV, RACK_ENV or RAILS_ENV, defaulting to development.

Override either per invocation:

symmetric-encryption --config path/to/symmetric-encryption.yml --env production --decrypt secret.enc

Or set them in the environment, so they do not have to be repeated:

export SYMMETRIC_ENCRYPTION_CONFIG="~/application/common/config/symmetric-encryption.yml"
export SYMMETRIC_ENCRYPTION_ENV="production"

Step 2: Encrypt and decrypt files

symmetric-encryption --encrypt large_file.csv --output large_file.csv.enc

Compression is applied by default when encrypting a file. Turn it off with --no-compress:

symmetric-encryption --encrypt photo.jpg --output photo.jpg.enc --no-compress

Decrypt:

symmetric-encryption --decrypt large_file.csv.enc --output large_file.csv

Without --output, the result goes to stdout, so an encrypted file can be inspected without ever writing a decrypted copy to disk:

symmetric-encryption --decrypt large_file.csv.enc | wc -l
symmetric-encryption --decrypt large_file.csv.enc | grep "Hello"
symmetric-encryption --decrypt large_file.csv.enc | head

Without a file name, input is read from stdin, so the command composes with a pipeline:

cat large_file.csv | symmetric-encryption --encrypt --output large_file.csv.enc

Step 3: Encrypt strings for configuration files

Prompt for a value, masked, and print its encrypted form:

symmetric-encryption --encrypt --prompt

You are asked for the value twice, so a typo cannot be encrypted unnoticed. Decrypt one the same way:

symmetric-encryption --decrypt --prompt

Both need the highline gem, which is not a dependency of this gem:

gem "highline"

Generate a random password and print it with its encrypted form, ready to paste into a configuration file:

symmetric-encryption --new-password
symmetric-encryption --new-password 32

Once keys have been rotated, re-encrypt the values already sitting in your configuration files. Values that cannot be decrypted in the current environment are left alone:

symmetric-encryption --re-encrypt "**/*.yml"

Step 4: Manage keys

See Key Rotation for when and why to run these.

symmetric-encryption --generate --app-name my_app     # New configuration file and keys
symmetric-encryption --rotate-keys                    # New data encryption key
symmetric-encryption --rotate-kek                     # New key encrypting keys only
symmetric-encryption --activate-key                   # Make the highest version primary
symmetric-encryption --cleanup-keys                   # Remove all but the highest version

--cleanup-keys names the versions it is about to remove and asks before removing them, because data encrypted with a removed key can no longer be read. Use --force to skip the prompt in a script. When stdin is not a terminal it does not prompt at all, but it still names the versions.

Option reference

Files and strings

Configuration and keys

Key rotation

General

Next steps

• Key Rotation: introducing a new key without downtime.
• Configuration: the configuration file and the keystores.
• Files: the same operations from Ruby.