Stdlib: ext/sodium — libsodium crypto API (ext/sodium parity)

[PurHur]

Category

stdlib

Problem

Modern PHP crypto uses ext/sodium (sodium_crypto_*, Sodium\* classes). This compiler has hash_* and openssl_* gaps tracked separately but no libsodium surface.

php-src reference

• ext/sodium/libsodium.c — PHP_FUNCTION(sodium_crypto_secretbox), etc.
• ext/sodium/php_libsodium.h
• Tests: ext/sodium/tests/*.phpt

Repro (failure today)

<?php
var_export(function_exists('sodium_crypto_secretbox'));
$key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$c = sodium_crypto_secretbox('hi', $nonce, $key);
$plain = sodium_crypto_secretbox_open($c, $nonce, $key);
var_export($plain);
echo "\n";

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php repro.php
php bin/vm.php repro.php 2>&1 | head -20
'

Runtime	function_exists	Round-trip
Zend + ext/sodium	true	'hi'
bin/vm.php	false	undefined function fatal

Scope (this repo) — phase 1 VM

Function	Zend role
sodium_crypto_secretbox / open	Secretbox AEAD
sodium_crypto_sign / verify	Ed25519
sodium_bin2hex / hex2bin	Encoding helpers
sodium_memzero	Secure zero (documented no-op acceptable on VM if unavoidable)
Constants	SODIUM_CRYPTO_SECRETBOX_*, SODIUM_CRYPTO_SIGN_*

Module	Path
Extension	ext/sodium/ (new)
Registration	ext/sodium/Module.php, included in module/extension registry (pairs #4839, #9050)
Tests	test/compliance/cases/stdlib/sodium_secretbox.phpt (skip only if extension not built)

Bootstrap / PHP-in-PHP constraint: if phase-1 uses temporary host delegation, it must be explicitly marked as bootstrap-only and tracked to a follow-up that removes host dependency for self-host (#1492). Default semantics should remain php-src-strict.

Phase 2 (separate issues): sodium_crypto_generichash, sodium_crypto_pwhash, and Sodium\* OOP namespace.

Done when

• Repro round-trip returns 'hi' on VM
• function_exists('sodium_crypto_secretbox') is true
• SODIUM_CRYPTO_* constants defined (match Zend values)
• Capability matrix rows added
• No permanent internal_sodium_* shims

[PurHur]

claim: PHP Compiler Ext — I/O & Crypto — starting this run

Gate snapshot (host):

• php script/bootstrap-inventory.php --check → OK 5030/5030
• docker info → OK
• sodium phase-1 gap: sodium_crypto_secretbox* green; sodium_bin2hex/sodium_hex2bin/sodium_memzero/sodium_crypto_box still missing on VM

Implementing remaining phase-1 helpers from the issue done-when (bin2hex/hex2bin/memzero; box if time).

[PurHur]

Merged #19414

Verification

• VM: sodium_bin2hex / sodium_hex2bin / sodium_memzero match Zend (round-trip, ignore chars, SodiumException on bad hex / non-string memzero).
• vendor/bin/phpunit --filter 'sodium_bin2hex_hex2bin_memzero|testSodiumMemzeroFirstArgByRef' → OK (3 tests).
• inventory 5033/5033 + spine sync + generated docs OK.

Phase-1 done-when from the issue body is green for these helpers. Remaining umbrella surface (sodium_crypto_box etc.) can be follow-up issues if still missing.

[PurHur]

Merged: #19414 → 9e680bb

Phase-1 helpers shipped:

• sodium_bin2hex / sodium_hex2bin / sodium_memzero on VM (php-src-strict)
• compliance sodium_bin2hex_hex2bin_memzero.phpt + by-ref unit guard
• spine sync + inventory/capability regen

If further sodium_crypto_box / remaining matrix gaps should stay open, reopen or file a child issue for the leftover surface.