If you have been looking around wolfcrypt’s APIs and source code you might have noticed that both wc_MlDsaKey_Sign() and wc_MlDsaKey_SignCtx() exist and you might wonder about the difference.
TL;DR
wc_MlDsaKey_SignCtx() differs from wc_MlDsaKey_Sign() in that it adds a 1 byte marker (0x00), a length specifier for the context string, and a context string.
If you’re not sure which one to use then you probably want to use wc_MlDsaKey_SignCtx(). If you’re not sure what the context should be, you should use a NULL pointer and specify a length of 0.
The Details
ctx is the FIPS 204 context string, an optionally provided application-supplied domain separator of up to 255 bytes that is mixed into the message before signing. Signer and verifier must pass the same ctx or verification fails. Most applications pass a NULL pointer for ctx and 0 for length which is what wolfSSL’s own TLS 1.3 and X.509 code does.
This was added as part of the FIPS 204 standardization process; so before that (when the algorithm was called Dilthium) there was no context string and 0x00 marker. wc_MlDsaKey_Sign() does that. We keep wc_MlDsaKey_Sign() for our customers that were early adopter customers so they can continue to interoperate with their earlier software.
To be as specific and clear as possible, ML-DSA has a pre-conditioning step. Before FIPS-204 standardization it looked like this in wc_MlDsaKey_Sign() :
tr || msg
For FIPS-204 it looks like this:
tr || 0x00 || ctxLen || ctx || msg
Where:
tr = SHAKE_256(publicKey)
ctx = context string passed in (must be shorter than 255 bytes)
ctxLen = context string length
msg = the message to be signed
In both cases, the result is then signed in the same way.
Still not sure which API you should be using? Give us a shout, and we’ll help you out!
Note that since FIPS 204 is the standardized way to sign and verify, we will eventually deprecate wc_MlDsaKey_Sign(). We are currently monitoring customer usage of these APIs, and once none are using this API any longer, it will be deprecated. That said, if you are an open-source user of wolfCrypt and you are calling this function, please do get in touch with us to let us know.
If you have questions about any of the above, please contact us at facts@wolfssl.com or call us at +1 425 245 8247.
Download wolfSSL Now