Add sodium_crypto_stream_xchacha20_xor_ic()

There are many use-cases where a PHP user is currently using sodium_compat's implementation of this low-level XChaCha20 API. For example, multi-part message processing (in low-memory settings) for a ciphertext that was encrypted with XChaCha20-Poly1305 (rather than the secretstream API).

Adding this function to ext/sodium offers better performance and lowers users' memory usage with the polyfill, and ensures that users coming from other languages that provide libsodium bindings have a more consistent experience with our bindings. This is a win-win.

This patch follows the libsodium precedent of adding functions instead of optional parameters to existing functions. The parameter order is also consistent with the C API.

https://doc.libsodium.org/advanced/stream_ciphers/xchacha20#usage

Closes GH-8276.

Author: paragonie-security

NEWS

@@ -26,6 +26,9 @@ PHP                                                                        NEWS
   . Fixed bug #80909 (crash with persistent connections in PDO_ODBC). (Calvin
     Buckley)
 
+- Sodium:
+  . Added sodium_crypto_stream_xchacha20_xor_ic(). (Scott)
+
 - Standard:
   . net_get_interfaces() also reports wireless network interfaces on Windows.
     (Yurun)

UPGRADING

@@ -114,6 +114,9 @@ PHP 8.2 UPGRADE NOTES
 6. New Functions
 ========================================
 
+- Sodium:
+  . sodium_crypto_stream_xchacha20_xor_ic()
+
 - Standard:
   . The peak memory usage can now be reset to the current usage thanks to
     memory_reset_peak_usage().

ext/sodium/libsodium.c

@@ -1578,6 +1578,49 @@ PHP_FUNCTION(sodium_crypto_stream_xchacha20_xor)
 
 	RETURN_NEW_STR(ciphertext);
 }
+
+PHP_FUNCTION(sodium_crypto_stream_xchacha20_xor_ic)
+{
+	zend_string   *ciphertext;
+	unsigned char *key;
+	unsigned char *msg;
+	unsigned char *nonce;
+	zend_long     *ic;
+
+	size_t         ciphertext_len;
+	size_t         key_len;
+	size_t         msg_len;
+	size_t         nonce_len;
+
+	if (zend_parse_parameters(ZEND_NUM_ARGS(), "ssls",
+									&msg, &msg_len,
+									&nonce, &nonce_len,
+									&ic,
+									&key, &key_len) == FAILURE) {
+		sodium_remove_param_values_from_backtrace(EG(exception));
+		RETURN_THROWS();
+	}
+	if (nonce_len != crypto_stream_xchacha20_NONCEBYTES) {
+		zend_argument_error(sodium_exception_ce, 2, "must be SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES bytes long");
+		RETURN_THROWS();
+	}
+	if (key_len != crypto_stream_xchacha20_KEYBYTES) {
+		zend_argument_error(sodium_exception_ce, 3, "must be SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES bytes long");
+		RETURN_THROWS();
+	}
+	ciphertext_len = msg_len;
+	ciphertext = zend_string_checked_alloc((size_t) ciphertext_len, 0);
+	if (crypto_stream_xchacha20_xor_ic((unsigned char *) ZSTR_VAL(ciphertext), msg,
+									   (unsigned long long) msg_len, nonce,
+									   (unsigned long long) ic, key) != 0) {
+		zend_string_free(ciphertext);
+		zend_throw_exception(sodium_exception_ce, "internal error", 0);
+		RETURN_THROWS();
+	}
+	ZSTR_VAL(ciphertext)[ciphertext_len] = 0;
+
+	RETURN_NEW_STR(ciphertext);
+}
 #endif
 
 #ifdef crypto_pwhash_SALTBYTES

ext/sodium/libsodium.stub.php

@@ -205,6 +205,8 @@ function sodium_crypto_stream_xchacha20(int $length, string $nonce, string $key)
 function sodium_crypto_stream_xchacha20_keygen(): string {}
 
 function sodium_crypto_stream_xchacha20_xor(string $message, string $nonce, string $key): string {}
