Introduce header for mlkem-native's public API

[hanno-becker]

• Based on Remove backend name from default namespace #618

TLDR This PR aims to introduce a public header mlkem_native.h specifying the stable API of mlkem-native.

---

Application sources using an mlkem-native build should not have to
add the source tree of mlkem-native to the include paths. Instead,
there should be a single standaloe header sufficient to include
all necessary declarations.

Previously, this was not true: Applications would need to include
kem.h from the source tree, which in turn would pull in, for example,
config.h and cbmc.h.

On the other hand, the header of mlkem-native is not static, but
depends on information from the build, namely the security level
and the namespacing: The security level determines the sizes of
key material which callers need to know about. The namespacing
determines the name of the function symbols, which callers need
to know about.
It is therefore not possible to completely detach the mlkem-native
API header from the source tree used to build mlkem-native.

One way to address this is to merely require the build configuration
header to be included in the public API header. This works well for
single-level builds, but is inconvenient if the consumer wants to use
multiple instances of mlkem-native for different security levels; in
this case, including the public header multiple times would pull in
multiple configuration files, which would lead to clashes of #define's
clauses.
On the other hand, requiring the consumer to duplicate the level and
namespacing information in the API header is inconvenient for simple
tests or single-level builds.

This introduces a public API header mlkem-native.h, which addresses
the above as follows:

mlkem-native.h requires the build level and build namespace. By default,
it is obtained by including the underlying build configuration
(assumed to be present in the include paths). Alternatively, the user
can set BUILD_INFO_LVL and BUILD_INFO_NAMESPACE explicitly in mlkem-native.h,
and thereby avoid any dependency between mlkem-native.h and config.h.
In this setting, mlkem-native.h leaves no other traces than static size
declarations and build-specific API declarations. In particular, it can
be included multiple times.

This commit adjusts all tests and examples to no longer include kem.h,
but only mlkem-native.h. In all cases but the monolithic build example,
no further change is required, with the API header pulling the underlying
configuration automatically.

The monolithic build test examples/monolithic_build is adjusted as follows:
Where previously it included two instances of mlkem-native, it now includes
three, one per security level. The previous mlkem_native_all.c is renamed
to mlkem_native_monobuild.c, and is the source file needed for a monolithic
build of a single configuration. This is then included 3 times in mlkem_native_all.c.
To provide a header for this file, we include mlkem-native.h 3 times, using
manually set BUILD_INFO_LVL and BUILD_INFO_NAMESPACE to avoid nameclashes
from pulling in the full configuration.

[hanno-becker]

@bhess FYI. Feel free to chime in in terms of suitability for OQS.

[mkannwischer]

Thanks @hanno-becker - I think this a step in the right direction!
A few suggestions.

[oqs-bot]

Arm Cortex-A76 (Raspberry Pi 5) benchmarks

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	29007 cycles	29061 cycles	1.00
ML-KEM-512 encaps	35410 cycles	35384 cycles	1.00
ML-KEM-512 decaps	45885 cycles	45860 cycles	1.00
ML-KEM-768 keypair	49355 cycles	49388 cycles	1.00
ML-KEM-768 encaps	55585 cycles	55566 cycles	1.00
ML-KEM-768 decaps	70323 cycles	70304 cycles	1.00
ML-KEM-1024 keypair	72007 cycles	72050 cycles	1.00
ML-KEM-1024 encaps	80776 cycles	80825 cycles	1.00
ML-KEM-1024 decaps	100641 cycles	100700 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Intel Xeon 4th gen (c7i)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	13511 cycles	13522 cycles	1.00
ML-KEM-512 encaps	17274 cycles	17307 cycles	1.00
ML-KEM-512 decaps	22780 cycles	22850 cycles	1.00
ML-KEM-768 keypair	22532 cycles	22521 cycles	1.00
ML-KEM-768 encaps	24487 cycles	24448 cycles	1.00
ML-KEM-768 decaps	32411 cycles	32387 cycles	1.00
ML-KEM-1024 keypair	31416 cycles	31386 cycles	1.00
ML-KEM-1024 encaps	34941 cycles	34920 cycles	1.00
ML-KEM-1024 decaps	45735 cycles	45791 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

