Apr 6, 2019 · Apr 5, 2019
diff --git a/reference/constraints.rst b/reference/constraints.rst
   constraints/All
   constraints/UserPassword
   constraints/Valid
   constraints/NotCompromisedPassword

 The Validator is designed to validate objects against *constraints*.
 In real life, a constraint could be: "The cake must not be burned". In
diff --git a/reference/constraints/NotPwned.rst b/reference/constraints/NotPwned.rst
 NotCompromisedPassword
 ======================

 .. versionadded:: 4.3

    The ``NotCompromisedPassword`` constraint was introduced in Symfony 4.3.

 Validates that the given password has not been compromised by checking that is
 not included in any of the public data breaches tracked by `haveibeenpwned.com`_.

 ==========  ===================================================================
 Applies to  :ref:`property or method <validation-property-target>`
 Options     - `groups`_
            - `message`_
            - `payload`_
            - `skipOnError`_
            - `threshold`_
 Class       :class:`Symfony\\Component\\Validator\\Constraints\\NotCompromisedPassword`
 Validator   :class:`Symfony\\Component\\Validator\\Constraints\\NotCompromisedPasswordValidator`
 ==========  ===================================================================

 Basic Usage
 -----------

 The following constraint ensures that the ``rawPassword`` property of the
 ``User`` class doesn't store a compromised password:

 .. configuration-block::

    .. code-block:: php-annotations

        // src/Entity/User.php
        namespace App\Entity;

        use Symfony\Component\Validator\Constraints as Assert;

        class User
        {
            // ...

            /**
             * @Assert\NotCompromisedPassword
             */
            protected $rawPassword;
        }

    .. code-block:: yaml

        # config/validator/validation.yaml
        App\Entity\User:
            properties:
                rawPassword:
                    - NotCompromisedPassword

    .. code-block:: xml

        <!-- config/validator/validation.xml -->
        <?xml version="1.0" encoding="UTF-8" ?>
        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

            <class name="App\Entity\User">
                <property name="rawPassword">
                    <constraint name="NotCompromisedPassword"></constraint>
                </property>
            </class>
        </constraint-mapping>

    .. code-block:: php

        // src/Entity/User.php
        namespace App\Entity;

        use Symfony\Component\Validator\Mapping\ClassMetadata;
        use Symfony\Component\Validator\Constraints as Assert;

        class User
        {
            public static function loadValidatorMetadata(ClassMetadata $metadata)
            {
                $metadata->addPropertyConstraint('rawPassword', new Assert\NotCompromisedPassword());
            }
        }

 In order to make the password validation, this constraint doesn't send the raw
 password value to the ``haveibeenpwned.com`` API. Instead, it follows a secure
 process known as `k-anonimity password validation`_.

 In practice, the raw password is hashed using SHA-1 and only the first bytes of
 the hash are sent. Then, the ``haveibeenpwned.com`` API compares those bytes
 with the SHA-1 hashes of all leaked passwords and returns the list of hashes
 that start with those same bytes. That's how the constraint can check if the
 password has been compromised without fully disclosing it.

 For example, if the password is ``test``, the entire SHA-1 hash is
 ``a94a8fe5ccb19ba61c4c0873d391e987982fbbd3`` but the validator only sends
 ``a94a8`` to the ``haveibeenpwned.com`` API.

 Available Options
 -----------------

 .. include:: /reference/constraints/_groups-option.rst.inc

 message
 ~~~~~~~

 **type**: ``string`` **default**: ``This password has been leaked in a data breach, it must not be used. Please use another password.``

 The default message supplied when the password has been compromised.

 .. include:: /reference/constraints/_payload-option.rst.inc

 skipOnError
 ~~~~~~~~~~~

 **type**: ``boolean`` **default**: ``false``

 When the HTTP request made to the ``haveibeenpwned.com`` API fails for any
 reason, an exception is thrown (no validation error is displayed). Set this
 option to ``true`` to not throw the exception and consider the password valid.

 threshold
 ~~~~~~~~~

 **type**: ``integer`` **default**: ``1``

 This value defines the number of times a password should have been leaked
 publicly to consider it compromised. Think carefully before setting this option
 to a higher value because it could decrease the security of your application.

 .. _`haveibeenpwned.com`: https://haveibeenpwned.com/
 .. _`k-anonimity password validation`: https://blog.cloudflare.com/validating-leaked-passwords-with-k-anonymity/
diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc
 * :doc:`Collection </reference/constraints/Collection>`
 * :doc:`Count </reference/constraints/Count>`
 * :doc:`UniqueEntity </reference/constraints/UniqueEntity>`
 * :doc:`NotCompromisedPassword </reference/constraints/NotCompromisedPassword>`
