From 38308e6d1353eda587d676ac40ce489c638fb0c3 Mon Sep 17 00:00:00 2001 From: Kasper Timm Hansen Date: Sun, 24 Sep 2017 21:41:16 +0200 Subject: [ci skip] Attempt a new explanation for rotations. It's become clear to me that the use case is still a bit muddy and the upgrade path is going to be tough for people to figure out. This attempts at understanding it better through documentation, but still needs follow up work. [ Michael Coyne & Kasper Timm Hansen ] --- guides/source/configuring.md | 6 ++---- guides/source/security.md | 44 ++++++++++++++++---------------------------- 2 files changed, 18 insertions(+), 32 deletions(-) (limited to 'guides') diff --git a/guides/source/configuring.md b/guides/source/configuring.md index 86c8364d83..0f87d73d6e 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -493,10 +493,8 @@ Defaults to `'signed cookie'`. * `config.action_dispatch.signed_cookie_digest` sets the digest to be used for signed cookies. This defaults to `"SHA1"`. -* `config.action_dispatch.cookies_rotations` is set to an instance of - [RotationConfiguration](http://api.rubyonrails.org/classes/ActiveSupport/RotationConfiguration.html). - It provides an interface for rotating keys, salts, ciphers, and - digests for encrypted and signed cookies. +* `config.action_dispatch.cookies_rotations` allows rotating + secrets, ciphers, and digests for encrypted and signed cookies. * `config.action_dispatch.perform_deep_munge` configures whether `deep_munge` method should be performed on the parameters. See [Security Guide](security.html#unsafe-query-generation) diff --git a/guides/source/security.md b/guides/source/security.md index 994978b88b..9e1dc518d2 100644 --- a/guides/source/security.md +++ b/guides/source/security.md @@ -161,43 +161,31 @@ It is also useful to rotate this value for other more benign reasons, such as an employee leaving your organization or changing hosting environments. -Key rotations can be defined through -`config.action_dispatch.cookies_rotations` which provides an interface for -rotating signed and encrypted cookie keys, salts, digests, and ciphers. - -For example, suppose we want to rotate out an old `secret_key_base`, we -can define a signed and encrypted key rotation as follows: +For example to rotate out an old `secret_key_base`, we can define signed and +encrypted rotations as follows: ```ruby -config.action_dispatch.cookies_rotations.rotate :encrypted, - cipher: "aes-256-gcm", - secret: Rails.application.credentials.old_secret_key_base, - salt: config.action_dispatch.authenticated_encrypted_cookie_salt - -config.action_dispatch.cookies_rotations.rotate :signed, - digest: "SHA1", - secret: Rails.application.credentials.old_secret_key_base, - salt: config.action_dispatch.signed_cookie_salt +Rails.application.config.action_dispatch.cookies_rotations.tap do |cookies| + cookies.rotate :encrypted, secret: Rails.application.credentials.old_secret_key_base + cookies.rotate :signed, secret: Rails.application.credentials.old_secret_key_base +end ``` -Multiple rotations are possible by calling `rotate` multiple times. For -example, suppose we want to use SHA512 for signed cookies while rotating -out SHA256 and SHA1 digests using the same `secret_key_base`: +It's also possible to set up multiple rotations. For instance to use `SHA512` +for signed cookies while rotating out SHA256 and SHA1 digests, we'd do: ```ruby -config.action_dispatch.signed_cookie_digest = "SHA512" +Rails.application.config.action_dispatch.signed_cookie_digest = "SHA512" -config.action_dispatch.cookies_rotations.rotate :signed, - digest: "SHA256", - secret: Rails.application.credentials.secret_key_base, - salt: config.action_dispatch.signed_cookie_salt - -config.action_dispatch.cookies_rotations.rotate :signed, - digest: "SHA1", - secret: Rails.application.credentials.secret_key_base, - salt: config.action_dispatch.signed_cookie_salt +Rails.application.config.action_dispatch.cookies_rotations.tap do |cookies| + cookies.rotate :signed, digest: "SHA256" + cookies.rotate :signed, digest: "SHA1" +end ``` +While you can setup as many rotations as you'd like it's not common to have many +rotations going at any one time. + For more details on key rotation with encrypted and signed messages as well as the various options the `rotate` method accepts, please refer to the -- cgit v1.2.3