Skip to main content

Encrypting sensitive configuration

Certain information such as access tokens, secret keys, passwords, certificates etc. is considered as sensitive data thus should not be committed to the repository as plain text.

Silta supports encryption/decryption of such information via silta-cli, furthermore, silta-cli can be used both locally and during the build/deploy, thus making the process simple and consistent. Official documentation of silta-cli can be found here.

Encryption & decryption​

To encrypt a file for secure storing within repository, silta secrets encrypt command is used. When used in Silta, encrypted files have to be decrypted during the build or deployment to take effect. See the walkthrough example below.

1. Get the encryption key​

Please refer to the section related to encryption keys

2. Create and encrypt the file containing sensitive information​

silta-cli allows to encrypt any file, i.e. it can be Silta configuration file containing sensitive data within environment variables or TLS certificates, an actual TLS certificate file located at /secrets/server.crt or anything else. Below are some examples:

  • Sensitive Silta configuration for Drupal chart
php:
  hashsalt: super-secret
  env:
    IMPORTANT_API_KEY: super-secret
  • Sensitive Silta configuration for Frontend chart
services:
  node:
    env:
      IMPORTANT_API_KEY: super-secret

Once you have the file ready for encryption, run:

silta secrets encrypt --file /path/to/file --secret-key <secret-key>

Or, if you have the encryption key stored as a local environment variable, use that as a reference instead:

silta secrets encrypt --file /path/to/file --secret-key-env ENV_VAR_NAME

Note that silta secrets encrypt encrypts the source file itself unless you specify a different target path via the --output-file flag (see full docs here)

3. Add decryption to CircleCI configuration​

When used in Silta, files have to be decrypted to take effect. For this you need to alter the relevant build/deploy jobs, you can use one of the two options below.

decrypt_files parameter​

Caveats:

  • decrypt_files is only supported in silta/drupal-build-deploy, silta/drupal-build and silta/drupal-deploy jobs, thus only the Drupal chart
  • You can't specify a custom encryption key

Advantages:

  • simpler configuration, no need to specify or generate an encryption key - one defined in CircleCI context (SECRET_KEY) is used. Note that it's expected that secrets are encrypted with the same key locally (to get the key, refer to encryption keys section).

Usage example:

decrypt_files: path/to/encrypted/file
  • path/to/encrypted/file is relative to the build folder (root)

This approach has slightly more complex configuration however it also has more advantages:

  • Allows to specify a custom encryption key
  • Supported by all charts:
    • Drupal (silta/drupal-build, silta/drupal-deploy, silta/drupal-build-deploy jobs). Note: use pre-release parameter in silta/drupal-deploy
    • Frontend (silta/frontend-build-deploy job)
    • Simple (silta/simple-build-deploy job)

Usage examples:

In silta/drupal-build:

codebase-build:
- silta/decrypt-files:
    files: sso/saml.crt
    secret_key_env: MY_PROJECT_SECRET_KEY

In silta/drupal-deploy:

pre-release:
- silta/decrypt-files:
    files: silta/secrets
    secret_key_env: MY_PROJECT_SECRET_KEY
  • Note: If you don't specify the secret_key_env parameter, default encryption key from CircleCI context will be used as mentioned earlier.

Note for projects using silta/drupal-build and silta/drupal-deploy

If project uses separate jobs for build and deploy, the job you add the decryption to depends on the use-case:

  • if secret needs to be in a decrypted form during application runtime, i.e., TLS certificate for SSO integration, add it under silta/drupal-build.
  • if secret needs to be decrypted only during the deployment, i.e., Silta configuration file, add it under silta/drupal-deploy

Decrypting existing secrets locally​

To inspect or alter information in encrypted files, you have to decrypt them locally.

  1. Get the encryption key (refer to the Secret keys section of this document)
  2. Run:
silta secrets decrypt --file /path/to/encrypted/file --secret-key <secret-key>

or, if you have secret key stored as local environment variable:

silta secrets decrypt --file /path/to/encrypted/file --secret-key-env ENV_VAR_NAME

Note that silta secrets decrypt decrypts the source file itself unless you specify the--output-file flag. See full docs of the decryption command here

Remember not to commit decrypted secret files!

Encryption keys​

For new projects​

It's strongly recommended to create project-specific encryption keys or even environment specific ones for better security. Here's a walkthrough example.

  1. In CircleCI, click "Settings" button in the top-right corner of your project's overview page, then choose "Environment variables" from the sidebar on the left. Click "Add environment variable". Name it something like MY_PROJECT_SECRET_KEY and generate a secure random value for it, i.e. on Unix based systems you can use this command:
head -c 32 /dev/urandom | base64
  1. Use this key locally for encryption
  2. Update your CircleCI configuration to use the same key, i.e., in silta/drupal-build add:
codebase-build:
- silta/decrypt-files:
    files: path/to/file
    secret_key_env: MY_PROJECT_SECRET_KEY

A few notes:

  • You can refer to this example when switching encryption keys for an existing project. However, bear in mind that you must first locally decrypt existing secrets with the old encryption key and re-encrypt them with the new one for things to work.
  • Projects can have multiple encryption keys, i.e, one for development, one for staging and another one for production environment. If you choose to go this path, make sure you use the right key when encrypting/decrypting secrets per environment.

For existing projects​

To get the encryption key from and existing project, follow the guide below.

  1. Determine name of the CircleCI environment variable the project uses for decryption. This can be done by inspecting project's CircleCI configuration file and searching for secret_key_env references.

If references are found, i.e., secret_key_env: MY_PROJECT_SECRET_KEY.

This indicates that project utilises custom encryption key(s) stored in CircleCI's environment variable(s).

If references are not found

This indicates that project uses the default encryption key stored in CircleCI's context as SECRET_KEY environment variable (reference to Silta CircleCI orb). Note that project can utilise multiple contexts, check for context information in your CircleCI config to see which one is in use.

  1. Get value of the particular CircleCI environment variable, note that when inspecting via CircleCI UI values are redacted due to security reasons. To get the actual value of the env var, you must SSH into a CircleCI environment.
  2. In CircleCI, go to your project's pipelines page, find the last successful pipeline of the environment you need to get the encryption key for. Now find the job you're interested in and rerun if with SSH (from top-right corner choose "Rerun > Rerun job with SSH").
  3. Wait for the job to run until it's successful and "Waiting for SSH sessions". Use the SSH command from CircleCI's output, it should look something like this:
ssh -p 54782 50.19.60.152
  1. After SSH'ing into CircleCI env, run the following command to get the encryption key value (replace MY_PROJECT_SECRET_KEY with the actual env var name):
printenv MY_PROJECT_SECRET_KEY
  1. Securely store the value locally for further use, i.e. set it as an environment variable