Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Templates and Data Bags

Encrypted Data Bags and Secrets

Learn how Chef encrypted data bags protect passwords and keys, how the secret key is shared, what the sensitive property does, and modern secrets alternatives.

Configuration often needs secrets: a database password, an API token, a TLS private key. If you put them in a plain data bag, anyone with read access to the Chef Server, or to the Git repository that holds the JSON, can read them. An encrypted data bag protects the values so that only machines that have the shared secret can decrypt them.

In this lesson you will learn how Chef encrypts items, how the secret reaches the node, how to keep secrets out of logs, and what newer tools do the same job better. You will also run a real encryption round trip in Ruby using the OpenSSL library, so you can see what the stored data looks like.

Chef itself does not run on this site. The Chef commands are read-only. The encryption demo is plain Ruby with AES-256-GCM and is a teaching model, not Chef's exact on-disk format.

What an encrypted item looks like

You create an encrypted item with knife and a secret file. The id stays readable, but every other value is replaced by a blob:

Terminal
openssl rand -base64 512 | tr -d '\r\n' > secret_key
knife data bag create credentials db --secret-file secret_key
JSON
{
  "id": "db",
  "password": {
    "encrypted_data": "Xw2k...==",
    "iv": "9fQ1...==",
    "auth_tag": "4mJ0...==",
    "version": 3,
    "cipher": "aes-256-gcm"
  }
}

Chef (item format version 3) uses AES-256-GCM. Each value gets its own random IV (initialization vector) and an authentication tag. GCM is an authenticated mode: if somebody changes the encrypted bytes, decryption fails instead of returning garbage.

Encrypt and decrypt in Ruby

Here is the same idea with Ruby's openssl. The key is derived from a shared secret with SHA-256, each value gets a fresh random IV, and the tag detects tampering.

Ruby AES-256-GCM round trip with a shared secret

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The program prints that the plaintext is not visible in the blob, decrypts it with the right secret, and refuses both a wrong secret and a modified ciphertext. That is the same guarantee Chef's version 3 format gives.

Using encrypted items in a recipe

In a recipe you load the item with the secret, and Chef decrypts transparently:

Ruby
secret = Chef::EncryptedDataBagItem.load_secret('/etc/chef/encrypted_data_bag_secret')
creds = Chef::EncryptedDataBagItem.load('credentials', 'db', secret)

template '/etc/myapp/db.yml' do
  source 'db.yml.erb'
  mode '0600'
  variables(password: creds['password'])
  sensitive true
end

If the secret is at the default path /etc/chef/encrypted_data_bag_secret, data_bag_item('credentials', 'db') decrypts automatically for you. Two details matter:

  • sensitive true hides the diff and content from logs and from Chef reports. Without it the password may appear in the console.
  • File mode 0600 stops other users on the machine from reading the result.

The hard part: delivering the secret

Encryption only moves the problem: now the secret key must reach each node. Common ways:

  1. Bake it into the machine image or provisioning script (/etc/chef/encrypted_data_bag_secret, mode 0600).
  2. Fetch it at bootstrap time from a cloud secret store with the instance's identity.
  3. Use a different secret per environment, so a leaked test key does not expose production.

Rotation is manual: you must re-encrypt every item with the new key and update every node. That pain is a big reason teams look at alternatives.

Better options today

flowchart TD
  A["Where do secrets live?"] --> B["Encrypted data bag: simple, key distribution is yours"]
  A --> C["Chef Vault: per-node keys, uses node public keys"]
  A --> D["Secrets manager: Vault, cloud KMS, central rotation"]

Choose by how many secrets you have and how often they rotate.

  • Chef Vault (chef-vault gem) encrypts each item for specific nodes, using their public keys. There is no shared secret file to distribute, and you can grant or revoke access per node.
  • Chef Infra 17+ secrets helper: a secret function can fetch values from a store such as AWS Secrets Manager, Azure Key Vault or HashiCorp Vault at converge time, so the secret never lives in the Chef Server:
Ruby
password = secret(name: 'db-password', service: :hashi_vault, config: { vault_addr: 'https://vault.example.com' })

For new work, prefer a secrets manager and the helper, and keep encrypted data bags for small setups.

Habits that keep secrets safe

  • Never commit the secret key. Add it to .gitignore.
  • Do not print secrets with Chef::Log or puts.
  • Keep decrypted values in variables and mark the resource sensitive true.
  • Give each environment its own key and rotate when staff leave.
  • Review who can read the Chef Server: encrypted bags protect against casual reading, not against someone who also holds the key.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which part of an encrypted data bag item stays readable?

    The id remains plain so Chef can find the item. The other values are replaced by encrypted blobs.
  2. 2. What does the auth_tag of AES-GCM provide?

    GCM authenticates the data. If anything is changed, decryption fails instead of returning wrong data.
  3. 3. What does sensitive true do on a resource?

    It only suppresses output. You still need proper file modes to protect the file on the node.
  4. 4. What is the main advantage of Chef Vault over a shared secret file?

    Chef Vault grants access per node, which makes adding and revoking access easier.
  5. 5. Why is a leaked secret key a serious problem?

    The key unlocks all items encrypted with it, so keep it out of Git and rotate it when needed.

Summary

  • Encrypted data bags keep id readable and replace values with AES-256-GCM blobs (IV, tag, ciphertext).
  • Nodes need the shared secret at /etc/chef/encrypted_data_bag_secret or another path; delivering it is the real challenge.
  • Use sensitive true, restrictive file modes and separate keys per environment.
  • Chef Vault and the secrets helper with an external manager avoid distributing one shared key.
  • Never commit keys or print decrypted values.

Next: Roles and Run Lists