From 74eae01aaa3f6f2169723cc6e80784fca39f0588 Mon Sep 17 00:00:00 2001
From: Louis-Arnaud Catoire <la.catoire@gmail.com>
Date: Sun, 16 Aug 2026 19:46:10 +0200
Subject: [PATCH] sodium: document the 8.4 aarch64 support for AES-256-GCM

Before PHP 8.4 the HAVE_AESGCM guard in ext/sodium/libsodium.c covered
x86 and x86_64 only. PHP 8.4 extends it to __aarch64__ and _M_ARM64
(php-src #12867, commit 1816403d84). On aarch64 this means
sodium_crypto_aead_aes256gcm_is_available() may now return true, and the
encrypt, decrypt and keygen functions and the
SODIUM_CRYPTO_AEAD_AES256GCM_* constants are now defined at all.

The changelog table shared by the encrypt, decrypt and keygen pages is
declared once as sodium.changelog.aes256gcm-aarch64 in
language-snippets.ent. The previously empty descriptions of the four
constants are filled in as well.
---
 language-snippets.ent                         | 23 +++++++++++++++++
 reference/sodium/constants.xml                |  8 ++++++
 .../sodium-crypto-aead-aes256gcm-decrypt.xml  |  5 ++++
 .../sodium-crypto-aead-aes256gcm-encrypt.xml  |  5 ++++
 ...ium-crypto-aead-aes256gcm-is-available.xml | 25 +++++++++++++++++++
 .../sodium-crypto-aead-aes256gcm-keygen.xml   |  5 ++++
 6 files changed, 71 insertions(+)

diff --git a/language-snippets.ent b/language-snippets.ent
index fed94ed48f2e..c6e8392e26e4 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -4496,6 +4496,29 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
    </simpara>
 '>
 
+<!-- Sodium -->
+<!ENTITY sodium.changelog.aes256gcm-aarch64 '
+  <informaltable xmlns="http://docbook.org/ns/docbook">
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       This function is now also defined on aarch64.
+       Previously it was only defined on x86 and x86_64.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+'>
+
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
diff --git a/reference/sodium/constants.xml b/reference/sodium/constants.xml
index d4fbda7841ec..55343ef6d980 100644
--- a/reference/sodium/constants.xml
+++ b/reference/sodium/constants.xml
@@ -169,6 +169,8 @@
    </term>
    <listitem>
     <simpara>
+     Only defined on platforms where AES-256-GCM support is compiled in.
+     Defined on aarch64 as of PHP 8.4.0.
     </simpara>
    </listitem>
   </varlistentry>
@@ -179,6 +181,8 @@
    </term>
    <listitem>
     <simpara>
+     Only defined on platforms where AES-256-GCM support is compiled in.
+     Defined on aarch64 as of PHP 8.4.0.
     </simpara>
    </listitem>
   </varlistentry>
@@ -189,6 +193,8 @@
    </term>
    <listitem>
     <simpara>
+     Only defined on platforms where AES-256-GCM support is compiled in.
+     Defined on aarch64 as of PHP 8.4.0.
     </simpara>
    </listitem>
   </varlistentry>
@@ -199,6 +205,8 @@
    </term>
    <listitem>
     <simpara>
+     Only defined on platforms where AES-256-GCM support is compiled in.
+     Defined on aarch64 as of PHP 8.4.0.
     </simpara>
    </listitem>
   </varlistentry>
diff --git a/reference/sodium/functions/sodium-crypto-aead-aes256gcm-decrypt.xml b/reference/sodium/functions/sodium-crypto-aead-aes256gcm-decrypt.xml
index 6e4a5ecd8cc3..dbc516a70273 100644
--- a/reference/sodium/functions/sodium-crypto-aead-aes256gcm-decrypt.xml
+++ b/reference/sodium/functions/sodium-crypto-aead-aes256gcm-decrypt.xml
@@ -69,6 +69,11 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  &sodium.changelog.aes256gcm-aarch64;
+ </refsect1>
+
 
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/sodium/functions/sodium-crypto-aead-aes256gcm-encrypt.xml b/reference/sodium/functions/sodium-crypto-aead-aes256gcm-encrypt.xml
index d6ee383f4ccf..374605bf15b0 100644
--- a/reference/sodium/functions/sodium-crypto-aead-aes256gcm-encrypt.xml
+++ b/reference/sodium/functions/sodium-crypto-aead-aes256gcm-encrypt.xml
@@ -68,6 +68,11 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  &sodium.changelog.aes256gcm-aarch64;
+ </refsect1>
+
 
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/sodium/functions/sodium-crypto-aead-aes256gcm-is-available.xml b/reference/sodium/functions/sodium-crypto-aead-aes256gcm-is-available.xml
index bc592dae462e..ac430592ae53 100644
--- a/reference/sodium/functions/sodium-crypto-aead-aes256gcm-is-available.xml
+++ b/reference/sodium/functions/sodium-crypto-aead-aes256gcm-is-available.xml
@@ -30,6 +30,31 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       This function may now return &true; on aarch64 CPUs with the ARM
+       cryptographic extensions.
+       Previously, hardware-accelerated AES-256-GCM was only detected on x86
+       and x86_64, and this function always returned &false; on aarch64.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
 
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/sodium/functions/sodium-crypto-aead-aes256gcm-keygen.xml b/reference/sodium/functions/sodium-crypto-aead-aes256gcm-keygen.xml
index 6aa3113097b9..021ffa1bd35b 100644
--- a/reference/sodium/functions/sodium-crypto-aead-aes256gcm-keygen.xml
+++ b/reference/sodium/functions/sodium-crypto-aead-aes256gcm-keygen.xml
@@ -31,6 +31,11 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  &sodium.changelog.aes256gcm-aarch64;
+ </refsect1>
+
 
 </refentry>
 <!-- Keep this comment at the end of the file