Skip to content

Commit e37a77f

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

File tree

4 files changed

+774
-1
lines changed

4 files changed

+774
-1
lines changed

‎doc/dox_comments/header_files/dilithium.h‎

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
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(key, heap, 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(key, 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(key, 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(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(key, rng);
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(key, out, 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(key, in, 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(key, out, 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(key, in, 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(key, sig, sigSz, msg, msgSz, 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(key, sig, sigSz, msg, msgSz, res);
252+
253+
/*!
254+
\ingroup MLDSA
255+
256+
\brief This macro exports the ML-DSA public key to DER format.
257+
258+
This macro maps to wc_Dilithium_PublicKeyToDer().
259+
260+
\return bytes Returned as the number of bytes written upon success (> 0)
261+
\return negative error code Returned upon failure
262+
263+
\param key pointer to MlDsaKey
264+
\param output output buffer for DER
265+
\param len size of output buffer in bytes
266+
\param withAlg non-zero to include AlgorithmIdentifier when supported
267+
268+
\sa wc_MlDsaKey_PrivateKeyToDer
269+
*/
270+
int wc_MlDsaKey_PublicKeyToDer(key, output, len, withAlg);
271+
272+
/*!
273+
\ingroup MLDSA
274+
275+
\brief This macro exports the ML-DSA private key to DER format.
276+
277+
This macro maps to wc_Dilithium_PrivateKeyToDer().
278+
279+
\return bytes Returned as the number of bytes written upon success (> 0)
280+
\return negative error code Returned upon failure
281+
282+
\param key pointer to MlDsaKey
283+
\param output output buffer for DER
284+
\param len size of output buffer in bytes
285+
286+
\sa wc_MlDsaKey_PublicKeyToDer
287+
*/
288+
int wc_MlDsaKey_PrivateKeyToDer(key, output, len);
289+
290+
/*!
291+
\ingroup MLDSA
292+
293+
\brief This function returns the raw private key length in bytes for the configured parameter set.
294+
295+
\return 0 Returned upon success
296+
\return BAD_FUNC_ARGS Returned if key or len is NULL
297+
298+
\param key pointer to an initialized MlDsaKey structure
299+
\param len output pointer receiving private key length in bytes
300+
301+
\sa wc_MlDsaKey_ExportPrivRaw
302+
*/
303+
int wc_MlDsaKey_GetPrivLen(MlDsaKey *key, int *len);
304+
305+
/*!
306+
\ingroup MLDSA
307+
308+
\brief This function returns the raw public key length in bytes for the configured parameter set.
309+
310+
\return 0 Returned upon success
311+
\return BAD_FUNC_ARGS Returned if key or len is NULL
312+
313+
\param key pointer to an initialized MlDsaKey structure
314+
\param len output pointer receiving public key length in bytes
315+
316+
\sa wc_MlDsaKey_ExportPubRaw
317+
*/
318+
int wc_MlDsaKey_GetPubLen(MlDsaKey *key, int *len);
319+
320+
/*!
321+
\ingroup MLDSA
322+
323+
\brief This function returns the signature length in bytes for the configured parameter set.
324+
325+
\return 0 Returned upon success
326+
\return BAD_FUNC_ARGS Returned if key or len is NULL
327+
328+
\param key pointer to an initialized MlDsaKey structure
329+
\param len output pointer receiving signature length in bytes
330+
331+
\sa wc_MlDsaKey_Sign
332+
*/
333+
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)