Ref/hash-Phpdoc专题

hash_algos

返回已注册的哈希算法列表

说明

array <span class="methodname">hash_algos ( <span class="methodparam">void )

返回值

返回一个数值索引的数组， 包含了受支持的哈希算法名称。

更新日志

版本 说明
7.4.0 支持 crc32c。
7.1.0 加入 sha512/224，sha512/256，sha3-224，sha3-256，sha3-384 以及 sha3-512 算法的支持。

范例

示例 #1 hash_algos 例程

在 PHP 7.4.0 中，hash_algos 会返回下表所示的算法清单：

<?php
print_r(hash_algos());
?>

以上例程的输出类似于：

Array
(
    [0] => md2
    [1] => md4
    [2] => md5
    [3] => sha1
    [4] => sha224
    [5] => sha256
    [6] => sha384
    [7] => sha512/224
    [8] => sha512/256
    [9] => sha512
    [10] => sha3-224
    [11] => sha3-256
    [12] => sha3-384
    [13] => sha3-512
    [14] => ripemd128
    [15] => ripemd160
    [16] => ripemd256
    [17] => ripemd320
    [18] => whirlpool
    [19] => tiger128,3
    [20] => tiger160,3
    [21] => tiger192,3
    [22] => tiger128,4
    [23] => tiger160,4
    [24] => tiger192,4
    [25] => snefru
    [26] => snefru256
    [27] => gost
    [28] => gost-crypto
    [29] => adler32
    [30] => crc32
    [31] => crc32b
    [32] => crc32c
    [33] => fnv132
    [34] => fnv1a32
    [35] => fnv164
    [36] => fnv1a64
    [37] => joaat
    [38] => haval128,3
    [39] => haval160,3
    [40] => haval192,3
    [41] => haval224,3
    [42] => haval256,3
    [43] => haval128,4
    [44] => haval160,4
    [45] => haval192,4
    [46] => haval224,4
    [47] => haval256,4
    [48] => haval128,5
    [49] => haval160,5
    [50] => haval192,5
    [51] => haval224,5
    [52] => haval256,5
)

参见

  • hash_hmac_algos

hash_copy

拷贝哈希运算上下文

说明

HashContext <span class="methodname">hash_copy ( <span class="type">HashContext $context )

参数

context
由 hash_init 函数返回的哈希运算上下文。

返回值

返回哈希运算上下文的一个复本。

更新日志

版本 说明
7.2.0 接受的参数以及返回值从资源类型修改为 HashContext 对象类型。

范例

示例 #1 hash_copy 例程

<?php
$context = hash_init("md5");
hash_update($context, "data");

/* 拷贝上下文资源以便继续使用 */
$copy_context = hash_copy($context);

echo hash_final($context), "\n";

hash_update($copy_context, "data");
echo hash_final($copy_context), "\n";
?>

以上例程会输出：

8d777f385d3dfec8815d20f7496026dc
511ae0b1c13f95e5f08f1a0dd3da3d93

hash_equals

可防止时序攻击的字符串比较

说明

bool <span class="methodname">hash_equals ( <span class="type">string $known_string , <span class="methodparam">string $user_string )

比较两个字符串，无论它们是否相等，本函数的时间消耗是恒定的。

本函数可以用在需要防止时序攻击的字符串比较场景中， 例如，可以用在比较 crypt 密码哈希值的场景。

参数

known_string
已知长度的、要参与比较的 string

user_string
用户提供的字符串

返回值

当两个字符串相等时返回 true，否则返回 false。

错误／异常

如果所提供的 2 个参数中任何一个不是字符串， 会导致 E_WARNING 消息。

范例

示例 #1 hash_equals 例程

<?php
$expected  = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$correct   = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$incorrect = crypt('apple', '$2a$07$usesomesillystringforsalt$');

var_dump(hash_equals($expected, $correct));
var_dump(hash_equals($expected, $incorrect));
?>

以上例程会输出：

bool(true)
bool(false)

注释

Note:

要想成功进行比较，那么所提供的 2 个参数必须是相同长度的字符串。 如果所提供的字符串长度不同，那么本函数会立即返回 false， 在时序攻击的场景下，已知字符串的长度可能会被泄露。

Note:

非常重要的一点是，用户提供的字符串必须是第二个参数。

hash_file

使用给定文件的内容生成哈希值

说明

