[crypto/mlkem] Add main subroutines for ml-kem1024

[siemen11]

Add the main arithmetic and subroutines for the ml-kem1024 in the otbn.

[andrea-caforio]

Thanks @siemen11. ML-KEM is on the map now. :-) I did an initial review, haven't checked some of the logic-heavy parts yet.

[andrea-caforio]

Does this work without a dummy addition in between? Our Montgomery multiplier does not do the conditional subtraction, so 2 subsequent multiplications might be incorrect.

[siemen11]

The difference is that ML-KEM works on 12 bit values, not like ML-DSA with 24 bits, so we can leave the overflow unhandled for a bit

[andrea-caforio]

I see. The following addition is not a problem either I guess? Just to verify for myself because the operands for the addition are together larger than 2q but the addition is only well-defined for < 2q.

[siemen11]

The way I understand it is that the outputs from bn.mulvm are strictly bounded by q, so the sum of any two multiplication outputs is at most 2q

[andrea-caforio]

The output of the Montgomery mutiplier used to be in [0, q[ but that was removed in later versions of the SIMD extension.

https://opentitan.org/book/hw/ip/otbn/doc/isa.html#bnmulvmhttps://opentitan.org/book/hw/ip/otbn/doc/isa.html#bnmulvm

[siemen11]

The way that I understand it is that, we have a, b smaller than q and q = 3329, a 12 bit prime.

When we call bn.mulvm.8S, we calculate
r = (ab + mq)/2^32 <= floor((a*b - q)/2^32) + q (because m <= w^32 - 1, the Mont constant)
But because a, b < q, that floor is actually equal to 0, so r stays still smaller than q

Specifically, this is also mentioned in the docu:
"Note that when chaining multiplications, the conditional subtraction can be postponed until after the last multiplication in case the initial inputs are in [0, 2q[ and q < (2^d)/4 holds."

We have d = 32, and we have (2^d) / 4 = (2^32) / 4 = 2^30 and q = 2^12

[etterli]

I did some digging and I think the explanation of @siemen11 is correct (the w in m <= w^32 - 1 should be a 2). For ML-DSA is does not work because q is too big and the floor() is not 0. Because a*b = (q-1)^2 at most and s = (a*b - q) / 2^32 is > 1. This means that r <= q + s.

[etterli]

Thanks @siemen11 for bringing ML-KEM alive. I had a first view into the decode functions. Mainly added some comments about some specifics of OTBN instructions.

[etterli]

Thanks for the improvements on the decoding. I now reviewed also the encoding functions.

[etterli]

I reviewed the polynomial arithmetic operations. Nicely optimized computations.

[etterli]

I did some digging and I think the explanation of @siemen11 is correct (the w in m <= w^32 - 1 should be a 2). For ML-DSA is does not work because q is too big and the floor() is not 0. Because a*b = (q-1)^2 at most and s = (a*b - q) / 2^32 is > 1. This means that r <= q + s.

[etterli]

Do we need this or is in ML-KEM defined, similar to ML-DSA, that w31 is always 0?

[siemen11]

Decaps uses w31... I need to optimize this still and see whether I can move it out

[siemen11]

I left the w31 there for now, maybe later we can optimize it

[andrea-caforio]

Let's go. :-)