Implementation of XAES-256-GCM with EVP_AEAD #2809

ttungle96 · 2025-11-08T03:40:13Z

Issues:

Add EVP_AEAD API of XAES-256-GCM, which is extended AES-256-GCM with a derived key mode proposed by Filippo Valsorda in 2023, followed by a specification released in 2024.
This implementation uses an optimized CMAC dedicated to the specific use case of XAES-256-GCM from XAES-256-GCM #2652.
Support varying nonce sizes: 20 ≤ b ≤ 24 based on the extension: https://eprint.iacr.org/2025/758.pdf#page=24

Description of Changes

Implementation for API EVP_AEAD of XAES-256-GCM is appended to e_aes.c, and the tests are appended to aead_test.cc.

Testing

We use the test vectors provided here:
https://github.com/C2SP/C2SP/blob/main/XAES-256-GCM.md
https://github.com/C2SP/C2SP/blob/main/XAES-256-GCM/openssl/openssl.c
https://github.com/C2SP/C2SP/blob/main/XAES-256-GCM/go/XAES-256-GCM_test.go

./crypto_test --gtest_filter='All/PerAEADTest.*'
./crypto_test --gtest_filter='CipherTest.*'

Modifications compared with #2652

Optimize CMAC-based KDF: https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/crypto/fipsmodule/cipher/e_aes.c#L1809
Add full test cases based on Implementation of XAES-256-GCM with EVP_CIPHER #2750.
Adapt to varying tag sizes: https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/crypto/fipsmodule/cipher/e_aes.c#L1947
Support < 24-byte nonce sizes: https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/crypto/fipsmodule/cipher/e_aes.c#L1955, https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/crypto/fipsmodule/cipher/e_aes.c#L1992, https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/crypto/fipsmodule/cipher/e_aes.c#L2011.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

codecov-commenter · 2025-11-08T10:44:21Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.31%. Comparing base (706e60b) to head (29ae452).

Additional details and impacted files

@@               Coverage Diff                @@
##           xaes-256-gcm    #2809      +/-   ##
================================================
+ Coverage         78.27%   78.31%   +0.03%     
================================================
  Files               683      683              
  Lines            117356   117484     +128     
  Branches          16482    16488       +6     
================================================
+ Hits              91865    92002     +137     
+ Misses            24609    24601       -8     
+ Partials            882      881       -1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

dkostic · 2025-11-11T23:36:40Z

crypto/fipsmodule/cipher/e_aes.c

