Skip to content

RFC: Add incremental encaps API to support ML-KEM Braid #1619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
mkannwischer wants to merge 2 commits into
base: main
Choose a base branch
from
+2,228 −316
Draft

RFC: Add incremental encaps API to support ML-KEM Braid #1619

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
80d95d5
Add ML-KEM Braid API
mkannwischer Jun 14, 2026
e9ea411
Correct namespacing definitions for mlkem braid test
rod-chapman Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion .github/actions/config-variations/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ inputs:
description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled,
pct-enabled-broken, custom-alloc-heap, custom-zeroize, native-cap-ON, native-cap-OFF, native-cap-ID_AA64PFR1_EL1,
native-cap-CPUID_AVX2, no-asm, serial-fips202, custom-randombytes, custom-memcpy, custom-memset, custom-stdlib,
nblocks-1, nblocks-2, nblocks-4'
mlkem-braid, nblocks-1, nblocks-2, nblocks-4'
required: false
default: 'all'
opt:
Expand Down Expand Up @@ -231,6 +231,21 @@ runs:
examples: false # Some examples use a custom config themselves
alloc: false # Requires custom config
rng_fail: true
- name: "ML-KEM Braid (incremental encapsulation API)"
if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'mlkem-braid') }}
uses: ./.github/actions/multi-functest
with:
gh_token: ${{ inputs.gh_token }}
compile_mode: native
cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"configs/test_mlkem_braid_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
func: true
kat: true
acvp: true
opt: ${{ inputs.opt }}
examples: false
alloc: false
rng_fail: true
- name: "MLKEM_GEN_MATRIX_NBLOCKS=1"
if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'nblocks-1') }}
uses: ./.github/actions/multi-functest
Expand Down
5 changes: 5 additions & 0 deletions .github/workflows/integration-pavona.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,11 @@ jobs:
echo "=== Patched extensions.bzl ==="
cat third_party/mlkem_native/extensions.bzl

- name: Update work buffer sizes
run: |
cd "$PAVONA_DIR"
git apply "$GITHUB_WORKSPACE/integration/pavona/update-alloc-sizes.patch"

- name: Patch functest to only test deterministic API
run: |
cd "$PAVONA_DIR"
Expand Down
2 changes: 2 additions & 0 deletions BIBLIOGRAPHY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ source code and documentation.
- [test/configs/no_asm_config.h](test/configs/no_asm_config.h)
- [test/configs/serial_fips202_config.h](test/configs/serial_fips202_config.h)
- [test/configs/test_alloc_config.h](test/configs/test_alloc_config.h)
- [test/configs/test_mlkem_braid_config.h](test/configs/test_mlkem_braid_config.h)

### `FIPS202`

Expand Down Expand Up @@ -154,6 +155,7 @@ source code and documentation.
- [test/configs/no_asm_config.h](test/configs/no_asm_config.h)
- [test/configs/serial_fips202_config.h](test/configs/serial_fips202_config.h)
- [test/configs/test_alloc_config.h](test/configs/test_alloc_config.h)
- [test/configs/test_mlkem_braid_config.h](test/configs/test_mlkem_braid_config.h)

### `HOL-Light`

