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.
Guide: Configuring Rails Applications > Section: 3.1 Rails General Configuration
config.credentials.content_path
configures lookup path for encrypted credentials.
- With the simultaneous support of
global encrypted credentials
(introduced in Rails 5.2) andmulti-environment encrypted credentials
(introduced in Rails 6), thecredentials
file that ends up being decrypted and loaded goes through some defaulting and fallback logic that is non-trivial. It may be worth mentioning thatcontent_path
fully overrides that logic.
- 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 fallbackconfig/credentials.yml.enc
). - Clarify possible confusion points: what happens when
content_path
is set andkey_path
is not? Is there any interaction between them?
config.credentials.key_path
configures lookup path for encryption key.
- Same as above.
- 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 overENV["RAILS_MASTER_KEY"]
and its fallback"config/#{Rails.env.downcase}.key"
). - Possibly mention any interactions that the
key_path
has withcontent_path
.
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...
- 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
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 toENV["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.
- 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
and10.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 for
ENV["RAILS_MASTER_KEY"]
first, and then falls back toconfig/master.key
. - Mention the overrides that can be done using
content_path
andkey_path
and link to the "Section: 3.1 Rails General Configuration" documentation.
- Mention that the feature looks for
- On section
10.1.2
:- Mention that the feature looks for
ENV["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 toglobal encrypted credentials
using the fileconfig/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 inconfig/credentials.yml.enc
. - Mention the overrides that can be done using
content_path
andkey_path
and link to the "Section: 3.1 Rails General Configuration" documentation.
- Mention that the feature looks for
- 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".