AMD EPYC 3rd gen (c6a)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	18124 cycles	18123 cycles	1.00
ML-KEM-512 encaps	23190 cycles	23219 cycles	1.00
ML-KEM-512 decaps	30488 cycles	30517 cycles	1.00
ML-KEM-768 keypair	31073 cycles	31112 cycles	1.00
ML-KEM-768 encaps	34149 cycles	34158 cycles	1.00
ML-KEM-768 decaps	44744 cycles	44736 cycles	1.00
ML-KEM-1024 keypair	44684 cycles	44735 cycles	1.00
ML-KEM-1024 encaps	50050 cycles	49899 cycles	1.00
ML-KEM-1024 decaps	64354 cycles	64342 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Intel Xeon 4th gen (c7i) (no-opt)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	34843 cycles	34896 cycles	1.00
ML-KEM-512 encaps	45058 cycles	45026 cycles	1.00
ML-KEM-512 decaps	58873 cycles	58961 cycles	1.00
ML-KEM-768 keypair	59236 cycles	59186 cycles	1.00
ML-KEM-768 encaps	71859 cycles	71842 cycles	1.00
ML-KEM-768 decaps	89334 cycles	89371 cycles	1.00
ML-KEM-1024 keypair	87292 cycles	87532 cycles	1.00
ML-KEM-1024 encaps	104393 cycles	104588 cycles	1.00
ML-KEM-1024 decaps	127371 cycles	127572 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Intel Xeon 3rd gen (c6i)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	20333 cycles	20329 cycles	1.00
ML-KEM-512 encaps	26988 cycles	27016 cycles	1.00
ML-KEM-512 decaps	35803 cycles	35820 cycles	1.00
ML-KEM-768 keypair	34886 cycles	34903 cycles	1.00
ML-KEM-768 encaps	38125 cycles	38130 cycles	1.00
ML-KEM-768 decaps	50957 cycles	50970 cycles	1.00
ML-KEM-1024 keypair	47974 cycles	47958 cycles	1.00
ML-KEM-1024 encaps	54153 cycles	54119 cycles	1.00
ML-KEM-1024 decaps	71583 cycles	71659 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

AMD EPYC 4th gen (c7a)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	15054 cycles	15058 cycles	1.00
ML-KEM-512 encaps	19650 cycles	19653 cycles	1.00
ML-KEM-512 decaps	26303 cycles	26288 cycles	1.00
ML-KEM-768 keypair	25434 cycles	25469 cycles	1.00
ML-KEM-768 encaps	27958 cycles	28135 cycles	0.99
ML-KEM-768 decaps	37642 cycles	37833 cycles	0.99
ML-KEM-1024 keypair	35798 cycles	35647 cycles	1.00
ML-KEM-1024 encaps	40966 cycles	40999 cycles	1.00
ML-KEM-1024 decaps	54489 cycles	54506 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Graviton4

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	18137 cycles	18133 cycles	1.00
ML-KEM-512 encaps	22146 cycles	22162 cycles	1.00
ML-KEM-512 decaps	28772 cycles	28770 cycles	1.00
ML-KEM-768 keypair	30569 cycles	30563 cycles	1.00
ML-KEM-768 encaps	33631 cycles	33618 cycles	1.00
ML-KEM-768 decaps	43156 cycles	43146 cycles	1.00
ML-KEM-1024 keypair	44203 cycles	44194 cycles	1.00
ML-KEM-1024 encaps	49671 cycles	49660 cycles	1.00
ML-KEM-1024 decaps	62637 cycles	62656 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Arm Cortex-A55 (Snapdragon 888) benchmarks

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	58363 cycles	58372 cycles	1.00
ML-KEM-512 encaps	65794 cycles	65796 cycles	1.00
ML-KEM-512 decaps	84509 cycles	84559 cycles	1.00
ML-KEM-768 keypair	98947 cycles	98974 cycles	1.00
ML-KEM-768 encaps	110458 cycles	110630 cycles	1.00
ML-KEM-768 decaps	136521 cycles	136899 cycles	1.00
ML-KEM-1024 keypair	150264 cycles	150000 cycles	1.00
ML-KEM-1024 encaps	166287 cycles	166967 cycles	1.00
ML-KEM-1024 decaps	202642 cycles	203193 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Graviton3

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	18975 cycles	18965 cycles	1.00
ML-KEM-512 encaps	23554 cycles	23590 cycles	1.00
ML-KEM-512 decaps	30651 cycles	30673 cycles	1.00
ML-KEM-768 keypair	32311 cycles	32290 cycles	1.00
ML-KEM-768 encaps	35891 cycles	35872 cycles	1.00
ML-KEM-768 decaps	46015 cycles	46043 cycles	1.00
ML-KEM-1024 keypair	46611 cycles	46612 cycles	1.00
ML-KEM-1024 encaps	52444 cycles	52449 cycles	1.00
ML-KEM-1024 decaps	66283 cycles	66245 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