+// ------------------------------------------------------------------------------
+// ---------------- EVP_AEAD XAES-256-GCM Without Key Commitment ----------------
+// ------------------------------------------------------------------------------
+/* Since ctx->state capacity is 568 bytes, it does not have enough space 


what's ctx->state?

As I write in design doc: "state is a void pointer in the EVP_AEAD_CTX object pointing to an opaque memory that can be used to store implementation-specific data".
See this:
https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/include/openssl/aead.h#L223
https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/include/openssl/aead.h#L213

yes, but other people reading the code might not have access to your design doc :)

anyway, why don't you increase the size of ctx->state instead?

Since I'm not sure whether it is allowed to do so. Increasing the size of ctx->state will simplify the code. Should I follow that direction?

I think so, @nebeid what do you think about this?

Thanks! I just increased the size of ctx->state and cleaned allocate/free memory code.

It's better not to have a pointer, thanks, dkostic. On the other hand, do we need to have the gcm struct at all? What's different in using it compared to #2652 where it was created on the stack in the seal/open calls because nothing in it needs to be persisted between calls.
We're not considering yet reusing the gcm context, are you preparing for that usecase?

I removed struct aead_aes_gcm_ctx gcm_ctx from AEAD_XAES_256_GCM_CTX.

crypto/fipsmodule/cipher/e_aes.c

dkostic · 2025-11-11T23:39:33Z

crypto/fipsmodule/cipher/e_aes.c

+    AEAD_XAES_256_GCM_CTX *xaes_ctx = (AEAD_XAES_256_GCM_CTX*)&ctx->state;
+
+    // Allocate memory for xaes_ctx->gcm_ctx
+    xaes_ctx->gcm_ctx = OPENSSL_malloc(sizeof(struct aead_aes_gcm_ctx));


we should check that OPENSSL_malloc succeeded.

I'll add checking. The issue is it's hard to create a test case that could make it failed to increase test coverage.

that's ok, you can leave that particular code path untested.

crypto/fipsmodule/cipher/e_aes.c

nebeid · 2025-11-10T22:39:17Z

crypto/fipsmodule/cipher/e_aes.c

-    AES_encrypt(M1, derived_key, &xaes_ctx->xaes_key);
-    AES_encrypt(M2, derived_key + AES_BLOCK_SIZE, &xaes_ctx->xaes_key);
+    AES_encrypt(M, derived_key, xaes_key);
+    M[1] ^= 0x03;


A comment would be good to clarify the outcome of this XOR

Thanks! I added a comment!

nebeid · 2025-11-12T23:58:43Z

crypto/fipsmodule/cipher/e_aes.c

+// ------------------------------------------------------------------------------
+// ---------------- EVP_AEAD XAES-256-GCM Without Key Commitment ----------------
+// ------------------------------------------------------------------------------
+/* Since ctx->state capacity is 568 bytes, it does not have enough space 


It's better not to have a pointer, thanks, dkostic. On the other hand, do we need to have the gcm struct at all? What's different in using it compared to #2652 where it was created on the stack in the seal/open calls because nothing in it needs to be persisted between calls.
We're not considering yet reusing the gcm context, are you preparing for that usecase?

nebeid · 2025-11-13T00:42:49Z

tool/speed.cc

 #if AWSLC_API_VERSION > 16
       !SpeedKEM(selected) ||
 #endif
 #if AWSLC_API_VERSION > 31


The XAES APIs are introduced in

aws-lc/include/openssl/base.h

Line 117 in 368d499

#define AWSLC_API_VERSION 35

so maybe we need to introduce a new #if AWSLC_API_VERSION > 34 for them.

Thank you! I updated it.

nebeid · 2025-11-13T00:57:56Z

crypto/cipher_extra/aead_test.cc

+    // Test encryption and decryption with a plaintext
+    const uint8_t *plaintext = (const uint8_t *)"Hello, XAES-256-GCM!";
+    std::vector<uint8_t> ciphertext_and_tag;
+    DecodeHex(&ciphertext_and_tag, "01e5f78bc99de880bd2eeff2870d361f0eab5b2fc55268f34b14045878fe3668db980319");


Is this being used in the test? I don't see it in the arguments.
Where are the results from? The EVP implementation?

Yeah. They're redundant. Since for shorter nonce, we current only test to ensure encryption/decryption. I'll update. Thank you!

sgmenda-aws

some non-blocking remarks

sgmenda-aws · 2025-11-13T17:31:23Z

crypto/fipsmodule/cipher/e_aes.c

+    // Reference for nonce size < 24 bytes: 
+    // https://eprint.iacr.org/2025/758.pdf#page=24 
+    /* When nonce size b < 24 bytes, it uses bytes [b-12:b]
+     * of input nonce as iv for the underlying AES encryption. 
+     * nonce_len is b in the referece, where 20 <= b <= 24 */


this comment is repeated twice, here an in aead_xaes_256_gcm_open_gather. it would be clearer to make a helper function / macro that takes (nonce, nonce_len) and returns nonce + nonce_len - AES_GCM_NONCE_LENGTH and put the comment there.

Good suggestion! I'll change.

sgmenda-aws · 2025-11-13T17:38:19Z

include/openssl/aead.h

+// EVP_aead_xaes_256_gcm is AES-256 in Galois Counter Mode with CMAC-based KDF
+OPENSSL_EXPORT const EVP_AEAD *EVP_aead_xaes_256_gcm(void);


This is not a TLS-specific AEAD, so disambiguate. Also link to spec.

Suggested change

// EVP_aead_xaes_256_gcm is AES-256 in Galois Counter Mode with CMAC-based KDF

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_xaes_256_gcm(void);

// Other AEAD algorithms.

// EVP_aead_xaes_256_gcm is AES-256 in Galois Counter Mode with CMAC-based KDF, as specified in https://c2sp.org/XAES-256-GCM

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_xaes_256_gcm(void);

I'll move this next to EVP_aead_aes_256_gcm().

sgmenda-aws · 2025-11-13T17:38:40Z

tool/speed.cc

+#endif 
 #if AWSLC_API_VERSION > 31
-       !SpeedDigestSign(selected) ||
+       !SpeedDigestSign(selected) || 


Suggested change

!SpeedDigestSign(selected) ||

!SpeedDigestSign(selected) ||

crypto/cipher_extra/cipher_test.cc

