[ci skip] Prefer credentials to secrets in docs.

Removes most mentions of secrets.secret_key_base and explains
credentials instead.

Also removes some very stale upgrade notices about Rails 3/4.

3 files changed, 29 insertions, 48 deletions

diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index b3b5f19b61..2c3f74c3e1 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -397,34 +397,18 @@ You can also pass a `:domain` key and specify the domain name for the cookie:
 Rails.application.config.session_store :cookie_store, key: '_your_app_session', domain: ".example.com"
 ```
 
-Rails sets up (for the CookieStore) a secret key used for signing the session data. This can be changed in `config/secrets.yml`
+Rails sets up (for the CookieStore) a secret key used for signing the session data in `config/credentials.yml.enc`. This can be changed with `bin/rails credentials:edit`.
 
 ```ruby
-# Be sure to restart your server when you modify this file.
-
-# Your secret key is used for verifying the integrity of signed cookies.
-# If you change this key, all old signed cookies will become invalid!
-
-# Make sure the secret is at least 30 characters and all random,
-# no regular words or you'll be exposed to dictionary attacks.
-# You can use `rails secret` to generate a secure secret key.
-
-# Make sure the secrets in this file are kept private
-# if you're sharing your code publicly.
-
-development:
-  secret_key_base: a75d...
-
-test:
-  secret_key_base: 492f...
+# amazon:
+#  access_key_id: 123
+#  secret_access_key: 345
 
-# Do not keep production secrets in the repository,
-# instead read values from the environment.
-production:
-  secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>
+# Used as the base secret for all MessageVerifiers in Rails, including the one protecting cookies.
+secret_key_base: 492f...
 ```
 
-NOTE: Changing the secret when using the `CookieStore` will invalidate all existing sessions.
+NOTE: Changing the secret_key_base when using the `CookieStore` will invalidate all existing sessions.
 
 ### Accessing the Session
 
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index d4e1d7b5dd..1c720ad82f 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -138,7 +138,7 @@ defaults to `:debug` for all environments. The available log levels are: `:debug
 
 * `config.reload_classes_only_on_change` enables or disables reloading of classes only when tracked files change. By default tracks everything on autoload paths and is set to `true`. If `config.cache_classes` is `true`, this option is ignored.
 
-* `secrets.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. Applications get `secrets.secret_key_base` initialized to a random key present in `config/secrets.yml`.
+* `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. Applications get a random generated key in test and development environments, other environments should set one in `config/credentials.yml.enc`.
 
 * `config.public_file_server.enabled` configures Rails to serve static files from the public directory. This option defaults to `true`, but in the production environment it is set to `false` because the server software (e.g. NGINX or Apache) used to run the application should serve static files instead. If you are running or testing your app in production mode using WEBrick (it is not recommended to use WEBrick in production) set the option to `true.` Otherwise, you won't be able to use page caching and request for files that exist under the public directory.
 
diff --git a/guides/source/security.md b/guides/source/security.md
index 882daa9806..a74de22ac0 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -98,7 +98,7 @@ Rails 2 introduced a new default session storage, CookieStore. CookieStore saves
 In Rails 4, encrypted cookies through AES in CBC mode with HMAC using SHA1 for
 verification was introduced. This prevents the user from accessing and tampering
 the content of the cookie. Thus the session becomes a more secure place to store
-data. The encryption is performed using a server-side `secrets.secret_key_base`.
+data. The encryption is performed using a server-side `secret_key_base`.
 Two salts are used when deriving keys for encryption and verification. These
 salts are set via the `config.action_dispatch.encrypted_cookie_salt` and
 `config.action_dispatch.encrypted_signed_cookie_salt` configuration values.
@@ -111,18 +111,9 @@ Encrypted cookies are automatically upgraded if the
 
 _Do not use a trivial secret, i.e. a word from a dictionary, or one which is shorter than 30 characters! Instead use `rails secret` to generate secret keys!_
 
-Applications get `secrets.secret_key_base` initialized to a random key present in `config/secrets.yml`, e.g.:
+In test and development applications get a `secret_key_base` derived from the app name. Other environments must use a random key present in `config/credentials.yml.enc`, shown here in its decrypted state:
 
-    development:
-      secret_key_base: a75d...
-
-    test:
-      secret_key_base: 492f...
-
-    production:
-      secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>
-
-Older versions of Rails use CookieStore, which uses `secret_token` instead of `secret_key_base` that is used by EncryptedCookieStore. Read the upgrade documentation for more information.
+    secret_key_base: 492f...
 
 If you have received an application where the secret was exposed (e.g. an application whose source was shared), strongly consider changing the secret.
 
@@ -1032,27 +1023,33 @@ Environmental Security
 
 It is beyond the scope of this guide to inform you on how to secure your application code and environments. However, please secure your database configuration, e.g. `config/database.yml`, and your server-side secret, e.g. stored in `config/secrets.yml`. You may want to further restrict access, using environment-specific versions of these files and any others that may contain sensitive information.
 
-### Custom secrets
+### Custom credentials
+
+Rails generates a `config/credentials.yml.enc` to store third-party credentials
+within the repo. This is only viable because Rails encrypts the file with a master
+key that's generated into a version control ignored `config/master.key` — Rails
+will also look for that key in `ENV["RAILS_MASTER_KEY"]`. Rails also requires the
+the key to boot in production, so the credentials can be read.
+
+To edit stored credentials use `bin/rails credentials:edit`.
 
-Rails generates a `config/secrets.yml`. By default, this file contains the
-application's `secret_key_base`, but it could also be used to store other
-secrets such as access keys for external APIs.
+By default, this file contains the application's
+`secret_key_base`, but it could also be used to store other credentials such as
+access keys for external APIs.
 
-The secrets added to this file are accessible via `Rails.application.secrets`.
-For example, with the following `config/secrets.yml`:
+The credentials added to this file are accessible via `Rails.application.credentials`.
+For example, with the following decrypted `config/credentails.yml.enc`:
 
-    development:
-      secret_key_base: 3b7cd727ee24e8444053437c36cc66c3
-      some_api_key: SOMEKEY
+    secret_key_base: 3b7cd727ee24e8444053437c36cc66c3
+    some_api_key: SOMEKEY
 
-`Rails.application.secrets.some_api_key` returns `SOMEKEY` in the development
-environment.
+`Rails.application.credentails.some_api_key` returns `SOMEKEY` in any environment.
 
 If you want an exception to be raised when some key is blank, use the bang
 version:
 
 ```ruby
-Rails.application.secrets.some_api_key! # => raises KeyError: key not found: :some_api_key
+Rails.application.credentails.some_api_key! # => raises KeyError: key not found: :some_api_key
 ```
 
 Additional Resources