Skip to content

Commit 1be3f64

Browse files
kojo1kojo1
committed
API doc: ML-DSA, ML-KEM
1 parent c71a4dd commit 1be3f64

4 files changed

Lines changed: 773 additions & 1 deletion

File tree

‎doc/dox_comments/header_files/dilithium.h‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
/*!
2+
\ingroup MLDSA
3+
4+
\brief This macro initializes a provided MlDsaKey structure.
5+
6+
MlDsaKey is an alias of dilithium_key. This macro maps to
7+
wc_dilithium_init_ex().
8+
9+
\return 0 Returned upon successfully initializing the key structure
10+
\return BAD_FUNC_ARGS Returned if the key pointer evaluates to NULL
11+
\return MEMORY_E Returned if memory allocation fails (when applicable)
12+
13+
\param key pointer to the MlDsaKey structure to initialize
14+
\param heap pointer to a heap identifier, for use with memory overrides
15+
\param devId ID to use with crypto callbacks or async hardware.
16+
Set to INVALID_DEVID (-2) if not used.
17+
18+
_Example_
19+
\code
20+
MlDsaKey key;
21+
wc_MlDsaKey_Init(&key, NULL, INVALID_DEVID);
22+
\endcode
23+
24+
\sa wc_MlDsaKey_Free
25+
\sa wc_MlDsaKey_SetParams
26+
*/
27+
int wc_MlDsaKey_Init(MlDsaKey *key, void *heap, int devId);
28+
29+
/*!
30+
\ingroup MLDSA
31+
32+
\brief This macro sets the ML-DSA parameter set on an initialized MlDsaKey.
33+
34+
Supported parameter identifiers include:
35+
- WC_ML_DSA_44
36+
- WC_ML_DSA_65
37+
- WC_ML_DSA_87
38+
(Draft variants may also be available depending on build.)
39+
40+
This macro maps to wc_dilithium_set_level().
41+
42+
\return 0 Returned upon success
43+
\return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent)
44+
45+
\param key pointer to the initialized MlDsaKey structure
46+
\param id parameter set identifier (e.g., WC_ML_DSA_44 / _65 / _87)
47+
48+
_Example_
49+
\code
50+
wc_MlDsaKey_SetParams(&key, WC_ML_DSA_65);
51+
\endcode
52+
53+
\sa wc_MlDsaKey_GetParams
54+
\sa wc_MlDsaKey_MakeKey
55+
*/
56+
int wc_MlDsaKey_SetParams(MlDsaKey *key, byte id);
57+
58+
/*!
59+
\ingroup MLDSA
60+
61+
\brief This macro gets the ML-DSA parameter set configured in the key.
62+
63+
This macro maps to wc_dilithium_get_level().
64+
65+
\return 0 Returned upon success
66+
\return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent)
67+
68+
\param key pointer to the initialized MlDsaKey structure
69+
\param id output pointer receiving the current parameter set identifier
70+
71+
\sa wc_MlDsaKey_SetParams
72+
*/
73+
int wc_MlDsaKey_GetParams(MlDsaKey *key, byte id);
74+
75+
/*!
76+
\ingroup MLDSA
77+
78+
\brief This macro frees resources associated with an MlDsaKey structure.
79+
80+
This macro maps to wc_dilithium_free().
81+
82+
\return 0 Returned upon success (implementation dependent)
83+
\return BAD_FUNC_ARGS Returned if key is NULL (implementation dependent)
84+
85+
\param key pointer to the MlDsaKey structure to free
86+
87+
\sa wc_MlDsaKey_Init
88+
*/
89+
void wc_MlDsaKey_Free(MlDsaKey *key);
90+
/*!
91+
\ingroup MLDSA
92+
93+
\brief This macro generates an ML-DSA public/private key pair.
94+
95+
The key must be initialized and have parameters set prior to calling.
96+
This macro maps to wc_dilithium_make_key().
97+
98+
\return 0 Returned upon success
99+
\return BAD_FUNC_ARGS Returned if key or rng is NULL
100+
\return RNG_FAILURE_E Returned if RNG fails (when applicable)
101+
102+
\param key pointer to the initialized MlDsaKey structure
103+
\param rng pointer to an initialized WC_RNG structure
104+
105+
\sa wc_MlDsaKey_Sign
106+
\sa wc_MlDsaKey_Verify
107+
*/
108+
int wc_MlDsaKey_MakeKey(MlDsaKey *key, WC_RNG *rrng);
109+
110+
/*!
111+
\ingroup MLDSA
112+
113+
\brief This macro exports the private key in raw (algorithm-specific) format.
114+
115+
This macro maps to wc_dilithium_export_private_only().
116+
117+
\return 0 Returned upon success
118+
\return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent)
119+
\return BUFFER_E Returned if output buffer is too small (when applicable)
120+
121+
\param key pointer to the MlDsaKey structure containing a private key
122+
\param out output buffer for raw private key
123+
\param outLen in/out: on input, size of out; on output, bytes written (implementation dependent)
124+
125+
\sa wc_MlDsaKey_GetPrivLen
126+
\sa wc_MlDsaKey_ImportPrivRaw
127+
*/
128+
int wc_MlDsaKey_ExportPrivRaw(MlDsaKey *key, byte *out, word32 *outLen);
129+
130+
/*!
131+
\ingroup MLDSA
132+
133+
\brief This macro imports the private key from raw (algorithm-specific) format.
134+
135+
This macro maps to wc_dilithium_import_private_only().
136+
137+
\return 0 Returned upon success
138+
\return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent)
139+
\return BUFFER_E Returned if input length is invalid (when applicable)
140+
141+
\param key pointer to the MlDsaKey structure to receive the private key
142+
\param in input buffer containing raw private key
143+
\param inLen length of input in bytes
144+
145+
\sa wc_MlDsaKey_ExportPrivRaw
146+
*/
147+
int wc_MlDsaKey_ImportPrivRaw(MlDsaKey *key, byte *in, word32 inLen);
148+
149+
/*!
150+
\ingroup MLDSA
151+
152+
\brief This macro exports the public key in raw (algorithm-specific) format.
153+
154+
This macro maps to wc_dilithium_export_public().
155+
156+
\return 0 Returned upon success
157+
\return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent)
158+
\return BUFFER_E Returned if output buffer is too small (when applicable)
159+
160+
\param key pointer to the MlDsaKey structure containing a public key
161+
\param out output buffer for raw public key
162+
\param outLen in/out: on input, size of out; on output, bytes written (implementation dependent)
163+
164+
\sa wc_MlDsaKey_GetPubLen
165+
\sa wc_MlDsaKey_ImportPubRaw
166+
*/
167+
inte wc_MlDsaKey_ExportPubRaw(MlDsaKey *key, byte *out, word32 *outLen);
168+
169+
/*!
170+
\ingroup MLDSA
171+
172+
\brief This macro imports the public key from raw (algorithm-specific) format.
173+
174+
This macro maps to wc_dilithium_import_public().
175+
176+
\return 0 Returned upon success
177+
\return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent)
178+
\return BUFFER_E Returned if input length is invalid (when applicable)
179+
180+
\param key pointer to the MlDsaKey structure to receive the public key
181+
\param in input buffer containing raw public key
182+
\param inLen length of input in bytes
183+
184+
\sa wc_MlDsaKey_ExportPubRaw
185+
*/
186+
int wc_MlDsaKey_ImportPubRaw(MlDsaKey *key, byte *in, word32 inLen);
187+
188+
/*!
189+
\ingroup MLDSA
190+
191+
\brief This macro signs a message using an ML-DSA private key.
192+
193+
This macro maps to wc_dilithium_sign_msg().
194+
Note the argument order: (msg,msgSz) are provided after (sig,sigSz).
195+
196+
\return 0 Returned upon success
197+
\return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent)
198+
\return BUFFER_E Returned if the signature buffer is too small (when applicable)
199+
\return RNG_FAILURE_E Returned if RNG fails (when applicable)
200+
201+
\param key pointer to the MlDsaKey structure containing a private key
202+
\param sig output buffer for signature
203+
\param sigSz in/out: on input, size of sig; on output, signature length written
204+
\param msg pointer to message buffer to sign
205+
\param msgSz size of message in bytes
206+
\param rng pointer to an initialized WC_RNG structure
207+
208+
_Example_
209+
\code
210+
byte sigBuf[DILITHIUM_ML_DSA_44_SIG_SIZE];
211+
word32 sigSz = sizeof(sigBuf);
212+
213+
wc_MlDsaKey_Sign(&key, sigBuf, &sigSz, msg, msgSz, &rng);
214+
\endcode
215+
216+
\sa wc_MlDsaKey_Verify
217+
\sa wc_MlDsaKey_GetSigLen
218+
*/
219+
int wc_MlDsaKey_Sign(MlDsaKey *key, byte *sig, word43 sigSz, const byte *msg, mword32 sgSz, WC_RNG *rng);
220+
221+
/*!
222+
\ingroup MLDSA
223+
224+
\brief This macro verifies an ML-DSA signature using an ML-DSA public key.
225+
226+
This macro maps to wc_dilithium_verify_msg().
227+
228+
The verification result is written to \p res.
229+
230+
\return 0 Returned upon success (verification executed)
231+
\return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent)
232+
233+
\param key pointer to the MlDsaKey structure containing a public key
234+
\param sig pointer to signature buffer
235+
\param sigSz size of signature in bytes
236+
\param msg pointer to message buffer to verify
237+
\param msgSz size of message in bytes
238+
\param res output: verification result (typically 1 = valid, 0 = invalid)
239+
240+
_Example_
241+
\code
242+
int verified = 0;
243+
wc_MlDsaKey_Verify(&pub, sigBuf, sigSz, msg, msgSz, &verified);
244+
if (verified != 1) {
245+
// invalid
246+
}
247+
\endcode
248+
249+
\sa wc_MlDsaKey_Sign
250+
*/
251+
int wc_MlDsaKey_Verify(MlDsaKey *key, const byte *sig, word32 sigSz, const byte *msg, word32 msgSz, int *res);
252+
/*!
253+
\ingroup MLDSA
254+
255+
\brief This macro exports the ML-DSA public key to DER format.
256+
257+
This macro maps to wc_Dilithium_PublicKeyToDer().
258+
259+
\return bytes Returned as the number of bytes written upon success (> 0)
260+
\return negative error code Returned upon failure
261+
262+
\param key pointer to MlDsaKey
263+
\param output output buffer for DER
264+
\param len size of output buffer in bytes
265+
\param withAlg non-zero to include AlgorithmIdentifier when supported
266+
267+
\sa wc_MlDsaKey_PrivateKeyToDer
268+
*/
269+
int wc_MlDsaKey_PublicKeyToDer(MlDsaKey *key, byte *output, word32 len, int withAlg);
270+
271+
/*!
272+
\ingroup MLDSA
273+
274+
\brief This macro exports the ML-DSA private key to DER format.
275+
276+
This macro maps to wc_Dilithium_PrivateKeyToDer().
277+
278+
\return bytes Returned as the number of bytes written upon success (> 0)
279+
\return negative error code Returned upon failure
280+
281+
\param key pointer to MlDsaKey
282+
\param output output buffer for DER
283+
\param len size of output buffer in bytes
284+
285+
\sa wc_MlDsaKey_PublicKeyToDer
286+
*/
287+
int wc_MlDsaKey_PrivateKeyToDer(MlDsaKey *key, byte *output, word32 len);
288+
289+
/*!
290+
\ingroup MLDSA
291+
292+
\brief This function returns the raw private key length in bytes for the configured parameter set.
293+
294+
\return 0 Returned upon success
295+
\return BAD_FUNC_ARGS Returned if key or len is NULL
296+
297+
\param key pointer to an initialized MlDsaKey structure
298+
\param len output pointer receiving private key length in bytes
299+
300+
\sa wc_MlDsaKey_ExportPrivRaw
301+
*/
302+
int wc_MlDsaKey_GetPrivLen(MlDsaKey *key, int *len);
303+
304+
/*!
305+
\ingroup MLDSA
306+
307+
\brief This function returns the raw public key length in bytes for the configured parameter set.
308+
309+
\return 0 Returned upon success
310+
\return BAD_FUNC_ARGS Returned if key or len is NULL
311+
312+
\param key pointer to an initialized MlDsaKey structure
313+
\param len output pointer receiving public key length in bytes
314+
315+
\sa wc_MlDsaKey_ExportPubRaw
316+
*/
317+
int wc_MlDsaKey_GetPubLen(MlDsaKey *key, int *len);
318+
319+
/*!
320+
\ingroup MLDSA
321+
322+
\brief This function returns the signature length in bytes for the configured parameter set.
323+
324+
\return 0 Returned upon success
325+
\return BAD_FUNC_ARGS Returned if key or len is NULL
326+
327+
\param key pointer to an initialized MlDsaKey structure
328+
\param len output pointer receiving signature length in bytes
329+
330+
\sa wc_MlDsaKey_Sign
331+
*/
332+
int wc_MlDsaKey_GetSigLen(MlDsaKey *key, int *len);

‎doc/dox_comments/header_files/doxygen_groups.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,8 @@
198198
\defgroup MD2 Algorithms - MD2
199199
\defgroup MD4 Algorithms - MD4
200200
\defgroup MD5 Algorithms - MD5
201+
\defgroup MLDSA Algorithms - ML-DSA
202+
\defgroup MLKEM Algorithms - ML-KEM
201203
\defgroup PKCS7 Algorithms - PKCS7
202204
\defgroup PKCS11 Algorithms - PKCS11
203205
\defgroup Password Algorithms - Password Based

‎doc/dox_comments/header_files/doxygen_pages.h‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@
4949
<li>\ref MD2</li>
5050
<li>\ref MD4</li>
5151
<li>\ref MD5</li>
52+
<li>\ref MLDSA</li>
53+
<li>\ref MLKEM</li>
5254
<li>\ref Password</li>
5355
<li>\ref PKCS7</li>
5456
<li>\ref PKCS11</li>
@@ -74,4 +76,3 @@
7476
- \ref SAKKE_RSK
7577
- \ref SAKKE_Operations
7678
*/
77-

0 commit comments

Comments
 (0)