Expand Down
10 changes: 10 additions & 0 deletions examples/basic_deterministic/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
10 changes: 10 additions & 0 deletions examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
10 changes: 10 additions & 0 deletions examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
10 changes: 10 additions & 0 deletions examples/custom_backend/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
10 changes: 10 additions & 0 deletions examples/monolithic_build/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
10 changes: 10 additions & 0 deletions examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
1 change: 1 addition & 0 deletions examples/monolithic_build_multilevel_native/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ CFLAGS := \
-Wno-long-long \
-Wno-unknown-pragmas \
-Wno-unused-command-line-argument \
-Wno-unused-function \
-O3 \
-fomit-frame-pointer \
-std=c99 \
Expand Down
10 changes: 10 additions & 0 deletions examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
10 changes: 10 additions & 0 deletions examples/monolithic_build_native/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
10 changes: 10 additions & 0 deletions examples/multilevel_build/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
10 changes: 10 additions & 0 deletions examples/multilevel_build_native/mlkem_native/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
27 changes: 27 additions & 0 deletions integration/pavona/update-alloc-sizes.patch
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
diff --git a/sw/device/lib/crypto/include/mlkem.h b/sw/device/lib/crypto/include/mlkem.h
index ee8c531..00f0887 100644
--- a/sw/device/lib/crypto/include/mlkem.h
+++ b/sw/device/lib/crypto/include/mlkem.h
@@ -33,16 +33,16 @@ enum {

// Work buffer sizes in 32-bit words
kOtcryptoMlkem512WorkBufferKeypairWords = 5824 / sizeof(uint32_t),
- kOtcryptoMlkem512WorkBufferEncapsWords = 8384 / sizeof(uint32_t),
- kOtcryptoMlkem512WorkBufferDecapsWords = 9152 / sizeof(uint32_t),
+ kOtcryptoMlkem512WorkBufferEncapsWords = 6304 / sizeof(uint32_t),
+ kOtcryptoMlkem512WorkBufferDecapsWords = 7072 / sizeof(uint32_t),

kOtcryptoMlkem768WorkBufferKeypairWords = 10176 / sizeof(uint32_t),
- kOtcryptoMlkem768WorkBufferEncapsWords = 13248 / sizeof(uint32_t),
- kOtcryptoMlkem768WorkBufferDecapsWords = 14336 / sizeof(uint32_t),
+ kOtcryptoMlkem768WorkBufferEncapsWords = 10656 / sizeof(uint32_t),
+ kOtcryptoMlkem768WorkBufferDecapsWords = 11744 / sizeof(uint32_t),

kOtcryptoMlkem1024WorkBufferKeypairWords = 15552 / sizeof(uint32_t),
- kOtcryptoMlkem1024WorkBufferEncapsWords = 19136 / sizeof(uint32_t),
- kOtcryptoMlkem1024WorkBufferDecapsWords = 20704 / sizeof(uint32_t),
+ kOtcryptoMlkem1024WorkBufferEncapsWords = 16032 / sizeof(uint32_t),
+ kOtcryptoMlkem1024WorkBufferDecapsWords = 17600 / sizeof(uint32_t),
};