github-actions

clang-tidy made some suggestions

crypto/obj/obj_dat.h

XAES_256_GCM EVP_AEAD

56a317d

ttungle96 requested a review from a team as a code owner November 8, 2025 03:40

XAES_256_GCM EVP_AEAD

b80917f

torben-hansen requested review from dkostic and nebeid November 8, 2025 04:42

ttungle96 added 3 commits November 10, 2025 12:39

Optimize CMAC

b6adb76

Update comments

21c9f90

Add nonce error case

d6f1c16

dkostic reviewed Nov 11, 2025

View reviewed changes

ttungle96 added 4 commits November 11, 2025 20:18

Add malloc/free memory checking

b36d383

Add comments/description

cba620d

Increase state size of EVP_AEAD_CTX

0bcb3f9

Add comments

3d3a12b

ttungle96 requested a review from dkostic November 12, 2025 21:09

dkostic previously approved these changes Nov 12, 2025

View reviewed changes

nebeid reviewed Nov 13, 2025

View reviewed changes

Remove gcm_ctx in AEAD_XAES_256_GCM_CTX

d8d40f6

ttungle96 dismissed dkostic’s stale review via d8d40f6 November 13, 2025 00:28

ttungle96 requested review from dkostic and nebeid November 13, 2025 00:31

nebeid reviewed Nov 13, 2025

View reviewed changes

Remove redundant code in test and put speed test at correct API version

16c6157

ttungle96 requested a review from nebeid November 13, 2025 01:05

nebeid previously approved these changes Nov 13, 2025

View reviewed changes

dkostic previously approved these changes Nov 13, 2025

View reviewed changes

refresh ci

4bc5381

sgmenda-aws reviewed Nov 13, 2025

View reviewed changes

skmcgrail and others added 2 commits November 13, 2025 11:02

Merge branch 'xaes-256-gcm' into xaes-256-gcm

8f805b6

Resolve comments of Sanketh

bba8f20

ttungle96 dismissed stale reviews from dkostic and nebeid via bba8f20 November 13, 2025 19:52

ttungle96 requested review from dkostic, nebeid and sgmenda-aws November 13, 2025 19:54

sgmenda-aws previously approved these changes Nov 13, 2025

View reviewed changes

dkostic previously approved these changes Nov 13, 2025

View reviewed changes

nebeid previously approved these changes Nov 13, 2025

View reviewed changes

Re-update obj_data.h

70cd651

ttungle96 dismissed stale reviews from nebeid, dkostic, and sgmenda-aws via 70cd651 November 13, 2025 22:57

github-actions bot reviewed Nov 13, 2025

View reviewed changes

crypto/obj/obj_dat.h Show resolved Hide resolved

ttungle96 requested review from dkostic, nebeid and sgmenda-aws November 13, 2025 23:04

dkostic previously approved these changes Nov 13, 2025

View reviewed changes

Apply suggestion from @sgmenda-aws

7fd931b

sgmenda-aws dismissed dkostic’s stale review via 7fd931b November 13, 2025 23:11

sgmenda-aws approved these changes Nov 13, 2025

View reviewed changes

dkostic approved these changes Nov 13, 2025

View reviewed changes

refresh ci

29ae452

torben-hansen merged commit 92b4227 into aws:xaes-256-gcm Nov 14, 2025
370 of 388 checks passed

ttungle96 deleted the xaes-256-gcm branch November 14, 2025 00:56

		// EVP_aead_xaes_256_gcm is AES-256 in Galois Counter Mode with CMAC-based KDF
		OPENSSL_EXPORT const EVP_AEAD *EVP_aead_xaes_256_gcm(void);

Implementation of XAES-256-GCM with EVP_AEAD #2809

Implementation of XAES-256-GCM with EVP_AEAD #2809

Uh oh!

Conversation

ttungle96 commented Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issues:

Description of Changes

Testing

Modifications compared with #2652

Uh oh!

codecov-commenter commented Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ttungle96 Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ttungle96 Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sgmenda-aws left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ttungle96 Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ttungle96 Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ttungle96 commented Nov 8, 2025 •

edited

Loading

codecov-commenter commented Nov 8, 2025 •

edited

Loading

ttungle96 Nov 12, 2025 •

edited

Loading

ttungle96 Nov 13, 2025 •

edited

Loading

ttungle96 Nov 13, 2025 •

edited

Loading

ttungle96 Nov 13, 2025 •

edited

Loading