Add EVP_CIPHER API for XAES-256-GCM with Key Commitment #2826

ttungle96 · 2025-11-14T01:28:43Z

Add 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. The key commitment extension follows https://eprint.iacr.org/2025/758.pdf#page=6.
This implementation supports EVP_CIPHER API and uses an optimized CMAC dedicated to the specific use case of XAES-256-GCM from XAES-256-GCM #2652 to derive subkeys and key commitments.
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_CIPHER of XAES-256-GCM with Key Commitment is appended to e_aes.c
The tests are appended to cipher_tests.txt.
TestCipherAPI (https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/crypto/cipher_extra/cipher_test.cc#L184) and TestCipher (https://github.com/ttungle96/aws-lc/blob/xaes-256-gcm/crypto/cipher_extra/cipher_test.cc#L473) in cipher_test.cc is added a parameter named kc at the end with default value to support testing cipher with key commitment without disrupting legacy code.

Testing

Reuse the test vectors in #2750 with our own added key commitment values.

Evaluation

Performance evaluation with speedtool on c6i.2xlarge (8 vCPUs and 16 GB RAM):

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

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.

github-actions

clang-tidy made some suggestions

github-actions · 2025-11-14T01:32:57Z

crypto/obj/obj_dat.h

-#define NUM_NID 1000
+#define NUM_NID 1001

 static const uint8_t kObjectData[] = {


warning: unknown type name 'uint8_t' [clang-diagnostic-error]

static const uint8_t kObjectData[] = { ^

github-actions · 2025-11-14T01:32:57Z

crypto/obj/obj_dat.h

+    0x32,
 };

 static const ASN1_OBJECT kObjects[NUM_NID] = {


warning: unknown type name 'ASN1_OBJECT' [clang-diagnostic-error]

static const ASN1_OBJECT kObjects[NUM_NID] = { ^

codecov-commenter · 2025-11-14T02:12:44Z

Codecov Report

❌ Patch coverage is 93.33333% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.32%. Comparing base (92b4227) to head (bfc193c).

Files with missing lines	Patch %	Lines
crypto/fipsmodule/cipher/e_aes.c	91.78%	6 Missing ⚠️
crypto/cipher_extra/cipher_test.cc	96.87%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@               Coverage Diff                @@
##           xaes-256-gcm    #2826      +/-   ##
================================================
+ Coverage         78.30%   78.32%   +0.01%     
================================================
  Files               683      683              
  Lines            117484   117572      +88     
  Branches          16489    16499      +10     
================================================
+ Hits              92000    92086      +86     
- Misses            24602    24604       +2     
  Partials            882      882

☔ 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.

nebeid

I will review cipher_test.cc

nebeid · 2025-11-18T23:12:26Z

crypto/fipsmodule/cipher/e_aes.c

+#if defined(OPENSSL_32_BIT)
+    assert((uintptr_t)ptr % 4 == 0);
+    ptr += (uintptr_t)ptr & 4;
+#endif
+    assert((uintptr_t)ptr % 8 == 0);
+    ptr += (uintptr_t)ptr & 8;


I doubt we need these alignment requirements in addition to those of the gcm ctx. Can we try removing them here and on line 1858? Otherwise, do you know what would drive our need for them?

It will lead to many CI tests failed. I tried that. You can see the failed tests below. However, when I created and run with a docker, all tests still passed.

nebeid · 2025-11-18T23:56:42Z

crypto/fipsmodule/cipher/e_aes.c

+
+    XAES_256_GCM_KC_CTX *xaes_ctx = xaes_256_gcm_kc_from_cipher_ctx(ctx);
+
+    switch(type) {


I think it's more prudent to check that ptr is not NULL.
I see that there are no checks in aes_gcm_ctrl, but it's good to verify here and we should probably change there as well wherever it's used. It's sometimes intentionally NULL as in the INIT case in

aws-lc/crypto/fipsmodule/cipher/cipher.c

Line 185 in 88aec89

if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_INIT, 0, NULL)) {

Yes. I'll add checking ptr for two new added ctrl commands.

nebeid · 2025-11-18T23:58:25Z

crypto/cipher_extra/test/cipher_tests.txt

 AAD = 633273702e6f72672f584145532d3235362d47434d
 Tag = 7fd083bf3fdb41abd740a21f71eb769d

+# Note: KC are our own test values


Is it possible to use the same set of tests as the ones without KC and the test harness just ignores it when it's plain XAES?

Does that mean I should remove all changes that were made to cipher_test.cc to support key commitment verification?

No, sorry, what I meant is if you were to unify the 2 sets of test vectors in this file (i.e. delete the ones above of XAES-256-GCM because they're superseded by the KC one), would they then work with both XAES and XAES-KC? It seems to me that XAES may not be tested in CipherFileTest because it needs its own "Cipher" string. So you can ignore the suggestion.

Yes. It needs to have "Cipher = XAES-256-GCM-KC" to specify the cipher.

nebeid · 2025-11-19T15:42:18Z

crypto/fipsmodule/cipher/e_aes.c

    case NID_xaes_256_gcm: 
      assert(ctx->cipher->ctx_size == sizeof(XAES_256_GCM_CTX));
      ptr = ctx->cipher_data;
-#if defined(OPENSSL_32_BIT)


In my previous comment, I meant keeping this alignment in aes_gcm_from_cipher_ctx and try and remove them from the ones below, but maybe it doesn't make sense because it's the same pointer to ctx->cipher_data and it would be different if you're not doing the same operations to get it.

Yeah. Since aes_gcm_from_cipher_ctx() is called in other places like aes_gcm_cipher(), aes_gcm_ctrl(), and aes_gcm_init_key(), it needs to be consistent everywhere.

nebeid · 2025-11-19T15:45:40Z

include/openssl/cipher.h

-// We're introducing a new error code for invalid key commitment
+// We're introducing a new error code for invalid key commitment and invalid buffer
 #define CIPHER_R_KEY_COMMITMENT_INVALID 145
+#define CIPHER_R_BUFFER_INVALID 146


You can use

aws-lc/crypto/internal.h

Line 1447 in 88aec89

#define GUARD_PTR(ptr) __AWS_LC_ENSURE((ptr) != NULL, OPENSSL_PUT_ERROR(CRYPTO, ERR_R_PASSED_NULL_PARAMETER); \

and no need to introduce a new error.

Thank you! I replaced that directive in my update and deleted CIPHER_R_BUFFER_INVALID.

nebeid · 2025-11-19T15:46:55Z

crypto/cipher_extra/test/cipher_tests.txt

 AAD = 633273702e6f72672f584145532d3235362d47434d
 Tag = 7fd083bf3fdb41abd740a21f71eb769d

+# Note: KC are our own test values


No, sorry, what I meant is if you were to unify the 2 sets of test vectors in this file (i.e. delete the ones above of XAES-256-GCM because they're superseded by the KC one), would they then work with both XAES and XAES-KC? It seems to me that XAES may not be tested in CipherFileTest because it needs its own "Cipher" string. So you can ignore the suggestion.

nebeid · 2025-11-19T15:57:16Z

crypto/cipher_extra/cipher_test.cc

Can the negative tests that were added for XAES (e.g. shorter nonces) be modified to also test XAES-KC?

I made changes in cipher_test.cc to test negative cases with invalid key/nonce, and shorter nonce for both evp-xaes-256-gcm and evp-xaes-256-gcm-kc.

Add EVP_CIPHER API XAES-256-GCM with Key Commitment

0a3768b

ttungle96 requested a review from a team as a code owner November 14, 2025 01:28

github-actions bot reviewed Nov 14, 2025

View reviewed changes

Add comment optimized Key Commitment

35defa9

ttungle96 added 3 commits November 13, 2025 18:27

Edit comments

28e379f

Naming

ff9b2ec

re-run generate_build_files.py

a7ccfc5

torben-hansen requested review from dkostic and nebeid November 14, 2025 14:56

ttungle96 force-pushed the xaes-256-gcm branch from 043f78e to a7ccfc5 Compare November 14, 2025 16:46

Update

01a9681

ttungle96 force-pushed the xaes-256-gcm branch 2 times, most recently from a594eb1 to 01a9681 Compare November 14, 2025 19:43

nebeid reviewed Nov 18, 2025

View reviewed changes

Update

d80c7d2

nebeid reviewed Nov 19, 2025

View reviewed changes

ttungle96 added 5 commits November 19, 2025 08:48

Go back

4e92f5d

Add negative tests

e882576

Reorder

c285850

Delete CIPHER_R_BUFFER_INVALID

417325b

refresh ci

cdfdb87

ttungle96 requested a review from nebeid November 19, 2025 22:05

Add EVP-XAES-256-GCM-KC to speedtool

bfc193c

nebeid approved these changes Nov 20, 2025

View reviewed changes

dkostic approved these changes Nov 20, 2025

View reviewed changes

torben-hansen merged commit a6e811c into aws:xaes-256-gcm Nov 20, 2025
369 of 388 checks passed

ttungle96 deleted the xaes-256-gcm branch November 20, 2025 18:21


		XAES_256_GCM_KC_CTX *xaes_ctx = xaes_256_gcm_kc_from_cipher_ctx(ctx);

		switch(type) {

Add EVP_CIPHER API for XAES-256-GCM with Key Commitment #2826

Add EVP_CIPHER API for XAES-256-GCM with Key Commitment #2826

Uh oh!

Conversation

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

Uh oh!

Description of Changes

Testing

Evaluation

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

nebeid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ttungle96 Nov 19, 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!

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!

ttungle96 Nov 19, 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ttungle96 commented Nov 14, 2025 •

edited

Loading

codecov-commenter commented Nov 14, 2025 •

edited

Loading

ttungle96 Nov 19, 2025 •

edited

Loading

ttungle96 Nov 19, 2025 •

edited

Loading