A break down of the documentation gaps that exist in Rails' 6.0.3.1 guides related to encrypted credentials.

Rails 6 Guides Encrypted Credentials Documentation Gaps.md

1. About

This work is related to my post about the status of encrypted credentials support in Rails 6 that is part of the "A May of WTFs" initiative.

In particular, it identifies the documentation gaps that exist in Rails' 6.0.3.1 guides related to encrypted credentials.

2. Documentation Gaps and Suggestions

Guide: Configuring Rails Applications > Section: 3.1 Rails General Configuration

config.credentials.content_path

config.credentials.content_path configures lookup path for encrypted credentials.

Gaps

• With the simultaneous support of global encrypted credentials (introduced in Rails 5.2) and multi-environment encrypted credentials (introduced in Rails 6), the credentials file that ends up being decrypted and loaded goes through some defaulting and fallback logic that is non-trivial. It may be worth mentioning that content_path fully overrides that logic.

Suggestions

• Add link to https://guides.rubyonrails.org/security.html#custom-credentials where users can learn more about how encrypted credentials work.
• Mention that content_path overrides the defaulting and fallback logic of finding the encrypted credentials file. (i.e. If set, it takes precedence over "config/credentials/#{Rails.env.downcase}.yml.enc" and its fallback config/credentials.yml.enc).
• Clarify possible confusion points: what happens when content_path is set and key_path is not? Is there any interaction between them?

config.credentials.key_path

config.credentials.key_path configures lookup path for encryption key.

Gaps

• Same as above.

Suggestions

• Add link to https://guides.rubyonrails.org/security.html#custom-credentials where users can learn more about how encrypted credentials work.
• Mention that key_path overrides the defaulting and fallback logic of finding the encryption key file. (i.e. If set, it takes precedence over ENV["RAILS_MASTER_KEY"] and its fallback "config/#{Rails.env.downcase}.key").
• Possibly mention any interactions that the key_path has with content_path.

secret_key_base

secret_key_base is used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering...

Suggestions

• Add link to https://guides.rubyonrails.org/security.html#session-storage where users can learn more about the role that secret_key_base plays in Session security.

Guide: Securing Rails Applications > Section: 10.1 Custom Credentials

Gaps

This is the only section on all the Rails Guides that touches on encrypted credentials. This are the most relevant documentation gaps:

• The section does not explain the problem the feature is solving (why are encrypted credentials important).
• The documentation only touches lightly on global encrypted credentials. Multi-environment encrypted credentials are not mentioned.
• The documentation suggests that config/master.key is looked for first, and then it defaults to ENV["RAILS_MASTER_KEY"], when the behaviour is the other way around.
• There is good documentation about this feature inside rails credentials:help that has not been surfaced to the Rails guides.

Suggestions

• Most of the suggestions below can be achieved by using what is already inside rails credentials:help.
• Rename the tilte of section 10.1 to Encrypted Credentials (or something similar). This is the name of the feature and is what people Google for.
• Use the body of section 10.1 to explain the motivation of this feature (i.e. the problem it solves).
• Remove the information on rails secret that is currently in the section. It is not relevant on this section and becomes a potential source of confusion.
• Add 2 sub-sections 10.1.1 Global Encrypted Credentials and 10.1.2 Multi-environment Encrypted Credentials and use them to explain each of the features separetely.
• On section 10.1.1:
  • Mention that the feature looks forENV["RAILS_MASTER_KEY"] first, and then falls back to config/master.key.
  • Mention the overrides that can be done using content_path and key_path and link to the "Section: 3.1 Rails General Configuration" documentation.
• On section 10.1.2:
  • Mention that the feature looks forENV["RAILS_MASTER_KEY"] first, and then for "config/credentials/#{Rails.env.downcase}.key".
  • Mention that if "config/credentials/#{Rails.env.downcase}.yml.enc" is not found, the feature fallsback to global encrypted credentials using the file config/credentials.yml.enc.
  • Be sure to mention that the feature loads one or the other. In other words, there is no "if a key is not found in config/credentials/staging.yml.enc then the key is looked for in config/credentials.yml.enc.
  • Mention the overrides that can be done using content_path and key_path and link to the "Section: 3.1 Rails General Configuration" documentation.
• Good citizen: Add a warning along the lines of "if you are having trouble with changes in your credentials not being loaded on local development, try re-starting spring".