1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
/** @file
ML-DSA API implementation based on OpenSSL
Copyright (c) 2026, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent
**/
#include <Library/BaseCryptLib.h>
#include <Library/DebugLib.h>
/**
Creates a new ML-DSA context by Crypto NID.
This function allocates and initializes a new ML-DSA context for the specified
ML-DSA variant. The context is created with no key material; the EVP_PKEY
structure is set to NULL. The caller must call MlDsaFree() to release the
context when done.
Before keys can be used for signing or verification, they must be set using
MlDsaSetPrivKey() or MlDsaSetPubKey().
If Nid is not a supported ML-DSA variant, then return NULL.
If memory allocation fails, then return NULL.
@param[in] Nid Crypto NID of the ML-DSA variant (e.g., CRYPTO_NID_ML_DSA_87).
@retval Pointer to new ML-DSA context if successful.
@retval NULL if Nid is unsupported or allocation failed.
**/
VOID *
EFIAPI
MlDsaNewByNid (
IN UINTN Nid
)
{
ASSERT (FALSE);
return NULL;
}
/**
Frees an ML-DSA context and all associated resources.
This function releases all memory associated with the ML-DSA context, including
the EVP_PKEY structure. After calling this function, the MlDsaContext pointer
should not be used.
If MlDsaContext is NULL, then this function returns immediately without action.
@param[in] MlDsaContext Pointer to the ML-DSA context to be released.
**/
VOID
EFIAPI
MlDsaFree (
IN VOID *MlDsaContext
)
{
ASSERT (FALSE);
}
/**
Retrieves the ML-DSA public key from the ML-DSA context.
This function extracts the public key from the ML-DSA context and copies it to
the provided buffer. The public key is returned in raw binary format.
The context must have a key set (either via MlDsaSetPrivKey() or MlDsaSetPubKey())
before calling this function.
If MlDsaContext is NULL, then return FALSE.
If PublicKeySize is NULL, then return FALSE.
If the context does not contain a valid key, then return FALSE.
If PublicKey buffer is too small, PublicKeySize is updated with required size and return FALSE.
@param[in] MlDsaContext Pointer to ML-DSA context containing the key.
@param[out] PublicKey Pointer to buffer to receive the public key.
@param[in,out] PublicKeySize On input, size of PublicKey buffer in bytes.
On output, actual size of public key written.
@retval TRUE ML-DSA public key retrieved successfully.
@retval FALSE Invalid parameters or buffer too small.
**/
BOOLEAN
EFIAPI
MlDsaGetPubKey (
IN VOID *MlDsaContext,
OUT UINT8 *PublicKey,
IN OUT UINTN *PublicKeySize
)
{
ASSERT (FALSE);
return FALSE;
}
/**
Sets the ML-DSA public key in the ML-DSA context.
This function imports a raw public key into the ML-DSA context. The public key
must be in raw binary format (not PEM or DER encoded). The key size must match
the expected size for the ML-DSA variant (2592 bytes for ML-DSA-87).
After setting the public key, the context can be used for signature verification
but not for signing (which requires the private key).
If MlDsaContext is NULL, then return FALSE.
If PublicKey is NULL, then return FALSE.
If PublicKeySize does not match the expected size for the variant, then return FALSE.
@param[in] MlDsaContext Pointer to ML-DSA context created by MlDsaNewByNid().
@param[in] PublicKey Pointer to raw public key bytes.
@param[in] PublicKeySize Size of the public key in bytes.
@retval TRUE ML-DSA public key was set successfully.
@retval FALSE Invalid parameters or key size mismatch.
**/
BOOLEAN
EFIAPI
MlDsaSetPubKey (
IN VOID *MlDsaContext,
IN UINT8 *PublicKey,
IN UINTN PublicKeySize
)
{
ASSERT (FALSE);
return FALSE;
}
/**
Sets the ML-DSA private key in the ML-DSA context.
This function imports a raw private key into the ML-DSA context. The private key
must be in raw binary format (not PEM or DER encoded). The key size must match
the expected size for the ML-DSA variant (4896 bytes for ML-DSA-87).
OpenSSL automatically derives the public key from the private key, so after
calling this function, both signing and verification operations are possible.
If MlDsaContext is NULL, then return FALSE.
If PrivateKey is NULL, then return FALSE.
If PrivateKeySize does not match the expected size for the variant, then return FALSE.
@param[in] MlDsaContext Pointer to ML-DSA context created by MlDsaNewByNid().
@param[in] PrivateKey Pointer to raw private key bytes.
@param[in] PrivateKeySize Size of the private key in bytes.
@retval TRUE ML-DSA private key was set successfully.
@retval FALSE Invalid parameters or key size mismatch.
**/
BOOLEAN
EFIAPI
MlDsaSetPrivKey (
IN VOID *MlDsaContext,
IN UINT8 *PrivateKey,
IN UINTN PrivateKeySize
)
{
ASSERT (FALSE);
return FALSE;
}
/**
Generates and retrieves the public key from a private key context.
This function extracts the public key from an ML-DSA context that contains
a private key. It is equivalent to calling MlDsaGetPubKey() but is provided
for API consistency with other cryptographic implementations.
The context must contain a private key (set via MlDsaSetPrivKey()) before
calling this function.
If MlDsaContext is NULL, then return FALSE.
If PublicKey is NULL, then return FALSE.
If PublicKeySize does not match the expected size for the variant, then return FALSE.
@param[in] MlDsaContext Pointer to ML-DSA context containing the private key.
@param[out] PublicKey Pointer to buffer to receive the public key.
@param[in] PublicKeySize Size of the PublicKey buffer in bytes.
@retval TRUE Public key generated and retrieved successfully.
@retval FALSE Invalid parameters or public key extraction failed.
**/
BOOLEAN
EFIAPI
MlDsaGeneratePubKey (
IN VOID *MlDsaContext,
OUT UINT8 *PublicKey,
IN UINTN PublicKeySize
)
{
ASSERT (FALSE);
return FALSE;
}
/**
Generates an ML-DSA signature for a given message.
This function creates an ML-DSA signature using the private key stored in the
ML-DSA context. ML-DSA signatures can include an optional context string for
domain separation, allowing the same key to be used in different contexts
without creating security vulnerabilities.
The context must contain a private key (set via MlDsaSetPrivKey()) before
calling this function.
If MlDsaContext is NULL, then return FALSE.
If Message is NULL, then return FALSE.
If Signature is NULL, then return FALSE.
If SigSize is NULL, then return FALSE.
If SigSize buffer is too small, SigSize is updated with required size and return FALSE.
Context may be NULL if no context string is used (ContextSize must be 0).
@param[in] MlDsaContext Pointer to ML-DSA context containing the private key.
@param[in] Context Optional context string for domain separation.
May be NULL for default context.
@param[in] ContextSize Size of context string in bytes. Set to 0 if Context is NULL.
@param[in] Message Pointer to message data to be signed.
@param[in] MessageSize Size of message in bytes.
@param[out] Signature Pointer to buffer to receive the signature.
@param[in,out] SigSize On input, size of Signature buffer.
On output, actual size of signature (4627 bytes for ML-DSA-87).
@retval TRUE ML-DSA signature generated successfully.
@retval FALSE Invalid parameters or signature generation failed.
**/
BOOLEAN
EFIAPI
MlDsaSign (
IN VOID *MlDsaContext,
IN UINT8 *Context,
IN UINTN ContextSize,
IN CONST UINT8 *Message,
IN UINTN MessageSize,
OUT UINT8 *Signature,
IN OUT UINTN *SigSize
)
{
ASSERT (FALSE);
return FALSE;
}
/**
Verifies the ML-DSA signature for a given message.
This function verifies an ML-DSA signature against a message using the public key
contained in the ML-DSA context. An optional context string can be provided which
must match the context used during signing.
The context must contain a key (either public or private) set via MlDsaSetPrivKey()
or MlDsaSetPubKey() before calling this function.
If MlDsaContext is NULL, then return FALSE.
If Message is NULL, then return FALSE.
If Signature is NULL, then return FALSE.
If SigSize is 0 or exceeds INT_MAX, then return FALSE.
Context may be NULL if no context string is used.
@param[in] MlDsaContext Pointer to ML-DSA context containing the public key.
@param[in] Context Optional context string for domain separation.
May be NULL for default context.
@param[in] ContextSize Size of context string in bytes. Set to 0 if Context is NULL.
@param[in] Message Pointer to the message data to verify.
@param[in] MessageSize Size of the message in bytes.
@param[in] Signature Pointer to the ML-DSA signature to verify.
@param[in] SigSize Size of the signature in bytes.
@retval TRUE ML-DSA signature verification succeeded.
@retval FALSE ML-DSA signature verification failed or invalid parameters.
**/
BOOLEAN
EFIAPI
MlDsaVerify (
IN VOID *MlDsaContext,
IN UINT8 *Context,
IN UINTN ContextSize,
IN CONST UINT8 *Message,
IN UINTN MessageSize,
IN UINT8 *Signature,
IN UINTN SigSize
)
{
ASSERT (FALSE);
return FALSE;
}
|