AMD EPYC 3rd gen (c6a) (no-opt)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	52443 cycles	52177 cycles	1.01
ML-KEM-512 encaps	65398 cycles	65785 cycles	0.99
ML-KEM-512 decaps	88524 cycles	88423 cycles	1.00
ML-KEM-768 keypair	84299 cycles	84786 cycles	0.99
ML-KEM-768 encaps	102089 cycles	101479 cycles	1.01
ML-KEM-768 decaps	131299 cycles	132101 cycles	0.99
ML-KEM-1024 keypair	124700 cycles	124028 cycles	1.01
ML-KEM-1024 encaps	145185 cycles	145920 cycles	0.99
ML-KEM-1024 decaps	182693 cycles	183661 cycles	0.99

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Graviton2

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	29027 cycles	29059 cycles	1.00
ML-KEM-512 encaps	35362 cycles	35380 cycles	1.00
ML-KEM-512 decaps	45899 cycles	45897 cycles	1.00
ML-KEM-768 keypair	49384 cycles	49421 cycles	1.00
ML-KEM-768 encaps	55619 cycles	55568 cycles	1.00
ML-KEM-768 decaps	70382 cycles	70321 cycles	1.00
ML-KEM-1024 keypair	72055 cycles	72049 cycles	1.00
ML-KEM-1024 encaps	80885 cycles	80859 cycles	1.00
ML-KEM-1024 decaps	100744 cycles	100729 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

