feature #5109 Improved the explanation about the "secret" configuration parameter (javiereguiluz)

weaverryan · weaverryan · commit 387ebc0b84cb · 2015-04-27T07:49:43.000-07:00
This PR was merged into the 2.3 branch. Discussion ---------- Improved the explanation about the "secret" configuration parameter | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | - Commits ------- ac3a74d Minor rewording db5db0f Fixed a minor grammar issue 74841e6 Minor rewording 4bbd84a Fixed some typos b13250d Improved the explanation about the "secret" configuration parameter
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -60,10 +60,24 @@ secret
 
 **type**: ``string`` **required**
 
-This is a string that should be unique to your application. In practice,
-it's used for generating the CSRF tokens, but it could be used in any other
-context where having a unique string is useful. It becomes the service container
-parameter named ``kernel.secret``.
+This is a string that should be unique to your application and it's commonly used
+to add more entropy to security related operations. Its value should be a series of
+characters, numbers and symbols chosen randomly and the recommended length is
+around 32 characters.
+
+In practice, Symfony uses this value for generating the :ref:`CSRF tokens <forms-csrf>`,
+for encrypting the cookies used in the :doc:`remember me functionality </cookbook/security/remember_me>`
+and for creating signed URIs when using :ref:`ESI (Edge Side Includes) <edge-side-includes>` .
+
+This option becomes the service container parameter named ``kernel.secret``,
+which you can use whenever the application needs an immutable random string
+to add more entropy.
+
+As with any other security-related parameter, it is a good practice to change this
+value from time to time. However, keep in mind that changing this value will
+invalidate all signed URIs and Remember Me cookies. That's why, after changing
+this value, you should regenerate the application cache and log out all the
+application users.
 
 .. _configuration-framework-http_method_override:
 