Original file line number	Diff line number	Diff line change
Expand Up		@@ -66,6 +66,7 @@ Validation Constraints Reference
		constraints/All
		constraints/UserPassword
		constraints/Valid
		constraints/NotCompromisedPassword

		The Validator is designed to validate objects against constraints.
		In real life, a constraint could be: "The cake must not be burned". In
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,133 @@
		NotCompromisedPassword
		======================

		.. versionadded:: 4.3

		The ``NotCompromisedPassword`` constraint was introduced in Symfony 4.3.

		Validates that the given password has not been compromised by checking that is
		not included in any of the public data breaches tracked by `haveibeenpwned.com`_.

		========== ===================================================================
		Applies to :ref:`property or method <validation-property-target>`
		Options - `groups`_
		- `message`_
		- `payload`_
		- `skipOnError`_
		- `threshold`_
		Class :class:`Symfony\\Component\\Validator\\Constraints\\NotCompromisedPassword`
		Validator :class:`Symfony\\Component\\Validator\\Constraints\\NotCompromisedPasswordValidator`
		========== ===================================================================
wouterj marked this conversation as resolved. Show resolvedHide resolved

		Basic Usage
		-----------

		The following constraint ensures that the ``rawPassword`` property of the
		``User`` class doesn't store a compromised password:

		.. configuration-block::

		.. code-block:: php-annotations

		// src/Entity/User.php
		namespace App\Entity;

		use Symfony\Component\Validator\Constraints as Assert;

		class User
		{
		// ...

		/**
		* @Assert\NotCompromisedPassword
		*/
		protected $rawPassword;
		}

		.. code-block:: yaml

		# config/validator/validation.yaml
		App\Entity\User:
		properties:
		rawPassword:
		- NotCompromisedPassword

		.. code-block:: xml

		<!-- config/validator/validation.xml -->
		<?xml version="1.0" encoding="UTF-8" ?>
		<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

		<class name="App\Entity\User">
		<property name="rawPassword">
		<constraint name="NotCompromisedPassword"></constraint>
		</property>
		</class>
		</constraint-mapping>

		.. code-block:: php

		// src/Entity/User.php
		namespace App\Entity;

		use Symfony\Component\Validator\Mapping\ClassMetadata;
		use Symfony\Component\Validator\Constraints as Assert;

		class User
		{
		public static function loadValidatorMetadata(ClassMetadata $metadata)
		{
		$metadata->addPropertyConstraint('rawPassword', new Assert\NotCompromisedPassword());
		}
		}

		In order to make the password validation, this constraint doesn't send the raw
		password value to the ``haveibeenpwned.com`` API. Instead, it follows a secure
		process known as `k-anonimity password validation`_.

		In practice, the raw password is hashed using SHA-1 and only the first bytes of
		the hash are sent. Then, the ``haveibeenpwned.com`` API compares those bytes
		with the SHA-1 hashes of all leaked passwords and returns the list of hashes
		that start with those same bytes. That's how the constraint can check if the
		password has been compromised without fully disclosing it.

		For example, if the password is ``test``, the entire SHA-1 hash is
		``a94a8fe5ccb19ba61c4c0873d391e987982fbbd3`` but the validator only sends
		``a94a8`` to the ``haveibeenpwned.com`` API.

		Available Options
		-----------------

		.. include:: /reference/constraints/_groups-option.rst.inc

		message
		~~~~~~~

		type: ``string`` default: ``This password has been leaked in a data breach, it must not be used. Please use another password.``

		The default message supplied when the password has been compromised.

		.. include:: /reference/constraints/_payload-option.rst.inc

		skipOnError
		~~~~~~~~~~~

		type: ``boolean`` default: ``false``

		When the HTTP request made to the ``haveibeenpwned.com`` API fails for any
		reason, an exception is thrown (no validation error is displayed). Set this
		option to ``true`` to not throw the exception and consider the password valid.

		threshold
		~~~~~~~~~

		type: ``integer`` default: ``1``

		This value defines the number of times a password should have been leaked
		publicly to consider it compromised. Think carefully before setting this option
		to a higher value because it could decrease the security of your application.

		.. _`haveibeenpwned.com`: https://haveibeenpwned.com/
		.. _`k-anonimity password validation`: https://blog.cloudflare.com/validating-leaked-passwords-with-k-anonymity/
Original file line number	Diff line number	Diff line change
Expand Up		@@ -88,3 +88,4 @@ Other Constraints
		* :doc:`Collection </reference/constraints/Collection>`
		* :doc:`Count </reference/constraints/Count>`
		* :doc:`UniqueEntity </reference/constraints/UniqueEntity>`
		* :doc:`NotCompromisedPassword </reference/constraints/NotCompromisedPassword>`