AMD EPYC 4th gen (c7a) (no-opt)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	45708 cycles	45715 cycles	1.00
ML-KEM-512 encaps	56855 cycles	56922 cycles	1.00
ML-KEM-512 decaps	76215 cycles	76247 cycles	1.00
ML-KEM-768 keypair	74505 cycles	74437 cycles	1.00
ML-KEM-768 encaps	88520 cycles	88528 cycles	1.00
ML-KEM-768 decaps	114367 cycles	114300 cycles	1.00
ML-KEM-1024 keypair	109292 cycles	109359 cycles	1.00
ML-KEM-1024 encaps	127280 cycles	127198 cycles	1.00
ML-KEM-1024 decaps	159892 cycles	159905 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Intel Xeon 3rd gen (c6i) (no-opt)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	56658 cycles	56667 cycles	1.00
ML-KEM-512 encaps	69441 cycles	69506 cycles	1.00
ML-KEM-512 decaps	91472 cycles	91492 cycles	1.00
ML-KEM-768 keypair	91875 cycles	91911 cycles	1.00
ML-KEM-768 encaps	107839 cycles	107825 cycles	1.00
ML-KEM-768 decaps	136427 cycles	136585 cycles	1.00
ML-KEM-1024 keypair	134768 cycles	134891 cycles	1.00
ML-KEM-1024 encaps	155354 cycles	155385 cycles	1.00
ML-KEM-1024 decaps	191640 cycles	191709 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Graviton4 (no-opt)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	42020 cycles	41962 cycles	1.00
ML-KEM-512 encaps	50104 cycles	50107 cycles	1.00
ML-KEM-512 decaps	66106 cycles	66079 cycles	1.00
ML-KEM-768 keypair	69187 cycles	69183 cycles	1.00
ML-KEM-768 encaps	79941 cycles	79958 cycles	1.00
ML-KEM-768 decaps	101131 cycles	101142 cycles	1.00
ML-KEM-1024 keypair	102232 cycles	102501 cycles	1.00
ML-KEM-1024 encaps	117217 cycles	117438 cycles	1.00
ML-KEM-1024 decaps	143450 cycles	143375 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Graviton3 (no-opt)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	45382 cycles	45387 cycles	1.00
ML-KEM-512 encaps	54226 cycles	54245 cycles	1.00
ML-KEM-512 decaps	71160 cycles	71158 cycles	1.00
ML-KEM-768 keypair	74937 cycles	74901 cycles	1.00
ML-KEM-768 encaps	86199 cycles	86136 cycles	1.00
ML-KEM-768 decaps	108670 cycles	108642 cycles	1.00
ML-KEM-1024 keypair	111099 cycles	111104 cycles	1.00
ML-KEM-1024 encaps	125925 cycles	125939 cycles	1.00
ML-KEM-1024 decaps	154587 cycles	154645 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Graviton2 (no-opt)

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	71316 cycles	71184 cycles	1.00
ML-KEM-512 encaps	85150 cycles	85120 cycles	1.00
ML-KEM-512 decaps	112658 cycles	112558 cycles	1.00
ML-KEM-768 keypair	117860 cycles	117715 cycles	1.00
ML-KEM-768 encaps	135501 cycles	135306 cycles	1.00
ML-KEM-768 decaps	172129 cycles	172149 cycles	1.00
ML-KEM-1024 keypair	175509 cycles	175075 cycles	1.00
ML-KEM-1024 encaps	197563 cycles	197201 cycles	1.00
ML-KEM-1024 decaps	243867 cycles	243455 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Bananapi bpi-f3 benchmarks

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	335094 cycles	335241 cycles	1.00
ML-KEM-512 encaps	445811 cycles	445831 cycles	1.00
ML-KEM-512 decaps	593881 cycles	594090 cycles	1.00
ML-KEM-768 keypair	556252 cycles	556387 cycles	1.00
ML-KEM-768 encaps	698112 cycles	698350 cycles	1.00
ML-KEM-768 decaps	889739 cycles	890991 cycles	1.00
ML-KEM-1024 keypair	821852 cycles	821999 cycles	1.00
ML-KEM-1024 encaps	999255 cycles	998751 cycles	1.00
ML-KEM-1024 decaps	1230113 cycles	1231111 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.

[oqs-bot]

Arm Cortex-A72 (Raspberry Pi 4) benchmarks

Benchmark suite	Current: 95dcffe	Previous: 1a95417	Ratio
ML-KEM-512 keypair	51684 cycles	51700 cycles	1.00
ML-KEM-512 encaps	58194 cycles	57994 cycles	1.00
ML-KEM-512 decaps	74272 cycles	73992 cycles	1.00
ML-KEM-768 keypair	87873 cycles	87545 cycles	1.00
ML-KEM-768 encaps	96545 cycles	96486 cycles	1.00
ML-KEM-768 decaps	119091 cycles	119532 cycles	1.00
ML-KEM-1024 keypair	132193 cycles	131846 cycles	1.00
ML-KEM-1024 encaps	145415 cycles	144831 cycles	1.00
ML-KEM-1024 decaps	176626 cycles	177016 cycles	1.00

This comment was automatically generated by workflow using github-action-benchmark.