NotCompromisedPassword

編輯此頁面

驗證給定的密碼是否已洩露，方法是檢查它是否未包含在 haveibeenpwned.com 追蹤的任何公開資料外洩事件中。

適用於	屬性或方法
類別	NotCompromisedPassword
驗證器	NotCompromisedPasswordValidator

基本用法

以下約束確保 User 類別的 rawPassword 屬性不會儲存洩露的密碼

        1
2
3
4
5
6
7
8
9
10
        // src/Entity/User.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class User
{
    #[Assert\NotCompromisedPassword]
    protected string $rawPassword;
}
    

        1
2
3
4
5
        # config/validator/validation.yaml
App\Entity\User:
    properties:
        rawPassword:
            - NotCompromisedPassword
    

        1
2
3
4
5
6
7
8
9
10
11
12
        <!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="https://symfony.dev.org.tw/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://symfony.dev.org.tw/schema/dic/constraint-mapping https://symfony.dev.org.tw/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>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // src/Entity/User.php
namespace App\Entity;

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

class User
{
    // ...

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

為了進行密碼驗證，此約束不會將原始密碼值發送到 haveibeenpwned.com API。相反地，它遵循稱為 k-匿名密碼驗證的安全流程。

實際上，原始密碼會使用 SHA-1 雜湊，且僅發送雜湊的前幾個位元組。然後，haveibeenpwned.com API 會將這些位元組與所有洩露密碼的 SHA-1 雜湊進行比較，並傳回以相同位元組開頭的雜湊列表。這就是約束如何檢查密碼是否已洩露，而無需完全洩露它。

例如，如果密碼是 test，則完整的 SHA-1 雜湊是 a94a8fe5ccb19ba61c4c0873d391e987982fbbd3，但驗證器僅將 a94a8 發送到 haveibeenpwned.com API。

參見

在 Symfony 應用程式中使用此約束時，請定義 not_compromised_password 選項，以避免在 dev 和 test 環境中發出 HTTP 請求。

可用選項

`groups`

類型：array | string 預設值：null

它定義此約束的驗證群組。閱讀更多關於驗證群組的資訊。

`message`

類型：string 預設值：此密碼已在資料外洩事件中洩露，不得使用。請使用另一個密碼。

當密碼已洩露時提供的預設訊息。

`payload`

類型：mixed 預設值：null

此選項可用於將任意特定領域的資料附加到約束。Validator 組件不使用設定的酬載，但其處理完全取決於您。

例如，您可能想要使用多個錯誤級別，以便根據錯誤的嚴重性，在前端以不同的方式呈現失敗的約束。

`skipOnError`

類型：boolean 預設值：false

當向 haveibeenpwned.com API 發出的 HTTP 請求因任何原因失敗時，會擲回例外狀況（不會顯示驗證錯誤）。將此選項設定為 true 以避免擲回例外狀況並將密碼視為有效。

`threshold`

類型：integer 預設值：1

此值定義密碼應公開洩露多少次才被視為已洩露。在將此選項設定為較高值之前請仔細考慮，因為這可能會降低應用程式的安全性。

本作品，包括程式碼範例，均根據 Creative Commons BY-SA 3.0 授權條款授權。

版本