string <span class="methodname">hash_file ( <span class="type">string $algo , <span class="methodparam">string $filename [, bool $raw_output = false ] )

参数

algo
要使用的哈希算法的名称，例如："md5"，"sha256"，"haval160,4" 等。 在 hash_algos 中查看支持的算法。

filename
要进行哈希运算的文件路径。支持 fopen 封装器。

raw_output
设置为 true，输出格式为原始的二进制数据。 设置为 false，输出小写的 16 进制字符串。

返回值

如果 raw_output 设置为 true， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。

范例

示例 #1 使用 hash_file

<?php
/* 创建一个要计算哈希值的文件 */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

echo hash_file('md5', 'example.txt');
?>

以上例程会输出：

5c6ffbdd40d9556b73a21e63c3e0e904

参见

  • hash
  • hash_hmac_file
  • hash_update_file
  • md5_file
  • sha1_file

hash_final

结束增量哈希，并且返回摘要结果

说明

string <span class="methodname">hash_final ( <span class="type">HashContext $context [, <span class="methodparam">bool $raw_output<span class="initializer"> = false ] )

参数

context
hash_init 函数返回的哈希运算上下文资源。

raw_output
设置为 true，输出格式为原始的二进制数据。 设置为 false，输出小写的 16 进制字符串。

返回值

如果 raw_output 设置为 true， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。

更新日志

版本 说明
7.2.0 接收参数从资源类型修改为 HashContext 对象类型。

范例

示例 #1 hash_final 例程

<?php
$ctx = hash_init('sha1');
hash_update($ctx, 'The quick brown fox jumped over the lazy dog.');
echo hash_final($ctx);
?>

以上例程会输出：

c0854fb9fb03c41cce3802cb0d220529e6eef94e

参见

  • hash_init
  • hash_update
  • hash_update_stream
  • hash_update_file

hash_hkdf

Generate a HKDF key derivation of a supplied key input

说明

string <span class="methodname">hash_hkdf ( <span class="type">string $algo , <span class="methodparam">string $key [, int $length<span class="initializer"> = 0 [, <span class="methodparam">string $info<span class="initializer"> = "" [, <span class="methodparam">string $salt<span class="initializer"> = "" ]]] )

参数

algo
Name of selected hashing algorithm (i.e. "sha256", "sha512", "haval160,4", etc..) See hash_algos for a list of supported algorithms.

Note:

Non-cryptographic hash functions are not allowed.

key
Input keying material (raw binary). Cannot be empty.

length
Desired output length in bytes. Cannot be greater than 255 times the chosen hash function size.

If length is 0, the output length will default to the chosen hash function size.

info
Application/context-specific info string.

salt
Salt to use during derivation.

While optional, adding random salt significantly improves the strength of HKDF.

返回值

Returns a string containing a raw binary representation of the derived key (also known as output keying material - OKM); or false on failure.

错误／异常

An E_WARNING will be raised if key is empty, algo is unknown/non-cryptographic, length is less than 0 or too large (greater than 255 times the size of the hash function).

范例

示例 #1 hash_hkdf example

<?php
// Generate a random key, and salt to strengthen it during derivation.
$inputKey = random_bytes(32);
$salt = random_bytes(16);

// Derive a pair of separate keys, using the same input created above.
$encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
$authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);

var_dump($encryptionKey !== $authenticationKey); // bool(true)
?>

The above example produces a pair of separate keys, suitable for creation of an encrypt-then-HMAC construct, using AES-256 and SHA-256 for encryption and authentication respectively.

参见

hash_hmac_algos

Return a list of registered hashing algorithms suitable for hash_hmac

说明

array <span class="methodname">hash_hmac_algos ( <span class="methodparam">void )

返回值

Returns a numerically indexed array containing the list of supported hashing algorithms suitable for <span class="function">hash_hmac.

范例

示例 #1 hash_hmac_algos example

<?php
print_r(hash_hmac_algos());

以上例程的输出类似于：

