Merge branch '2.3' into 2.5

* 2.3:
  [#4606] Getting my XML (and PHP) on in the new security chapter
  [#4606] Tweaks thanks entirely to stof
  Changing to _ for consistency
  [#4606] Updating thanks to comments from everyone!
  Completely re-reading the security book
  Misc changes
  [Cookbook] Fix XML example of RTE

Conflicts:
	book/security.rst
	cookbook/map.rst.inc
	cookbook/security/index.rst

Author: weaverryan

best_practices/controllers.rst

@@ -110,8 +110,9 @@ for the homepage of our app:
          */
         public function indexAction()
         {
-            $em = $this->getDoctrine()->getManager();
-            $posts = $em->getRepository('App:Post')->findLatest();
+            $posts = $this->getDoctrine()
+                ->getRepository('AppBundle:Post')
+                ->findLatest();
 
             return $this->render('default/index.html.twig', array(
                 'posts' => $posts
@@ -136,6 +137,7 @@ For example:
 
 .. code-block:: php
 
+    use AppBundle\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     
     /**
@@ -146,7 +148,7 @@ For example:
         $deleteForm = $this->createDeleteForm($post);
 
         return $this->render('admin/post/show.html.twig', array(
-            'post'      => $post,
+            'post'        => $post,
             'delete_form' => $deleteForm->createView(),
         ));
     }
@@ -188,8 +190,10 @@ flexible:
 
 .. code-block:: php
 
+    use AppBundle\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;
+    use Symfony\Component\HttpFoundation\Request;
 
     /**
      * @Route("/comment/{postSlug}/new", name = "comment_new")

book/security.rst

@@ -125,6 +125,7 @@
   * :doc:`/components/security/firewall`
   * :doc:`/components/security/authentication`
   * :doc:`/components/security/authorization`
+  * :doc:`/components/security/secure_tools`
 
 * **Serializer**
 

components/map.rst.inc

@@ -8,3 +8,4 @@ Security
     firewall
     authentication
     authorization
+    secure_tools

components/security/index.rst

@@ -0,0 +1,60 @@
+Securely Comparing Strings and Generating Random Numbers
+========================================================
+
+The Symfony Security component comes with a collection of nice utilities
+related to security. These utilities are used by Symfony, but you should
+also use them if you want to solve the problem they address.
+
+Comparing Strings
+~~~~~~~~~~~~~~~~~
+
+The time it takes to compare two strings depends on their differences. This
+can be used by an attacker when the two strings represent a password for
+instance; it is known as a `Timing attack`_.
+
+Internally, when comparing two passwords, Symfony uses a constant-time
+algorithm; you can use the same strategy in your own code thanks to the
+:class:`Symfony\\Component\\Security\\Core\\Util\\StringUtils` class::
+
+    use Symfony\Component\Security\Core\Util\StringUtils;
+
+    // is some known string (e.g. password) equal to some user input?
+    $bool = StringUtils::equals($knownString, $userInput);
+
+.. caution::
+
+    To avoid timing attacks, the known string must be the first argument
+    and the user-entered string the second.
+
+Generating a Secure random Number
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Whenever you need to generate a secure random number, you are highly
+encouraged to use the Symfony
+:class:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom` class::
+
+    use Symfony\Component\Security\Core\Util\SecureRandom;
+
+    $generator = new SecureRandom();
+    $random = $generator->nextBytes(10);
+
+The
+:method:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom::nextBytes`
+method returns a random string composed of the number of characters passed as
+an argument (10 in the above example).
+
+The SecureRandom class works better when OpenSSL is installed. But when it's
+not available, it falls back to an internal algorithm, which needs a seed file
+to work correctly. Just pass a file name to enable it::
+
+    use Symfony\Component\Security\Core\Util\SecureRandom;
+
+    $generator = new SecureRandom('/some/path/to/store/the/seed.txt');
+    $random = $generator->nextBytes(10);
+
+.. note::
+
+    If you're using the Symfony Framework, you can access a secure random
+    instance directly from the container: its name is ``security.secure_random``.
+
+.. _`Timing attack`: http://en.wikipedia.org/wiki/Timing_attack

components/security/secure_tools.rst

@@ -132,7 +132,7 @@ about the replacement:
             <doctrine:config>
                 <doctrine:orm>
                     <!-- ... -->
-                    <doctrine:resolve-target-entity interface="Acme\InvoiceBundle\Model\InvoiceSubjectInterface">Acme\AppBundle\Entity\Customer</resolve-target-entity>
+                    <doctrine:resolve-target-entity interface="Acme\InvoiceBundle\Model\InvoiceSubjectInterface">Acme\AppBundle\Entity\Customer</doctrine:resolve-target-entity>
                 </doctrine:orm>
             </doctrine:config>
         </container>

cookbook/doctrine/resolve_target_entity.rst

@@ -16,9 +16,99 @@ ways:
 
 * :ref:`Configuring services <book-services-expressions>`;
 * :ref:`Route matching conditions <book-routing-conditions>`;
-* :ref:`Checking security <book-security-expressions>` and
+* :ref:`Checking security <book-security-expressions>` (explained below) and
   :ref:`access controls with allow_if <book-security-allow-if>`;
 * :doc:`Validation </reference/constraints/Expression>`.
 
 For more information about how to create and work with expressions, see
 :doc:`/components/expression_language/syntax`.
+
+.. _book-security-expressions:
+
+Security: Complex Access Controls with Expressions
+--------------------------------------------------
+
+.. versionadded:: 2.4
+    The expression functionality was introduced in Symfony 2.4.
+
+In addition to a role like ``ROLE_ADMIN``, the ``isGranted`` method also
+accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
+
+    use Symfony\Component\ExpressionLanguage\Expression;
+    // ...
+
+    public function indexAction()
+    {
+        if (!$this->get('security.context')->isGranted(new Expression(
+            '"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())'
+        ))) {
+            throw $this->createAccessDeniedException();
+        }
+
+        // ...
+    }
+
+In this example, if the current user has ``ROLE_ADMIN`` or if the current
+user object's ``isSuperAdmin()`` method returns ``true``, then access will
+be granted (note: your User object may not have an ``isSuperAdmin`` method,
+that method is invented for this example).
+
+This uses an expression and you can learn more about the expression language
+syntax, see :doc:`/components/expression_language/syntax`.
+
+.. _book-security-expression-variables:
+
+Inside the expression, you have access to a number of variables:
+
+``user``
+    The user object (or the string ``anon`` if you're not authenticated).
+``roles``
+    The array of roles the user has, including from the
+    :ref:`role hierarchy <book-security-role-hierarchy>` but not including the
+    ``IS_AUTHENTICATED_*`` attributes (see the functions below).
+``object``
+     The object (if any) that's passed as the second argument to ``isGranted``.
+``token``
+    The token object.
+``trust_resolver``
+    The :class:`Symfony\\Component\\Security\\Core\\Authentication\\AuthenticationTrustResolverInterface`,
+    object: you'll probably use the ``is_*`` functions below instead.
+
+Additionally, you have access to a number of functions inside the expression:
+
+``is_authenticated``
+    Returns ``true`` if the user is authenticated via "remember-me" or authenticated
+    "fully" - i.e. returns true if the user is "logged in".
+``is_anonymous``
+    Equal to using ``IS_AUTHENTICATED_ANONYMOUSLY`` with the ``isGranted`` function.
+``is_remember_me``
+    Similar, but not equal to ``IS_AUTHENTICATED_REMEMBERED``, see below.
+``is_fully_authenticated``
+    Similar, but not equal to ``IS_AUTHENTICATED_FULLY``, see below.
+``has_role``
+    Checks to see if the user has the given role - equivalent to an expression like
+    ``'ROLE_ADMIN' in roles``.
+
+.. sidebar:: ``is_remember_me`` is different than checking ``IS_AUTHENTICATED_REMEMBERED``
+
+    The ``is_remember_me`` and ``is_authenticated_fully`` functions are *similar*
+    to using ``IS_AUTHENTICATED_REMEMBERED`` and ``IS_AUTHENTICATED_FULLY``
+    with the ``isGranted`` function - but they are **not** the same. The
+    following shows the difference::
+
+        use Symfony\Component\ExpressionLanguage\Expression;
+        // ...
+
+        $sc = $this->get('security.context');
+        $access1 = $sc->isGranted('IS_AUTHENTICATED_REMEMBERED');
+
+        $access2 = $sc->isGranted(new Expression(
+            'is_remember_me() or is_fully_authenticated()'
+        ));
+
+    Here, ``$access1`` and ``$access2`` will be the same value. Unlike the
+    behavior of ``IS_AUTHENTICATED_REMEMBERED`` and ``IS_AUTHENTICATED_FULLY``,
+    the ``is_remember_me`` function *only* returns true if the user is authenticated
+    via a remember-me cookie and ``is_fully_authenticated`` *only* returns
+    true if the user has actually logged in during this session (i.e. is
+    full-fledged).

cookbook/expression/expressions.rst

@@ -144,6 +144,7 @@
 
 * :doc:`/cookbook/security/index`
 
+  * :doc:`/cookbook/security/form_login_setup`
   * :doc:`/cookbook/security/entity_provider`
   * :doc:`/cookbook/security/remember_me`
   * :doc:`/cookbook/security/impersonating_user`
@@ -164,6 +165,8 @@
   * :doc:`/cookbook/security/target_path`
   * :doc:`/cookbook/security/csrf_in_login_form`
   * :doc:`/cookbook/security/named_encoders`
+  * :doc:`/cookbook/security/access_control`
+  * :doc:`/cookbook/security/multiple_user_providers`
 
 * **Serializer**