+
+function sodium_crypto_stream_xchacha20_xor_ic(string $message, string $nonce, int $counter, string $key): string {}
 #endif
 
 function sodium_add(string &$string1, string $string2): void {}

ext/sodium/libsodium_arginfo.h

@@ -445,6 +445,15 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_sodium_crypto_stream_xchacha20_x
 ZEND_END_ARG_INFO()
 #endif
 
+#if defined(crypto_stream_xchacha20_KEYBYTES)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_sodium_crypto_stream_xchacha20_xor_ic, 0, 4, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, message, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, nonce, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, counter, IS_LONG, 0)
+	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
+ZEND_END_ARG_INFO()
+#endif
+
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_sodium_add, 0, 2, IS_VOID, 0)
 	ZEND_ARG_TYPE_INFO(1, string1, IS_STRING, 0)
 	ZEND_ARG_TYPE_INFO(0, string2, IS_STRING, 0)
@@ -662,6 +671,9 @@ ZEND_FUNCTION(sodium_crypto_stream_xchacha20_keygen);
 #if defined(crypto_stream_xchacha20_KEYBYTES)
 ZEND_FUNCTION(sodium_crypto_stream_xchacha20_xor);
 #endif
+#if defined(crypto_stream_xchacha20_KEYBYTES)
+ZEND_FUNCTION(sodium_crypto_stream_xchacha20_xor_ic);
+#endif
 ZEND_FUNCTION(sodium_add);
 ZEND_FUNCTION(sodium_compare);
 ZEND_FUNCTION(sodium_increment);
@@ -844,6 +856,9 @@ static const zend_function_entry ext_functions[] = {
 #endif
 #if defined(crypto_stream_xchacha20_KEYBYTES)
 	ZEND_FE(sodium_crypto_stream_xchacha20_xor, arginfo_sodium_crypto_stream_xchacha20_xor)
+#endif
+#if defined(crypto_stream_xchacha20_KEYBYTES)
+	ZEND_FE(sodium_crypto_stream_xchacha20_xor_ic, arginfo_sodium_crypto_stream_xchacha20_xor_ic)
 #endif
 	ZEND_FE(sodium_add, arginfo_sodium_add)
 	ZEND_FE(sodium_compare, arginfo_sodium_compare)

ext/sodium/tests/crypto_stream_xchacha20.phpt

@@ -34,6 +34,22 @@ $stream6 = sodium_crypto_stream_xchacha20_xor($stream5, $nonce, $key);
 
 var_dump($stream6 === $stream);
 
+// New test (with Initial Counter feature):
+$n2 = random_bytes(SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES);
+$left  = str_repeat("\x01", 64);
+$right = str_repeat("\xfe", 64);
+
+// All at once:
+$stream7_unified = sodium_crypto_stream_xchacha20_xor($left . $right, $n2, $key);
+
+// Piecewise, with initial counter:
+$stream7_left  = sodium_crypto_stream_xchacha20_xor_ic($left, $n2, 0, $key);
+$stream7_right = sodium_crypto_stream_xchacha20_xor_ic($right, $n2, 1, $key);
+$stream7_concat = $stream7_left . $stream7_right;
+
+var_dump(strlen($stream7_concat));
+var_dump($stream7_unified === $stream7_concat);
+
 try {
     sodium_crypto_stream_xchacha20(-1, $nonce, $key);
 } catch (SodiumException $ex) {
@@ -71,6 +87,8 @@ bool(true)
 bool(true)
 bool(true)
 bool(true)
+int(128)
+bool(true)
 sodium_crypto_stream_xchacha20(): Argument #1 ($length) must be greater than 0
 sodium_crypto_stream_xchacha20(): Argument #2 ($nonce) must be SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES bytes long
 sodium_crypto_stream_xchacha20(): Argument #3 ($key) must be SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES bytes long