Skip to content

ext/sodium: Add crypto_kem (X-Wing) and crypto_kem_mlkem768 bindings - #23420

Open
ZacharyDuBois wants to merge 7 commits into
php:masterfrom
ZacharyDuBois:sodium-kem
Open

ext/sodium: Add crypto_kem (X-Wing) and crypto_kem_mlkem768 bindings#23420
ZacharyDuBois wants to merge 7 commits into
php:masterfrom
ZacharyDuBois:sodium-kem

Conversation

@ZacharyDuBois

Copy link
Copy Markdown

libsodium 1.0.22 introduced a KEM API: X-Wing (hybrid ML-KEM768+X25519, upstream's recommended KEM) and ML-KEM768 (FIPS 203). This exposes both:

  • sodium_crypto_kem_{keypair,seed_keypair,secretkey,publickey,enc,dec}
  • sodium_crypto_kem_mlkem768_{keypair,seed_keypair,secretkey,publickey,enc,dec} + SODIUM_CRYPTO_KEM[_MLKEM768]_*BYTES constants

@ZacharyDuBois

Copy link
Copy Markdown
Author

Tried sending an email to internals but seems like y'all don't support DMARC with p=reject as it just bounced as the mailing list seems to be changing my DKIM signature.

@NickSdot

NickSdot commented Aug 23, 2026

Copy link
Copy Markdown
Contributor

Tried sending an email to internals but seems like y'all don't support DMARC with p=reject as it just bounced as the mailing list seems to be changing my DKIM signature.

While the subscribe step? If yes, you maybe want to ping @ derickr.

@ZacharyDuBois

Copy link
Copy Markdown
Author

But you did the subscribe step? If yes, you maybe want to ping @ derickr.

Yep, sent an intro (I think on Thursday) and that went though but shortly after I got the forensic report and it showed both SPF and DKIM failed. Looking at the headers, looks like it hit a relay causing the failure. Running an outbound test reports my email is all good.

@NickSdot

Copy link
Copy Markdown
Contributor

But you did the subscribe step? If yes, you maybe want to ping @ derickr.

Yep, sent an intro (I think on Thursday) and that went though but shortly after I got the forensic report and it showed both SPF and DKIM failed. Looking at the headers, looks like it hit a relay causing the failure. Running an outbound test reports my email is all good.

Fwiw, it went through anyway: https://news-web.php.net/php.internals/132308

@Ayesh
Ayesh requested a review from jedisct1 August 23, 2026 17:58
@jedisct1

Copy link
Copy Markdown
Contributor

The changes look good to me.

Thanks a lot for adding these functions!

@ZacharyDuBois

Copy link
Copy Markdown
Author

@jedisct1 no problem! I have a project I am working on that needed some post-quantum stuff added in (more so for playing around). Saw these were missing and didn't feel like hassling someone to add them when I am perfectly capable of it.

This is my first PR for PHP so let me know if I am missing anything! More than happy to make any edits. From what I heard on the mailing list, 8.6 is on a feature freeze so sadly it sounds like this won't make it out for 8.6 :(

@ZacharyDuBois

Copy link
Copy Markdown
Author

Fixed the merge conflict with NEWS

@Girgias

Girgias commented Aug 24, 2026

Copy link
Copy Markdown
Member

Probably best for @paragonie-scott / @paragonie-security to review this. :)

@ZacharyDuBois

Copy link
Copy Markdown
Author

@Girgias more the merrier but this is only direct passthrough to libsodium which is maintained by @jedisct1 with a bit of conversion to make it PHP-esque. That and a bunch of tests that are similar to the ones in place for the other libsodium calls.

@Girgias

Girgias commented Aug 24, 2026

Copy link
Copy Markdown
Member

@Girgias more the merrier but this is only direct passthrough to libsodium which is maintained by @jedisct1 with a bit of conversion to make it PHP-esque. That and a bunch of tests that are similar to the ones in place for the other libsodium calls.

He does maintain https://github.com/jedisct1/libsodium-php so his input would probably be useful too :)

@ZacharyDuBois

Copy link
Copy Markdown
Author

@Girgias sorry - was quite busy at the tail end of last week. @jedisct1 already commented on this:

The changes look good to me.

Thanks a lot for adding these functions!

@Girgias Girgias left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please rebase :)

Comment thread ext/sodium/php_libsodium.h
Expose the libsodium 1.0.22 generic KEM API (X-Wing, hybrid
ML-KEM768+X25519). Guarded so older libsodium builds are unaffected.
Expose libsodium 1.0.22's ML-KEM768 (FIPS 203) KEM with the same shape
as the generic crypto_kem API.
Not required for correctness (they are only expanded inside guarded
generated code), but makes the libsodium 1.0.22 dependency explicit.
@ZacharyDuBois

Copy link
Copy Markdown
Author

@Girgias committed and rebased.

@Girgias Girgias left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nit I just realised

Comment thread ext/sodium/libsodium.c Outdated
Comment thread ext/sodium/libsodium.c Outdated
Comment thread ext/sodium/libsodium.c Outdated
Comment thread ext/sodium/libsodium.c Outdated
@ZacharyDuBois

Copy link
Copy Markdown
Author

All good - fixed in the most recent commit. I was following the pattern in the file. Didn't notice it used both patterns (newer ones probably using what you referenced).

Comment thread ext/sodium/tests/crypto_kem.phpt Outdated
@ZacharyDuBois

ZacharyDuBois commented Sep 1, 2026

Copy link
Copy Markdown
Author

@NickSdot should be squared away in the tests now. Not sure about the windows build failure with the ODBC extension though. I am pretty sure thats unrelated.

@NickSdot NickSdot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@NickSdot should be squared away in the tests now. Not sure about the windows build failure with the ODBC extension though. I am pretty sure thats unrelated.

Windows was fixed in 52385c9. Catchs look good now. Added some more hints. :)

Comment thread ext/sodium/tests/crypto_kem_mlkem768.phpt Outdated
Comment thread ext/sodium/libsodium.c
Comment thread ext/sodium/libsodium.c
Comment thread ext/sodium/libsodium.c
An invalid ML-KEM public key encoding and a small-order X25519
ciphertext component deterministically fail inside libsodium,
exercising the memzero-on-error branches. ML-KEM768 decapsulation
never fails (implicit rejection), so it has no such test. Also drop
the cross-family length check, which duplicated existing coverage.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants