====== PHP RFC: Integrating BLAKE3 into PHP ======

Version: 0.1

Date: 2025-01-24

Author: Hans Henrik Bergan, hans@loltek.net

Status: Draft

First Published at: http://wiki.php.net/rfc/blake3

===== Introduction =====

TL;DR: Essentially, BLAKE3 provides SHA3-256–level security at considerably higher throughput.

BLAKE3 is a cryptographic hash function based on the SHA3-finalist BLAKE, offering SHA3-256-like security at much higher speed.  Benchmarks from /ext/hash/bench.php highlight BLAKE3's performance: it is over four times faster than SHA3-256 on AMD Ryzen 9 7950x, with BLAKE3 completing bench.php in 0.007752 seconds versus SHA3-256's 0.031518 seconds.
/ext/hash/bench.php chart on AMD Ryzen 9 7950x, excluding non-cryptographic hashes:

{{:rfc:output_5_.png?|}}

And here is a chart from the BLAKE3 developers:

{{ :rfc:speed.svg |}}

This RFC proposes adding BLAKE3 support to PHP, offering performance and security assurance to developers requiring hashing functionality.

===== Proposal =====

The proposal is to integrate BLAKE3 into PHP as a supported algorithm in the ext/hash extension. Developers will be able to use the familiar hash() function and related APIs to compute BLAKE3 hashes.

Example usage:

<code php>
<?php
// Compute a BLAKE3 hash
$hash = hash('blake3', 'The quick brown fox jumps over the lazy dog');
echo $hash, PHP_EOL; // 2f1514181aadccd913abd94cfa592701a5686ab23f8df1dff1b74710febc6d4a

// Compute a keyed BLAKE3 hash
$key = 'secret-key';
$hash_keyed = hash_hmac('blake3', 'The quick brown fox jumps over the lazy dog', $key);
echo $hash_keyed, PHP_EOL;
?>
</code>
The integration will include:

Support for the blake3 algorithm in the hash() function.

Support for keyed hashing (HMAC) with hash_hmac().

Updated documentation for ext/hash to include examples and usage of BLAKE3.

===== Backward Incompatible Changes =====

No backward-incompatible changes are introduced by this RFC. The addition of BLAKE3 is purely additive and does not modify existing functionality.

===== Proposed PHP Version(s) =====

This feature is proposed for inclusion in the next PHP 8.x release.

===== RFC Impact =====

==== To SAPIs ====

No impact is expected on CLI, Development web server, or embedded PHP.

==== To Existing Extensions ====

The ext/hash extension will be updated to include BLAKE3. This change will not affect other extensions.

==== To Opcache ====

There is no expected impact on Opcache.

==== New Constants ====

No new constants are introduced.

==== php.ini Defaults ====

No new php.ini settings are required for this feature.

===== Open Issues =====

There are currently no open issues related to this RFC.

===== Unaffected PHP Functionality =====

This RFC does not impact existing hashing algorithms or functionality in PHP.

===== Future Scope =====

Future enhancements to BLAKE3 support could include:

  * Multi-threaded hashing for even greater performance on large inputs. There is no multithreading support in the current ext/hash apis.
  * Support for extended output modes of BLAKE3 (e.g., XOF functionality). There is no XOF support in the current ext/hash apis.

===== Proposed Voting Choices =====

<doodle title="Integrate BLAKE3?" auth="divinity76" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

The implementation is available as a pull request at https://github.com/php/php-src/pull/13194. Tests have been included as part of the pull request, ensuring the correctness and reliability of the implementation.

===== Implementation =====

After approval, this section will include:

The version(s) the feature was merged into.

A link to the git commit(s).

A link to the PHP manual entry for the feature.

===== References =====

BLAKE3 Official Website: [[https://blake3.io/]]

BLAKE3 Specification: [[https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf]]

PHP Pull Request for BLAKE3 Support: [[https://github.com/php/php-src/pull/13194]]

===== Rejected Features =====

No features have been rejected during the discussion of this RFC.