/**
10 changes: 10 additions & 0 deletions mlkem/mlkem_native.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,9 @@
#undef MLK_CONTEXT_PARAMETERS_2
#undef MLK_CONTEXT_PARAMETERS_3
#undef MLK_CONTEXT_PARAMETERS_4
#undef MLK_CONTEXT_PARAMETERS_5
#undef MLK_CONTEXT_PARAMETERS_6
#undef MLK_CONTEXT_PARAMETERS_7
#undef MLK_EMPTY_CU
#undef MLK_ERR_FAIL
#undef MLK_ERR_OUT_OF_MEMORY
Expand All @@ -229,14 +232,21 @@
#undef mlk_gen_matrix
#undef mlk_indcpa_dec
#undef mlk_indcpa_enc
#undef mlk_indcpa_enc_u
#undef mlk_indcpa_enc_v
#undef mlk_indcpa_keypair_derand
/* mlkem/src/kem.h */
#undef MLKEM_EPP_BYTES
#undef MLKEM_POLY16_BYTES
#undef MLKEM_POLYVEC16_BYTES
#undef MLK_KEM_H
#undef mlk_kem_check_pk
#undef mlk_kem_check_sk
#undef mlk_kem_dec
#undef mlk_kem_enc
#undef mlk_kem_enc_derand
#undef mlk_kem_enc_derand_u
#undef mlk_kem_enc_v
#undef mlk_kem_keypair
#undef mlk_kem_keypair_derand
/* mlkem/src/params.h */
Expand Down
18 changes: 9 additions & 9 deletions mlkem/mlkem_native.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -477,17 +477,17 @@ int MLK_API_NAMESPACE(check_sk)(
*/
/* check-magic: off */
#define MLK_TOTAL_ALLOC_512_KEYPAIR_NO_PCT 5824
#define MLK_TOTAL_ALLOC_512_KEYPAIR_PCT 10048
#define MLK_TOTAL_ALLOC_512_ENCAPS 8384
#define MLK_TOTAL_ALLOC_512_DECAPS 9152
#define MLK_TOTAL_ALLOC_512_KEYPAIR_PCT 7968
#define MLK_TOTAL_ALLOC_512_ENCAPS 6304
#define MLK_TOTAL_ALLOC_512_DECAPS 7072
#define MLK_TOTAL_ALLOC_768_KEYPAIR_NO_PCT 10176
#define MLK_TOTAL_ALLOC_768_KEYPAIR_PCT 15552
#define MLK_TOTAL_ALLOC_768_ENCAPS 13248
#define MLK_TOTAL_ALLOC_768_DECAPS 14336
#define MLK_TOTAL_ALLOC_768_KEYPAIR_PCT 12960
#define MLK_TOTAL_ALLOC_768_ENCAPS 10656
#define MLK_TOTAL_ALLOC_768_DECAPS 11744
#define MLK_TOTAL_ALLOC_1024_KEYPAIR_NO_PCT 15552
#define MLK_TOTAL_ALLOC_1024_KEYPAIR_PCT 22400
#define MLK_TOTAL_ALLOC_1024_ENCAPS 19136
#define MLK_TOTAL_ALLOC_1024_DECAPS 20704
#define MLK_TOTAL_ALLOC_1024_KEYPAIR_PCT 19296
#define MLK_TOTAL_ALLOC_1024_ENCAPS 16032
#define MLK_TOTAL_ALLOC_1024_DECAPS 17600
/* check-magic: on */

/*
Expand Down
10 changes: 10 additions & 0 deletions mlkem/mlkem_native_asm.S
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,9 @@
#undef MLK_CONTEXT_PARAMETERS_2
#undef MLK_CONTEXT_PARAMETERS_3
#undef MLK_CONTEXT_PARAMETERS_4
#undef MLK_CONTEXT_PARAMETERS_5
#undef MLK_CONTEXT_PARAMETERS_6
#undef MLK_CONTEXT_PARAMETERS_7
#undef MLK_EMPTY_CU
#undef MLK_ERR_FAIL
#undef MLK_ERR_OUT_OF_MEMORY
Expand All @@ -253,14 +256,21 @@
#undef mlk_gen_matrix
#undef mlk_indcpa_dec
#undef mlk_indcpa_enc
#undef mlk_indcpa_enc_u
#undef mlk_indcpa_enc_v
#undef mlk_indcpa_keypair_derand
/* mlkem/src/kem.h */
#undef MLKEM_EPP_BYTES
#undef MLKEM_POLY16_BYTES
#undef MLKEM_POLYVEC16_BYTES
#undef MLK_KEM_H
#undef mlk_kem_check_pk
#undef mlk_kem_check_sk
#undef mlk_kem_dec
#undef mlk_kem_enc
#undef mlk_kem_enc_derand
#undef mlk_kem_enc_derand_u
#undef mlk_kem_enc_v
#undef mlk_kem_keypair
#undef mlk_kem_keypair_derand
/* mlkem/src/params.h */
Expand Down
10 changes: 10 additions & 0 deletions mlkem/mlkem_native_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,16 @@
*/
/* #define MLK_CONFIG_CONSTANTS_ONLY */

/******************************************************************************
* Name: MLK_CONFIG_ENABLE_MLKEM_BRAID
*
* Description: If this option is set, mlkem-native exposes the incremental
* encapsulation API (mlk_kem_enc_derand_u, mlk_kem_enc_v)
* needed for the ML-KEM Braid protocol.
*
*****************************************************************************/
/* #define MLK_CONFIG_ENABLE_MLKEM_BRAID */

/******************************************************************************
*
* Build-only configuration options
Expand Down
12 changes: 12 additions & 0 deletions mlkem/src/common.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,13 +205,25 @@
(arg0, arg1, arg2, context)
#define MLK_CONTEXT_PARAMETERS_4(arg0, arg1, arg2, arg3, context) \
(arg0, arg1, arg2, arg3, context)
#define MLK_CONTEXT_PARAMETERS_5(arg0, arg1, arg2, arg3, arg4, context) \
(arg0, arg1, arg2, arg3, arg4, context)
#define MLK_CONTEXT_PARAMETERS_6(a0, a1, a2, a3, a4, a5, context) \
(a0, a1, a2, a3, a4, a5, context)
#define MLK_CONTEXT_PARAMETERS_7(a0, a1, a2, a3, a4, a5, a6, context) \
(a0, a1, a2, a3, a4, a5, a6, context)
#else /* MLK_CONFIG_CONTEXT_PARAMETER */
#define MLK_CONTEXT_PARAMETERS_0(context) ()
#define MLK_CONTEXT_PARAMETERS_1(arg0, context) (arg0)
#define MLK_CONTEXT_PARAMETERS_2(arg0, arg1, context) (arg0, arg1)
#define MLK_CONTEXT_PARAMETERS_3(arg0, arg1, arg2, context) (arg0, arg1, arg2)
#define MLK_CONTEXT_PARAMETERS_4(arg0, arg1, arg2, arg3, context) \
(arg0, arg1, arg2, arg3)
#define MLK_CONTEXT_PARAMETERS_5(arg0, arg1, arg2, arg3, arg4, context) \
(arg0, arg1, arg2, arg3, arg4)
#define MLK_CONTEXT_PARAMETERS_6(a0, a1, a2, a3, a4, a5, context) \
(a0, a1, a2, a3, a4, a5)
#define MLK_CONTEXT_PARAMETERS_7(a0, a1, a2, a3, a4, a5, a6, context) \
(a0, a1, a2, a3, a4, a5, a6)
#endif /* !MLK_CONFIG_CONTEXT_PARAMETER */

#if defined(MLK_CONFIG_CONTEXT_PARAMETER_TYPE) != \
Expand Down
Loading
Loading