PHP 8.4: Sodium: `AEGIS-128L` and `AEGIS256` support

Version8.4

TypeNew Feature

AEGIS is an AES-based family of authenticated encryption algorithms that is faster than AES-GCM. The Sodium extension in PHP 8.4 supports AEGIS-128L and AEGIS256 encryption algorithms if the Sodium extension is compiled with libsodium 1.0.19 or later.

PHP 8.4 Sodium extension supports AEGIS-128L and AEGIS256 using PHP functions that follow the pattern _keygen, _encrypt, and _decrypt following the same pattern followed by the existing aes256gcm, chacha20poly1305, chacha20poly1305_ietf, and xchacha20poly1305 encryption algorithms. All of these are Authenticated Encryption with Additional Data (AEAD) algorithms.

AEGIS Encryption with PHP Sodium Extension
The Sodium extension in PHP 8.4 now supports AEGIS-128L and AEGIS-256 Authenticated Encryption ciphers. They are significantly faster than AES-GCM and CHACHA20-POLY1305. this article benchmarks them and explains how to securely encrypt and decrypt data using AEGIS-128L and AEGIS256 on PHP.

New Functions and PHP Constants

The Sodium extension in PHP 8.4 adds six new PHP functions and four new PHP constants for AEGIS-128L and AEGIS-256 AEAD algorithms.

`AEGIS-128L` Functions and Constants

AEGIS-128L is an AEAD algorithm that takes a 128-bit key and a 128-bit nonce value, and can encrypt/decrypt data less than 2*64 bits.

Constants:

SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES constant: Number of bytes required for the key value used by the AEGIS-128L algorithm. Assigned 16.
SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES constant: Number of bytes required for the nonce value used by AEGIS-128L algorithm. Assigned 16.
SODIUM_CRYPTO_AEAD_AEGIS128L_NSECBYTES constant, assigned 0.
SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES constant, assigned 32.

Functions:

sodium_crypto_aead_aegis128l_keygen function: Generates and returns a cryptographically secure random number of required length (SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES) for AEGIS-128L.
sodium_crypto_aead_aegis128l_encrypt function: Encrypts and authenticated plain-text data with AEGIS-128L.
sodium_crypto_aead_aegis128l_decrypt function: Verifies and then decrypts a message with AEGIS-128L.

sodium_crypto_aead_aegis128l_keygen function synopsis

/**  
 * Generate a random AEGIS-128L key
 * @return string  
 */
function sodium_crypto_aead_aegis128l_keygen(): string {  
}

sodium_crypto_aead_aegis128l_encrypt function synopsis

/**  
 * Encrypt then authenticate with AEGIS-128L.
 * @param string $message The plain-text message to encrypt.  
 * @param string $additional_data Additional, authenticated data. This is used in the verification of the authentication tag appended to the ciphertext, but it is not encrypted or stored in the ciphertext. 
 * @param string $nonce A number that must be only used once, per message. 16 bytes long.  
 * @param string $key Encryption key (128-bit).  
 * @return string Encrypted cipher-text  
 */
function sodium_crypto_aead_aegis128l_encrypt(string $message, string $additional_data, string $nonce, string $key): string {
}

sodium_crypto_aead_aegis128l_decrypt function synopsis

/**  
 * Verify and then decrypt a message with AEGIS-128L.
 * @param string $message Encrypted message created by sodium_crypto_aead_aegis128l_encrypt() function.  
 * @param string $additional_data Additional, authenticated data. This is used in the verification of the authentication tag appended to the ciphertext, but it is not encrypted or stored in the ciphertext. This must be the same value passed when encrypting the plain-text message. 
 * @param string $nonce A number that must be only used once, per message. 16 bytes long. This must be the same nonce value passed when encrypting the plain-text message.
 * @param string $key Encryption key (128-bit).  
 * @return string Encrypted cipher-text
 */
function sodium_crypto_aead_aegis128l_decrypt(string $message, string $additional_data, string $nonce, string $key): string {}

`AEGIS-256` Functions and Constants

Constants:

SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES constant: Number of bytes required for the key value used by AEGIS-256 algorithm. Assigned 32.
SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES constant: Number of bytes required for the nonce value used by the AEGIS-256 algorithm. Assigned 32.
SODIUM_CRYPTO_AEAD_AEGIS256_NSECBYTES constant, assigned 0
SODIUM_CRYPTO_AEAD_AEGIS256_ABYTES constant, assigned 32.

Functions:

sodium_crypto_aead_aegis256_keygen function: Generates and returns a cryptographically secure random number of required length (SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES) for AEGIS-256.
sodium_crypto_aead_aegis256_encrypt function: Encrypts and authenticated plain-text data with AEGIS-256.
sodium_crypto_aead_aegis256_decrypt function: Verifies and then decrypts a message with AEGIS-256.

