Class yii\base\Security

继承yii\base\Security » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/base/Security.php

Security 提供了一组方法来处理与安全性相关的常见任务.

特别是, 安全性(Security)支持以下功能:

Note: 该类需要使用 PHP 'OpenSSL'扩展才能在 Windows 上生成随机密钥/字符串, 并在所有平台上的加密/解密. 为了获取最高的安全级别, 建议使用 PHP 版本 >= 5.5.0.

有关 Security 的更多详细信息和使用信息, 请参阅 权威指南 - 安全 - 概述(Overview).

公共属性

隐藏继承的属性

属性类型描述定义在
$allowedCiphers array[] 每个支持的 OpenSSL 密码的块大小和密钥大小表的映射. yii\base\Security
$authKeyInfo string 消息身份认证密钥推导的 HKDF 信息值. yii\base\Security
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$cipher string 用于加密和解密的密码. yii\base\Security
$derivationIterations integer 推导迭代计数. yii\base\Security
$kdfHash string 用于密钥推导的哈希算法. yii\base\Security
$macHash string 消息认证的哈希算法. yii\base\Security
$passwordHashCost integer 用于密码哈希的默认成本. yii\base\Security
$passwordHashStrategy string 策略, 它应该用于生成密码哈希. yii\base\Security

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
compareString() 使用定时攻击防御方法执行字符串比较. yii\base\Security
decryptByKey() 验证并解密用 encryptByKey() 加密的数据. yii\base\Security
decryptByPassword() 验证并解密用 encryptByPassword() 加密的数据. yii\base\Security
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
encryptByKey() 使用加密密钥加密数据. yii\base\Security
encryptByPassword() 使用密码加密数据. yii\base\Security
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
generatePasswordHash() 从密码和随机盐生成一个安全的哈希. yii\base\Security
generateRandomKey() 生成指定数量的随机字节. yii\base\Security
generateRandomString() 生成一个指定长度的随机字符串. yii\base\Security
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
hashData() 使用密钥散列值加数据前缀, 以便稍后可以检测到数据是否被篡改. yii\base\Security
hkdf() 使用标准的 HKDF 算法从给定的输入键中导出一个键. yii\base\Security
init() 初始化对象. yii\base\BaseObject
maskToken() 掩盖令牌不可压缩的标记. yii\base\Security
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
pbkdf2() 使用标准的 PBKDF2 算法从给定的密码导出一个密钥. yii\base\Security
trigger() 触发事件. yii\base\Component
unmaskToken() 取消屏蔽之前由maskToken屏蔽的标记(token). yii\base\Security
validateData() 验证给定数据是否被篡改. yii\base\Security
validatePassword() 根据散列验证密码. yii\base\Security

受保护的方法

隐藏继承的方法

方法描述定义在
decrypt() 解密数据. yii\base\Security
encrypt() 加密数据. yii\base\Security
generateSalt() 生成一个可用于生成密码哈希的盐. yii\base\Security
shouldUseLibreSSL() yii\base\Security

属性详情

$allowedCiphers public 属性

每个支持的 OpenSSL 密码的块大小和密钥大小表的映射.

在每个元素中, 密钥都是 OpenSSL 支持的密码之一(@see openssl_get_cipher_methods()). 该值是一个由两个整数组成的数组, 第一个是密码的块大小(以字节为单位), 第二个是密钥大小(以字节为单位).

Warning: 我们推荐的所有 OpenSSL 密码都是默认值, 即 CBC 模式下的 AES.

Note: Yii 的加密协议对密码秘钥, HMAC 签名秘钥和秘钥推导盐使用相同的大小.

public array[] $allowedCiphers = ['AES-128-CBC' => [1616], 'AES-192-CBC' => [1624], 'AES-256-CBC' => [1632]]
$authKeyInfo public 属性

消息身份认证密钥推导的 HKDF 信息值.

参见 hkdf().