Array
(
    [0] => md2
    [1] => md4
    [2] => md5
    [3] => sha1
    [4] => sha224
    [5] => sha256
    [6] => sha384
    [7] => sha512/224
    [8] => sha512/256
    [9] => sha512
    [10] => sha3-224
    [11] => sha3-256
    [12] => sha3-384
    [13] => sha3-512
    [14] => ripemd128
    [15] => ripemd160
    [16] => ripemd256
    [17] => ripemd320
    [18] => whirlpool
    [19] => tiger128,3
    [20] => tiger160,3
    [21] => tiger192,3
    [22] => tiger128,4
    [23] => tiger160,4
    [24] => tiger192,4
    [25] => snefru
    [26] => snefru256
    [27] => gost
    [28] => gost-crypto
    [29] => haval128,3
    [30] => haval160,3
    [31] => haval192,3
    [32] => haval224,3
    [33] => haval256,3
    [34] => haval128,4
    [35] => haval160,4
    [36] => haval192,4
    [37] => haval224,4
    [38] => haval256,4
    [39] => haval128,5
    [40] => haval160,5
    [41] => haval192,5
    [42] => haval224,5
    [43] => haval256,5
)

注释

Note:

Before PHP 7.2.0 the only means to get a list of supported hash algorithms has been to call hash_algos which also returns hash algorithms that are not suitable for <span class="function">hash_hmac.

参见

  • hash_hmac
  • hash_algos

hash_hmac_file

使用 HMAC 方法和给定文件的内容生成带密钥的哈希值

说明

string <span class="methodname">hash_hmac_file ( <span class="methodparam">string $algo , string $filename , <span class="type">string $key [, <span class="methodparam">bool $raw_output<span class="initializer"> = false ] )

参数

algo
要使用的哈希算法名称，例如："md5"，"sha256"，"haval160,4" 等。 如何获取受支持的算法清单，请参见 <span class="function">hash_hmac_algos 函数。

filename
要进行哈希运算的文件路径，支持 fopen 封装器。

key
使用 HMAC 生成信息摘要时所使用的密钥。

raw_output
设置为 true 输出原始二进制数据， 设置为 false 输出小写 16 进制字符串。

返回值

如果 raw_output 设置为 true， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。 如果 algo 参数指定的不是受支持的算法，或者无法读取 filename 给定的文件，则返回 false。

更新日志

版本 说明
7.2.0 不再支持非加密的哈希函数（adler32，crc32，crc32b，fnv132，fnv1a32，fnv164，fnv1a64，joaat）。

范例

示例 #1 hash_hmac_file 例程

<?php
/* 创建一个要计算哈希值的文件 */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

echo hash_hmac_file('md5', 'example.txt', 'secret');
?>

以上例程会输出：

7eb2b5c37443418fc77c136dd20e859c

参见

  • hash_hmac_algos
  • hash_hmac
  • hash_file

hash_hmac

使用 HMAC 方法生成带有密钥的哈希值

说明

string <span class="methodname">hash_hmac ( <span class="type">string $algo , <span class="methodparam">string $data , string $key [, bool $raw_output = false ] )

参数

algo
要使用的哈希算法名称，例如："md5"，"sha256"，"haval160,4" 等。 如何获取受支持的算法清单，请参见 <span class="function">hash_hmac_algos 函数。

data
要进行哈希运算的消息。

key
使用 HMAC 生成信息摘要时所使用的密钥。

raw_output
设置为 true 输出原始二进制数据， 设置为 false 输出小写 16 进制字符串。

返回值

如果 raw_output 设置为 true， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。 如果 algo 参数指定的不是受支持的算法，返回 false。

更新日志

版本 说明
7.2.0 不再支持非加密的哈希函数（adler32，crc32，crc32b，fnv132，fnv1a32，fnv164，fnv1a64，joaat）。

范例

示例 #1 hash_hmac 例程

<?php
echo hash_hmac('ripemd160', 'The quick brown fox jumped over the lazy dog.', 'secret');
?>

以上例程会输出：

b8e7ae12510bdfb1812e463a7f086122cf37e4f7

参见

  • hash
  • hash_hmac_algos
  • hash_init
  • hash_hmac_file

hash_init

初始化增量哈希运算上下文

说明

HashContext <span class="methodname">hash_init ( <span class="type">string $algo [, <span class="methodparam">int $options<span class="initializer"> = 0 [, <span class="methodparam">string $key<span class="initializer"> = null ]] )

参数

algo
要使用的哈希算法名称，例如："md5"，"sha256"，"haval160,4" 等。 如何获取受支持的算法清单，请参见 <span class="function">hash_algos。

options
进行哈希运算的可选设置，目前仅支持一个选项：HASH_HMAC。 当指定此选项的时候，必须 指定 key 参数。

key
当 options 参数为 HASH_HMAC 时， 使用此参数传入进行 HMAC 哈希运算时的共享密钥。