sodium_crypto_aead_aegis256_keygen function synopsis

/**  
 * Generate a random AEGIS-256 key
 * @return string  
 */
function sodium_crypto_aead_aegis256_keygen(): string {  
}

sodium_crypto_aead_aegis256_encrypt function synopsis

/**  
 * Encrypt and then authenticate with AEGIS-256.
 * @param string $message The plain-text message to encrypt.  
 * @param string $additional_data Additional, authenticated data. This is used in the verification of the authentication tag appended to the ciphertext, but it is not encrypted or stored in the ciphertext. 
 * @param string $nonce A number that must be only used once, per message. 32 bytes long.  
 * @param string $key Encryption key (256-bit).  
 * @return string Encrypted cipher-text  
 */
function sodium_crypto_aead_aegis256_encrypt(string $message, string $additional_data, string $nonce, string $key): string {
}

sodium_crypto_aead_aegis256_decrypt function synopsis

/**  
 * Verify and then decrypt a message with AEGIS-256.
 * @param string $message Encrypted message created by sodium_crypto_aead_aegis256_encrypt() function.  
 * @param string $additional_data Additional, authenticated data. This is used in the verification of the authentication tag appended to the ciphertext, but it is not encrypted or stored in the ciphertext. This must be the same value passed when encrypting the plain-text message. 
 * @param string $nonce A number that must be only used once, per message. 32 bytes long. This must be the same nonce value passed when encrypting the plain-text message.
 * @param string $key Encryption key (256-bit).  
 * @return string Encrypted cipher-text
 */
function function sodium_crypto_aead_aegis256_decrypt(string $ciphertext, string $additional_data, string $nonce, string $key): string|false

Check `AEGIS-128L` and `AEGIS-256` availability

There is no dedicated function similar to sodium_crypto_aead_aes256gcm_is_available that returns whether AEGIS-128L and AEGIS-256 AEAD algorithms are available.

However, the new functions and constants are declared only if all of the requirements for them are fulfilled. This requires a x86_64 or aarch64 CPU, PHP 8.4, and Sodium extension to be compiled with with libsodium version 1.0.19 or later. Checking the availability of one of the new functions serves as an availability check for these algorithms:

function_exists('sodium_crypto_aead_aegis256_encrypt') {
    // AEGIS-128L available.
}

`AEGIS-128L` and `AEGIS-256` Usage Examples

See AEGIS Encryption with PHP Sodium Extension for detailed information and benchmarks on these two AEAD algorithms.

The following are quick examples showing the usage of the two new encryption algorithms.

AEGIS-128L

// generate a random key of sufficient length (16 bytes)
// This value must not be public.
$key = sodium_crypto_aead_aegis128l_keygen();

// Generate random nonce value of SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES length (16 bytes).
// This value should be stored along the encrypted text, but is not required to be private
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES);

// Additional data. This can be a user ID, email address, or empty.
$additional_data = '';

// Message to encrypt
$message = 'Hello';

// Encrypt
$ciphertext = sodium_crypto_aead_aegis128l_encrypt($message, $additional_data, $nonce, $key);

// Decrypt
$decryptedMessage = sodium_crypto_aead_aegis128l_decrypt($ciphertext, $additional_data, $nonce, $key); // "Hello"

AEGIS-256

// generate a random key of sufficient length (32 bytes)
// This value must not be public.
$key = sodium_crypto_aead_aegis256_keygen();

// Generate random nonce value of SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES length (32 bytes).
// This value should be stored along the encrypted text, but is not required to be private
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES);

// Additional data. This can be a user ID, email address, or empty.
$additional_data = '';

// Message to encrypt
$message = 'Hello';

// Encrypt
$ciphertext = sodium_crypto_aead_aegis256_encrypt($message, $additional_data, $nonce, $key);

// Decrypt
$decryptedMessage = sodium_crypto_aead_aegis256_decrypt($ciphertext, $additional_data, $nonce, $key); // "Hello"

Backward Compatibility Impact

AEGIS-128L and AEGIS-256 algorithms are added as new functions and constants in the Sodium extension in PHP 8.4.

The sodium_compat project provides a user-land PHP polyfill for Sodium extension. There is an open issue on the project to add support for AEGIS-128L and AEGIS-256, albeit with no work done on that front.

Implementation

PHP 8.4: Sodium: AEGIS-128L and AEGIS256 support

New Functions and PHP Constants

AEGIS-128L Functions and Constants

AEGIS-256 Functions and Constants

Check AEGIS-128L and AEGIS-256 availability

AEGIS-128L and AEGIS-256 Usage Examples