public string $authKeyInfo 'AuthorizationKey'
$cipher public 属性

用于加密和解密的密码.

public string $cipher 'AES-128-CBC'
$derivationIterations public 属性

推导迭代计数. 设置的尽可能高以阻止字典密码攻击.

$kdfHash public 属性

用于密钥推导的哈希算法. 推荐: sha256, sha384 或 sha512.

参见 hash_algos().

public string $kdfHash 'sha256'
$macHash public 属性

消息认证的哈希算法. 推荐: sha256, sha384 或 sha512.

参见 hash_algos().

public string $macHash 'sha256'
$passwordHashCost public 属性 (可用自版本: 2.0.6)

用于密码哈希的默认成本. 允许的值在431之间.

参见 generatePasswordHash().

$passwordHashStrategy public 属性
弃用 自版本 2.0.7, generatePasswordHash() 忽略 $passwordHashStrategy, 并在可用时使用password_hash(), 否则使用crypt().

策略, 它应该用于生成密码哈希. 可用策略:

  • password_hash - 将 PHP password_hash()函数与 PASSWORD_DEFAULT 算法结合使用. 建议使用此选项, 但它需要PHP版本 >= 5.5.0.
  • crypt - 使用 PHP crypt() 函数.

方法详情

compareString() public 方法

使用定时攻击防御方法执行字符串比较.

参见 http://codereview.stackexchange.com/questions/13512.

public boolean compareString ( $expected, $actual )
$expected string

要比较的字符串.

$actual string

用户提供的字符串.

return boolean

字符串是否相等.

decrypt() protected 方法

解密数据.

参见 encrypt().

protected boolean|string decrypt ( $data, $passwordBased, $secret, $info )
$data string

要解密的加密数据.

$passwordBased boolean

设置为true以使用基于密码的密钥派生.

$secret string

解密密码或密钥.

$info string|null

上下文/应用程序特定信息.

return boolean|string

解密的数据, 或认证失败时为false.

throws yii\base\InvalidConfigException

OpenSSL 未加载时.

throws yii\base\Exception

OpenSSL 错误时.

decryptByKey() public 方法

验证并解密用 encryptByKey() 加密的数据.

参见 encryptByKey().

public boolean|string decryptByKey ( $data, $inputKey, $info null )
$data string

要解密的加密数据.

$inputKey string

用于加密和认证的输入.

$info string

可选的上下文和特定于应用程序的信息, 请参阅 hkdf().

return boolean|string

解密的数据, 或认证失败时为false.

decryptByPassword() public 方法

验证并解密用 encryptByPassword() 加密的数据.

参见 encryptByPassword().

public boolean|string decryptByPassword ( $data, $password )
$data string

要解密的加密数据.

$password string

用于解密的密码.

return boolean|string

解密的数据, 或认证失败时为false.

encrypt() protected 方法

加密数据.

参见 decrypt().

protected string encrypt ( $data, $passwordBased, $secret, $info )
$data string

要加密的数据.

$passwordBased boolean

设置为true以使用基于密码的密钥派生.

$secret string

加密密码或密钥.

$info string|null

上下文/应用程序特定信息, 例如: 一个用户ID. 有关更多详细信息, 请参阅 RFC 5869 Section 3.2.

return string

加密的数据.

throws yii\base\InvalidConfigException

OpenSSL 未加载时.

throws yii\base\Exception

OpenSSL 错误时.

encryptByKey() public 方法

使用加密密钥加密数据.

使用 HKDF 和随机盐从输入密钥中导出用于加密和认证的密钥, 相对于 encryptByPassword() 非常快. 输入密钥必须正确随机 -- 使用 generateRandomKey() 来生成密钥. 加密数据包括密钥消息认证码(MAC), 因此不需要散列输入或输出数据.

参见:

public string encryptByKey ( $data, $inputKey, $info null )
$data string

要加密的数据.

$inputKey string

用于加密和认证的输入.

$info string

可选的上下文和特定于应用程序的信息, 请参阅 hkdf().

return string

加密数据作为字节字符串.

encryptByPassword() public 方法

使用密码加密数据.

使用 PBKDF2 和随机盐从密码中导出用于加密和认证的密钥, 该方法故意缓慢以避免字典攻击. 使用 encryptByKey() 使用加密密钥而不是密码快速加密. 密钥导出时间由 $derivationIterations 确定, 应该尽可能高. 加密数据包括密钥消息认证码(MAC), 因此不需要散列输入或输出数据.

Note: 尽可能避免使用密码进行加密. 没有任何东西可以防止质量差或密码受损.

参见:

public string encryptByPassword ( $data, $password )
$data string

要加密的数据.

$password string

用于加密的密码.

return string

加密数据作为字节字符串.

generatePasswordHash() public 方法

从密码和随机盐生成一个安全的哈希.

生成的散列可以存储在数据库中. 稍后当需要验证密码时, 可以获取散列并将其传递给 validatePassword(). 例如:

// 生成散列(通常在用户注册期间或密码更改时完成)
$hash = Yii::$app->getSecurity()->generatePasswordHash($password);
// ...在数据库中保存 $hash...

// 在登录期间, 使用从数据库中获取的 $hash 验证输入的密码是否正确
if (Yii::$app->getSecurity()->validatePassword($password, $hash)) {
    // 密码正确
} else {
    // 密码错误
}

参见 validatePassword().

public string generatePasswordHash ( $password, $cost null )
$password string

被哈希的密码.

$cost integer

Blowfish 散列算法使用的成本参数. 成本值越高, 生成散列所需的时间越长, 并且验证密码的时间越长. 更高的成本因此减缓了暴力攻击. 为了最好地防范暴力攻击, 请将其设置为生产服务器可承受的最高值. 计算每个增量的哈希加倍所花费的时间减去 $cost 之一.

return string

