Credentials, secrets and Active Record encryption

A Kaksha engineer who commits the app’s credentials key file to a public repository has leaked every secret the app holds: the key that signs and encrypts every cookie, the payment token, the SMTP password. A different leak is quieter: an attacker who copies 50,000 rows of the guardians table from a backup walks away with 50,000 plain phone numbers, and the column cannot be queried if it was encrypted the wrong way.

A Rails 8.1 app ships three defences for them. Rails credentials keep the API keys and passwords the app needs in one encrypted file. secret_key_base signs and encrypts what the running app hands to a browser. Active Record encryption encrypts chosen columns, so a copied backup gives nothing away. Each has a failure mode and a fix.

Where a Rails 8 app keeps its secrets

Rails credentials are one encrypted file and one key file. bin/rails credentials:edit writes config/credentials.yml.enc, which is encrypted and checked into git, and config/master.key, which holds the key that decrypts it and is listed in .gitignore. The encrypted credentialsencrypted credentials: The config/credentials.yml.enc file Rails ships with: a YAML file encrypted with a key read from a git-ignored key file or the RAILS_MASTER_KEY variable, holding secret_key_base and the app's API keys. file is useless on its own, and the credentials keycredentials key: The key that unlocks a Rails app's encrypted credentials: kept in a git-ignored key file on a developer laptop, or in the RAILS_MASTER_KEY environment variable on a server. file is useless on its own; the pair is what matters. A deploy almost never puts the key file on the server: it sets RAILS_MASTER_KEY as an environment variable instead, so a container image can be identical for development, staging and production.

Per-environment credentials go in config/credentials/production.yml.enc next to its own production.key, and when that file exists production reads it in place of the shared one. The 8.1 command bin/rails credentials:fetch stripe.secret_key prints one value for a deploy script, so a shell command never opens the whole file; the generated .kamal/secrets shows it in a commented example.

What signs cookies and what the log filter hides

secret_key_base is one credential, and the app derives its keys from it with ActiveSupport::KeyGenerator and a salt per use: one for signed cookies, one for encrypted cookies (the session cookie is one of them), and one for each named message verifier, such as the one behind generates_token_for tokens. Changing secret_key_basesecret_key_base: The credential Rails derives cookie-signing, cookie-encryption and message-signing keys from, with ActiveSupport::KeyGenerator; one value for the whole app, held in encrypted credentials. therefore signs every user out, and the security guide adds that encrypted cookies, signed cookies and Active Storage files may be affected too, unless the old value is registered as a rotation.

The second place a secret shows up is a smaller file. config/initializers/filter_parameter_logging.rb carries the filter_parametersfilter_parameters: The Rails config list whose entries are substring-matched against parameter keys so matching values become [FILTERED] in logs; the generator writes a list that starts with passw, email, secret, token. list:

# Shows what the generated config/initializers/filter_parameter_logging.rb hides from Rails logs.
# The filter list below is the one Rails 8.1.4 writes into a new app (checked by reading the generator template
# in the fixture app). filter_parameters is a key filter, not a value filter: a secret pasted into a comment field
# called notes is not masked.
require "active_support"
require "active_support/parameter_filter"

GENERATED = %i[passw email secret token _key crypt salt certificate otp ssn cvv cvc]
filter = ActiveSupport::ParameterFilter.new(GENERATED)

payload = {
  "user" => {
    "email_address" => "asha@example.com",
    "password" => "the-password",            # fictional, matches passw
    "password_confirmation" => "the-password",
    "pan_card" => "ABCDE1234F",              # NOT masked: no key matches
    "address" => "12 Rajpur Road, Dehradun",
  },
  "api_token" => "the-token",                # fictional, matches token
  "notes" => "wrote the password down in a notebook", # NOT masked: filter_parameters reads KEYS, not values
  "amount" => 500,
}
puts "filter list: #{GENERATED.inspect}"
puts "filtered:    #{filter.filter(payload).inspect}"

filter list: [:passw, :email, :secret, :token, :_key, :crypt, :salt, :certificate, :otp, :ssn, :cvv, :cvc]
filtered:    {"user" => {"email_address" => "[FILTERED]", "password" => "[FILTERED]", "password_confirmation" => "[FILTERED]", "pan_card" => "ABCDE1234F", "address" => "12 Rajpur Road, Dehradun"}, "api_token" => "[FILTERED]", "notes" => "wrote the password down in a notebook", "amount" => 500}

The run shows two facts. The list is a substring match on keys, so password, password_confirmation, email_address and api_token all become [FILTERED]. And it is a key filter, not a value filter: a password written into a notes field reaches the log unchanged. Add any key your app writes that holds a secret, and keep secrets out of free-text fields.

Two production questions follow: rotating secret_key_base without logging everyone out, and encrypting a column you still need to query. Active Record encryption gives each column one of two shapes. A deterministic column stores the same ciphertext for the same value, so find_by can still find a row by it. A non-deterministic column, the default, stores a new ciphertext on every write. Before a push, a secret scanner checks pasted code or logs for keys and tokens, in the browser.

Rotate secret_key_base and encryption keys with no sign-out Pro: opens with a Pro, Premium or Ultimate pass

Encrypt columns you still need to find rows by Pro: opens with a Pro, Premium or Ultimate pass

Practise: read the ciphertext before writing more code

The questions replay the credentials layout and the filter run: which two files a deploy needs, which file production reads when there are two, and which keys the generated filter hides and which it lets through.

Interview questions

Warm-up: a Rails log shows password: "[FILTERED]" but also a notes field with the plain text wrote the password down. Why does the filter hide one and not the other?

Because filter_parameters matches keys, not values. The generated list holds key patterns such as :passw, which catches password, password_confirmation and any other key that contains those letters. notes matches no entry, so its whole value reaches the log, whatever it says. Add every key your app uses for a secret to the list, and keep secrets out of free-text fields: a filter that guessed at values would still miss a password that looks like an ordinary word.

Key takeaways

• Encrypted credentials and the credentials key are a pair: the encrypted YAML goes in git, and the key comes from RAILS_MASTER_KEY on a server and from the git-ignored key file on a developer laptop.
• A per-environment file such as config/credentials/production.yml.enc replaces the shared file when it exists, and bin/rails credentials:fetch prints one value for a deploy script.
• Every cookie key is derived from secret_key_base, so changing it signs every user out unless the old value stays registered as a rotation.
• filter_parameters masks values by key name, so a secret typed into a free-text field such as notes reaches the log.
• Active Record encryption stores a column either deterministically, so find_by still works on it, or with a new ciphertext on every write, the default.