16: Establish a Shared Key with X-Wing and ML-KEM-768
Overview
Section titled “Overview”Walk through key encapsulation and decapsulation for two recipients. A key encapsulation mechanism lets a sender derive a shared secret using a recipient’s public key and send a ciphertext the recipient can decapsulate.
Prerequisites
Section titled “Prerequisites”- PHP 8.6 CLI. Confirm the version with
php --version. - The
sodiumextension built with libsodium 1.0.22 or later. - Review the previous chapter if you’re following the series in order.
Allow about 10 minutes for the walkthrough and exercise.
What You’ll Build
Section titled “What You’ll Build”A runnable sodium-kem.php example.
Step 1: Run the example (~5 min)
Section titled “Step 1: Run the example (~5 min)”Run the following from the root of the Code with PHP repository.
php code/php-8-6/16-sodium-kem/sodium-kem.php<?php
declare(strict_types=1);
$xWingKeypair = sodium_crypto_kem_keypair();[$ciphertext, $sent] = sodium_crypto_kem_enc(sodium_crypto_kem_publickey($xWingKeypair));$received = sodium_crypto_kem_dec($ciphertext, sodium_crypto_kem_secretkey($xWingKeypair));echo 'X-Wing keys agree: ', hash_equals($sent, $received) ? 'yes' : 'no', PHP_EOL;
$mlKemKeypair = sodium_crypto_kem_mlkem768_keypair();[$ciphertext, $sent] = sodium_crypto_kem_mlkem768_enc(sodium_crypto_kem_mlkem768_publickey($mlKemKeypair));$received = sodium_crypto_kem_mlkem768_dec($ciphertext, sodium_crypto_kem_mlkem768_secretkey($mlKemKeypair));echo 'ML-KEM-768 keys agree: ', hash_equals($sent, $received) ? 'yes' : 'no', PHP_EOL;Expected Result
Section titled “Expected Result”X-Wing keys agree: yesML-KEM-768 keys agree: yesWhy It Works
Section titled “Why It Works”The receiver holds the secret key and publishes the public key through an authenticated channel. Encapsulation returns the ciphertext and shared secret, in that order. X-Wing combines ML-KEM-768 and X25519. Use an established protocol for authentication and use of the shared key.
Troubleshooting
Section titled “Troubleshooting”- If either function is undefined even with Sodium enabled, check the library build with
php --ri sodium.
Exercise
Section titled “Exercise”Print the length of the ciphertext and secret for each suite. Compare the values with the matching SODIUM_CRYPTO_KEM_*BYTES constants without printing the secret itself.
Wrap-up
Section titled “Wrap-up”Continue with Encrypt IP Addresses with Sodium.