返回值

返回哈希运算上下文对象，以供 <span class="function">hash_update， <span class="function">hash_update_stream，<span class="function">hash_update_file, 和 <span class="function">hash_final 函数使用。

更新日志

版本 说明
7.2.0 当使用 HASH_HMAC 选项的时候，不再支持非加密的哈希函数（adler32，crc32，crc32b，fnv132，fnv1a32，fnv164，fnv1a64，joaat）。
7.2.0 返回 HashContext 对象，不再返回资源类型。

范例

示例 #1 增量哈希运算例程

<?php
$ctx = hash_init('md5');
hash_update($ctx, 'The quick brown fox ');
hash_update($ctx, 'jumped over the lazy dog.');
echo hash_final($ctx);
?>

以上例程会输出：

5c6ffbdd40d9556b73a21e63c3e0e904

参见

  • hash
  • hash_algos
  • hash_file
  • hash_hmac
  • hash_hmac_file

hash_pbkdf2

生成所提供密码的 PBKDF2 密钥导出

说明

string <span class="methodname">hash_pbkdf2 ( <span class="type">string $algo , <span class="methodparam">string $password , string $salt , int $iterations [, <span class="type">int $length = 0 [, <span class="type">bool $raw_output = false ]] )

参数

algo
哈希算法名称，例如 md5，sha256，haval160,4 等。 受支持的算法清单请参见 hash_algos。

password
要进行导出的密码。

salt
进行导出时所使用的“盐”，这个值应该是随机生成的。

iterations
进行导出时的迭代次数。

length
密钥导出数据的长度。如果 raw_output 为 true， 此参数为密钥导出数据的字节长度。如果 raw_output 为 false， 此参数为密钥导出数据的字节长度的 2 倍，因为 1 个字节数据对应的 2 个 16 进制的字符。

如果传入 0，则使用所选算法的完整输出大小。

raw_output
设置为 true 输出原始二进制数据， 设置为 false 输出小写 16 进制字符串。

返回值

如果 raw_output 设置为 true， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。

错误／异常

在以下情况下会产生 E_WARNING： 指定了未知的算法， iterations 小于等于 0， length 小于等于 0 或者 salt 过长（大于 INT_MAX - 4）。

更新日志

版本 说明
7.2.0 不再支持非加密的哈希函数（adler32，crc32，crc32b，fnv132，fnv1a32，fnv164，fnv1a64，joaat）。

范例

示例 #1 hash_pbkdf2 例程，基础用法

<?php
$password = "password";
$iterations = 1000;

// 使用 openssl_random_pseudo_bytes()，random_bytes()，或者其他合适的随机数生成函数
// 来生成随机初始向量
$salt = openssl_random_pseudo_bytes(16, MCRYPT_DEV_URANDOM);

$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
echo $hash;
?>

以上例程的输出类似于：

120fb6cffcf8b32c43e7

注释

Caution

为了安全起见，可以使用 PBKDF2 方法对密码明文进行哈希运算后再存储。 但是更好的方案是使用 password_hash 函数 或者使用 CRYPT_BLOWFISH 算法调用 <span class="function">crypt 函数。

参见

  • crypt
  • password_hash
  • hash
  • hash_algos
  • hash_init
  • hash_hmac
  • hash_hmac_file
  • openssl_pbkdf2

hash_update_file

从文件向活跃的哈希运算上下文中填充数据

说明

bool <span class="methodname">hash_update_file ( <span class="methodparam">HashContext $hcontext , <span class="type">string $filename [, <span class="methodparam">resource $scontext<span class="initializer"> = null ] )

参数

hcontext
由 hash_init 函数返回的哈希运算上下文。

filename
要进行哈希运算的文件路径，支持 fopen 封装器。

scontext
由 stream_context_create 函数返回的流上下文。

返回值

成功时返回 true， 或者在失败时返回 false。

更新日志

版本 说明
7.2.0 接收参数从资源类型修改为 HashContext 对象类型。

参见

  • hash_init
  • hash_update
  • hash_update_stream
  • hash_final
  • hash
  • hash_file

hash_update_stream

从打开的流向活跃的哈希运算上下文中填充数据

说明

int <span class="methodname">hash_update_stream ( <span class="methodparam">HashContext $context , <span class="type">resource $handle [, <span class="methodparam">int $length<span class="initializer"> = -1 ] )

参数