密码哈希字符串. 当 $passwordHashStrategy 设置为'crypt'时, 总是输出60个 ASCII 字符; 当设置为'password_hash'时, 输出长度在未来版本的 PHP 中可能会增加(https://secure.php.net/manual/en/function.password-hash.php).

throws yii\base\Exception

错误的密码参数或成本参数.

generateRandomKey() public 方法

生成指定数量的随机字节.

Note: 输出可能不是 ASCII.

参见 generateRandomString() 如果你需要一个字符串.

public string generateRandomKey ( $length 32 )
$length integer

要生成的字节数.

return string

生成的随机字节.

throws yii\base\InvalidArgumentException

如果指定了错误的长度.

throws yii\base\Exception

失败.

generateRandomString() public 方法

生成一个指定长度的随机字符串.

生成的字符串与[A-Za-z0-9_-]+匹配, 并且对 URL 编码是透明的.

public string generateRandomString ( $length 32 )
$length integer

秘钥的字符长度.

return string

生成的随机密钥.

throws yii\base\Exception

失败.

generateSalt() protected 方法

生成一个可用于生成密码哈希的盐.

对于 Blowfish 哈希算法, PHP crypt() 内置函数需要特定格式的 salt 字符串: "$2a$", "$2x$" 或 "$2y$", 两位数字的成本参数"$"以及字母表"./0-9A-Za-z"中的22个字符.0

protected string generateSalt ( $cost 13 )
$cost integer

成本参数.

return string

随机盐值.

throws yii\base\InvalidArgumentException

如果成本参数超出了431的范围.

hashData() public 方法

使用密钥散列值加数据前缀, 以便稍后可以检测到数据是否被篡改.

这些方法执行任务时, 不需要散列 encryptByKey()encryptByPassword() 的输入或输出.

参见:

public string hashData ( $data, $key, $rawHash false )
$data string

要保护的数据.

$key string

用于生成散列的密钥. 应该是一个安全的密钥.

$rawHash boolean

生成的哈希值是否为原始二进制格式. 如果为false, 则会生成小写十六进制数字.

return string

以键控哈希为前缀的数据.

throws yii\base\InvalidConfigException

当 HMAC 生成失败时.

hkdf() public 方法

使用标准的 HKDF 算法从给定的输入键中导出一个键.

实现 RFC 5869 中规定的 HKDF. 建议使用 SHA-2 哈希算法之一: sha224, sha256, sha384 或 sha512.

public string hkdf ( $algo, $inputKey, $salt null, $info null, $length 0 )
$algo string

hash_hmac()支持的散列算法, eg. 'SHA-256'.

$inputKey string

源密钥.

$salt string

随机盐.

$info string

可选信息将派生的密钥材料绑定到应用程序和特定于上下文的信息, 例如, 用户ID或 API 版本, 请参阅 RFC 5869.

$length integer

输出密钥的字节长度. 如果为0, 则输出密钥是哈希算法输出的长度.

return string

派生的密钥.

throws yii\base\InvalidArgumentException

当 HMAC 生成失败时.

maskToken() public 方法 (可用自版本: 2.0.12)

掩盖令牌不可压缩的标记.

将随机掩码应用于令牌并将用于结果的掩码预设为字符串始终唯一. 用于通过随机化令牌在每个请求上的输出方式来减轻 BREACH 攻击.

public string maskToken ( $token )
$token string

未被屏蔽的标记(token).

return string

屏蔽的标记(token).

pbkdf2() public 方法

使用标准的 PBKDF2 算法从给定的密码导出一个密钥.

实现 RFC 2898 中规定的 HKDF2. 建议使用 SHA-2 哈希算法之一: sha224, sha256, sha384 或 sha512.

public string pbkdf2 ( $algo, $password, $salt, $iterations, $length 0 )
$algo string

hash_hmac()支持的散列算法, eg. 'SHA-256'.

$password string

源密码

$salt string

随机盐

$iterations integer

散列算法的迭代次数. 尽量设置为阻止字典密码攻击.

$length integer

输出密钥的字节长度. 如果为0, 则输出密钥是哈希算法输出的长度.

return string

派生的密钥.

throws yii\base\InvalidArgumentException

当由于给出的无效参数导致哈希生成失败时.

shouldUseLibreSSL() protected 方法 (可用自版本: 2.0.36)

protected boolean shouldUseLibreSSL ( )
return boolean

如果应该使用LibreSSL, 请使用2.1.5或更高版本.

unmaskToken() public 方法 (可用自版本: 2.0.12)

取消屏蔽之前由maskToken屏蔽的标记(token).

public string unmaskToken ( $maskedToken )
$maskedToken string

屏蔽的标记(token).

return string

未标记的标记或标记格式的空字符串无效.

validateData() public 方法

验证给定数据是否被篡改.

参见 hashData().

public string|false validateData ( $data, $key, $rawHash false )
$data string

要验证的数据. 数据必须先由 hashData() 生成.

$key string

之前用于为 hashData() 中的数据生成散列的密钥. 函数来查看系统上支持的散列算法. 这必须与生成数据散列时传递给 hashData() 的值相同.

$rawHash boolean

这应该与使用 hashData() 生成数据时的值相同. 它指示数据中的散列值是否是二进制格式. 如果为false, 则表示散列值仅由小写十六进制数字组成. 将生成十六进制数字.

return string|false

带有散列的真实数据被删除. 如果数据被篡改, 则为false.

throws yii\base\InvalidConfigException

当 HMAC 生成失败时.

validatePassword() public 方法

根据散列验证密码.

参见 generatePasswordHash().

public boolean validatePassword ( $password, $hash )
$password string

要验证的密码.

$hash string

哈希来验证密码.

return boolean

密码是否正确.

throws yii\base\InvalidArgumentException

password/hash 参数不正确, 或者如果 crypt() 与 Blowfish 散列不可用.