context
由 hash_init 函数返回的哈希运算上下文。

handle
创建流的函数返回的打开的文件句柄。

length
要从 handle 向活跃的哈希运算上下文中拷贝 的最大字符数。

返回值

从 handle 向哈希运算上下文中实际填充的字节数量。

更新日志

版本 说明
7.2.0 接收参数从资源类型修改为 HashContext 对象类型。

范例

示例 #1 hash_update_stream 例程

<?php
$fp = tmpfile();
fwrite($fp, 'The quick brown fox jumped over the lazy dog.');
rewind($fp);

$ctx = hash_init('md5');
hash_update_stream($ctx, $fp);
echo hash_final($ctx);
?>

以上例程会输出：

5c6ffbdd40d9556b73a21e63c3e0e904

参见

  • hash_init
  • hash_update
  • hash_final
  • hash
  • hash_file

hash_update

向活跃的哈希运算上下文中填充数据

说明

bool <span class="methodname">hash_update ( <span class="type">HashContext $context , <span class="methodparam">string $data )

参数

context
由 hash_init 函数返回的哈希运算上下文。

data
要向哈希摘要中追加的数据。

返回值

返回 true。

更新日志

版本 说明
7.2.0 接收参数从资源类型修改为 HashContext 对象类型。

参见

  • hash_init
  • hash_update_file
  • hash_update_stream
  • hash_final

hash

生成哈希值 （消息摘要）

说明

string hash ( string $algo , <span class="type">string $data [, <span class="methodparam">bool $raw_output<span class="initializer"> = false ] )

参数

algo
要使用的哈希算法，例如："md5"，"sha256"，"haval160,4" 等。 在 <span class="function">hash_algos 中查看支持的算法。

data
要进行哈希运算的消息。

raw_output
设置为 true 输出原始二进制数据， 设置为 false 输出小写 16 进制字符串。

返回值

如果 raw_output 设置为 true， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。

范例

示例 #1 一个 hash 例程

<?php
echo hash('ripemd160', 'The quick brown fox jumped over the lazy dog.');
?>

以上例程会输出：

ec457d0a974c48d5685a7efa03d137dc8bbde7e3

示例 #2 使用 PHP 5.4 或者更高版本计算 tiger 哈希值

<?php
function old_tiger($data = "", $width=192, $rounds = 3) {
    return substr(
        implode(
            array_map(
                function ($h) {
                    return str_pad(bin2hex(strrev($h)), 16, "0");
                },
                str_split(hash("tiger192,$rounds", $data, true), 8)
            )
        ),
        0, 48-(192-$width)/4
    );
}
echo hash('tiger192,3', 'a-string'), PHP_EOL;
echo old_tiger('a-string'), PHP_EOL;
?>

以上例程在 PHP 5.3 中的输出：

146a7492719b3564094efe7abbd40a7416fd900179d02773
64359b7192746a14740ad4bb7afe4e097327d0790190fd16

以上例程在 PHP 5.4 中的输出：

64359b7192746a14740ad4bb7afe4e097327d0790190fd16
146a7492719b3564094efe7abbd40a7416fd900179d02773

参见

  • hash_file
  • hash_hmac
  • hash_init
  • md5
  • sha1

目录

  • hash_algos — 返回已注册的哈希算法列表
  • hash_copy — 拷贝哈希运算上下文
  • hash_equals — 可防止时序攻击的字符串比较
  • hash_file — 使用给定文件的内容生成哈希值
  • hash_final — 结束增量哈希，并且返回摘要结果
  • hash_hkdf — Generate a HKDF key derivation of a supplied key input
  • hash_hmac_algos — Return a list of registered hashing algorithms suitable for hash_hmac
  • hash_hmac_file — 使用 HMAC 方法和给定文件的内容生成带密钥的哈希值
  • hash_hmac — 使用 HMAC 方法生成带有密钥的哈希值
  • hash_init — 初始化增量哈希运算上下文
  • hash_pbkdf2 — 生成所提供密码的 PBKDF2 密钥导出
  • hash_update_file — 从文件向活跃的哈希运算上下文中填充数据
  • hash_update_stream — 从打开的流向活跃的哈希运算上下文中填充数据
  • hash_update — 向活跃的哈希运算上下文中填充数据
  • hash — 生成哈希值 （消息摘要）
本站为非盈利网站，作品由网友提供上传，如无意中有侵犯您的版权，请联系删除