CryptoPkg: Add some comments for API usage clarification.
[mirror_edk2.git] / CryptoPkg / Include / Library / BaseCryptLib.h
CommitLineData
97f98500
HT
1/** @file\r
2 Defines base cryptographic library APIs.\r
3 The Base Cryptographic Library provides implementations of basic cryptography\r
a8c44645 4 primitives (Hash Serials, HMAC, RSA, Diffie-Hellman, etc) for UEFI security\r
5 functionality enabling.\r
97f98500 6\r
afeb55e4 7Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>\r
97f98500
HT
8This program and the accompanying materials\r
9are licensed and made available under the terms and conditions of the BSD License\r
10which accompanies this distribution. The full text of the license may be found at\r
11http://opensource.org/licenses/bsd-license.php\r
12\r
13THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
14WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
15\r
16**/\r
17\r
18#ifndef __BASE_CRYPT_LIB_H__\r
19#define __BASE_CRYPT_LIB_H__\r
20\r
4a567c96 21///\r
22/// MD4 digest size in bytes\r
23///\r
24#define MD4_DIGEST_SIZE 16\r
25\r
97f98500
HT
26///\r
27/// MD5 digest size in bytes\r
28///\r
29#define MD5_DIGEST_SIZE 16\r
30\r
31///\r
32/// SHA-1 digest size in bytes.\r
33///\r
34#define SHA1_DIGEST_SIZE 20\r
35\r
36///\r
37/// SHA-256 digest size in bytes\r
38///\r
39#define SHA256_DIGEST_SIZE 32\r
40\r
2ac68e8b
QL
41///\r
42/// SHA-384 digest size in bytes\r
43///\r
44#define SHA384_DIGEST_SIZE 48\r
45\r
46///\r
47/// SHA-512 digest size in bytes\r
48///\r
49#define SHA512_DIGEST_SIZE 64\r
50\r
a8c44645 51///\r
52/// TDES block size in bytes\r
53///\r
54#define TDES_BLOCK_SIZE 8\r
55\r
56///\r
57/// AES block size in bytes\r
58///\r
59#define AES_BLOCK_SIZE 16\r
60\r
97f98500
HT
61///\r
62/// RSA Key Tags Definition used in RsaSetKey() function for key component identification.\r
63///\r
64typedef enum {\r
65 RsaKeyN, ///< RSA public Modulus (N)\r
66 RsaKeyE, ///< RSA Public exponent (e)\r
67 RsaKeyD, ///< RSA Private exponent (d)\r
68 RsaKeyP, ///< RSA secret prime factor of Modulus (p)\r
69 RsaKeyQ, ///< RSA secret prime factor of Modules (q)\r
70 RsaKeyDp, ///< p's CRT exponent (== d mod (p - 1))\r
71 RsaKeyDq, ///< q's CRT exponent (== d mod (q - 1))\r
72 RsaKeyQInv ///< The CRT coefficient (== 1/q mod p)\r
73} RSA_KEY_TAG;\r
74\r
75//=====================================================================================\r
76// One-Way Cryptographic Hash Primitives\r
77//=====================================================================================\r
78\r
4a567c96 79/**\r
80 Retrieves the size, in bytes, of the context buffer required for MD4 hash operations.\r
81\r
532616bb 82 If this interface is not supported, then return zero.\r
83\r
4a567c96 84 @return The size, in bytes, of the context buffer required for MD4 hash operations.\r
532616bb 85 @retval 0 This interface is not supported.\r
4a567c96 86\r
87**/\r
88UINTN\r
89EFIAPI\r
90Md4GetContextSize (\r
91 VOID\r
92 );\r
93\r
94/**\r
95 Initializes user-supplied memory pointed by Md4Context as MD4 hash context for\r
96 subsequent use.\r
97\r
16d2c32c 98 If Md4Context is NULL, then return FALSE.\r
532616bb 99 If this interface is not supported, then return FALSE.\r
4a567c96 100\r
101 @param[out] Md4Context Pointer to MD4 context being initialized.\r
102\r
103 @retval TRUE MD4 context initialization succeeded.\r
104 @retval FALSE MD4 context initialization failed.\r
532616bb 105 @retval FALSE This interface is not supported.\r
4a567c96 106\r
107**/\r
108BOOLEAN\r
109EFIAPI\r
110Md4Init (\r
111 OUT VOID *Md4Context\r
112 );\r
113\r
114/**\r
115 Makes a copy of an existing MD4 context.\r
116\r
16d2c32c 117 If Md4Context is NULL, then return FALSE.\r
118 If NewMd4Context is NULL, then return FALSE.\r
532616bb 119 If this interface is not supported, then return FALSE.\r
4a567c96 120\r
121 @param[in] Md4Context Pointer to MD4 context being copied.\r
122 @param[out] NewMd4Context Pointer to new MD4 context.\r
123\r
124 @retval TRUE MD4 context copy succeeded.\r
125 @retval FALSE MD4 context copy failed.\r
532616bb 126 @retval FALSE This interface is not supported.\r
4a567c96 127\r
128**/\r
129BOOLEAN\r
130EFIAPI\r
131Md4Duplicate (\r
132 IN CONST VOID *Md4Context,\r
133 OUT VOID *NewMd4Context\r
134 );\r
135\r
136/**\r
137 Digests the input data and updates MD4 context.\r
138\r
139 This function performs MD4 digest on a data buffer of the specified size.\r
140 It can be called multiple times to compute the digest of long or discontinuous data streams.\r
141 MD4 context should be already correctly intialized by Md4Init(), and should not be finalized\r
142 by Md4Final(). Behavior with invalid context is undefined.\r
143\r
16d2c32c 144 If Md4Context is NULL, then return FALSE.\r
532616bb 145 If this interface is not supported, then return FALSE.\r
4a567c96 146\r
147 @param[in, out] Md4Context Pointer to the MD4 context.\r
148 @param[in] Data Pointer to the buffer containing the data to be hashed.\r
149 @param[in] DataSize Size of Data buffer in bytes.\r
150\r
151 @retval TRUE MD4 data digest succeeded.\r
152 @retval FALSE MD4 data digest failed.\r
532616bb 153 @retval FALSE This interface is not supported.\r
4a567c96 154\r
155**/\r
156BOOLEAN\r
157EFIAPI\r
158Md4Update (\r
159 IN OUT VOID *Md4Context,\r
160 IN CONST VOID *Data,\r
161 IN UINTN DataSize\r
162 );\r
163\r
164/**\r
165 Completes computation of the MD4 digest value.\r
166\r
167 This function completes MD4 hash computation and retrieves the digest value into\r
168 the specified memory. After this function has been called, the MD4 context cannot\r
169 be used again.\r
170 MD4 context should be already correctly intialized by Md4Init(), and should not be\r
171 finalized by Md4Final(). Behavior with invalid MD4 context is undefined.\r
172\r
16d2c32c 173 If Md4Context is NULL, then return FALSE.\r
174 If HashValue is NULL, then return FALSE.\r
532616bb 175 If this interface is not supported, then return FALSE.\r
4a567c96 176\r
177 @param[in, out] Md4Context Pointer to the MD4 context.\r
178 @param[out] HashValue Pointer to a buffer that receives the MD4 digest\r
179 value (16 bytes).\r
180\r
181 @retval TRUE MD4 digest computation succeeded.\r
182 @retval FALSE MD4 digest computation failed.\r
532616bb 183 @retval FALSE This interface is not supported.\r
4a567c96 184\r
185**/\r
186BOOLEAN\r
187EFIAPI\r
188Md4Final (\r
189 IN OUT VOID *Md4Context,\r
190 OUT UINT8 *HashValue\r
191 );\r
192\r
97f98500
HT
193/**\r
194 Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.\r
195\r
532616bb 196 If this interface is not supported, then return zero.\r
197\r
97f98500 198 @return The size, in bytes, of the context buffer required for MD5 hash operations.\r
532616bb 199 @retval 0 This interface is not supported.\r
97f98500
HT
200\r
201**/\r
202UINTN\r
203EFIAPI\r
204Md5GetContextSize (\r
205 VOID\r
206 );\r
207\r
97f98500
HT
208/**\r
209 Initializes user-supplied memory pointed by Md5Context as MD5 hash context for\r
210 subsequent use.\r
211\r
16d2c32c 212 If Md5Context is NULL, then return FALSE.\r
532616bb 213 If this interface is not supported, then return FALSE.\r
97f98500 214\r
a8c44645 215 @param[out] Md5Context Pointer to MD5 context being initialized.\r
97f98500
HT
216\r
217 @retval TRUE MD5 context initialization succeeded.\r
218 @retval FALSE MD5 context initialization failed.\r
532616bb 219 @retval FALSE This interface is not supported.\r
97f98500
HT
220\r
221**/\r
222BOOLEAN\r
223EFIAPI\r
224Md5Init (\r
a8c44645 225 OUT VOID *Md5Context\r
97f98500
HT
226 );\r
227\r
a8c44645 228/**\r
229 Makes a copy of an existing MD5 context.\r
230\r
16d2c32c 231 If Md5Context is NULL, then return FALSE.\r
232 If NewMd5Context is NULL, then return FALSE.\r
532616bb 233 If this interface is not supported, then return FALSE.\r
a8c44645 234\r
235 @param[in] Md5Context Pointer to MD5 context being copied.\r
236 @param[out] NewMd5Context Pointer to new MD5 context.\r
237\r
238 @retval TRUE MD5 context copy succeeded.\r
239 @retval FALSE MD5 context copy failed.\r
532616bb 240 @retval FALSE This interface is not supported.\r
a8c44645 241\r
242**/\r
243BOOLEAN\r
244EFIAPI\r
245Md5Duplicate (\r
246 IN CONST VOID *Md5Context,\r
247 OUT VOID *NewMd5Context\r
248 );\r
97f98500
HT
249\r
250/**\r
a8c44645 251 Digests the input data and updates MD5 context.\r
252\r
253 This function performs MD5 digest on a data buffer of the specified size.\r
254 It can be called multiple times to compute the digest of long or discontinuous data streams.\r
255 MD5 context should be already correctly intialized by Md5Init(), and should not be finalized\r
256 by Md5Final(). Behavior with invalid context is undefined.\r
97f98500 257\r
16d2c32c 258 If Md5Context is NULL, then return FALSE.\r
532616bb 259 If this interface is not supported, then return FALSE.\r
97f98500
HT
260\r
261 @param[in, out] Md5Context Pointer to the MD5 context.\r
262 @param[in] Data Pointer to the buffer containing the data to be hashed.\r
a8c44645 263 @param[in] DataSize Size of Data buffer in bytes.\r
97f98500
HT
264\r
265 @retval TRUE MD5 data digest succeeded.\r
a8c44645 266 @retval FALSE MD5 data digest failed.\r
532616bb 267 @retval FALSE This interface is not supported.\r
97f98500
HT
268\r
269**/\r
270BOOLEAN\r
271EFIAPI\r
272Md5Update (\r
273 IN OUT VOID *Md5Context,\r
274 IN CONST VOID *Data,\r
a8c44645 275 IN UINTN DataSize\r
97f98500
HT
276 );\r
277\r
97f98500 278/**\r
a8c44645 279 Completes computation of the MD5 digest value.\r
280\r
281 This function completes MD5 hash computation and retrieves the digest value into\r
282 the specified memory. After this function has been called, the MD5 context cannot\r
283 be used again.\r
284 MD5 context should be already correctly intialized by Md5Init(), and should not be\r
285 finalized by Md5Final(). Behavior with invalid MD5 context is undefined.\r
97f98500 286\r
16d2c32c 287 If Md5Context is NULL, then return FALSE.\r
288 If HashValue is NULL, then return FALSE.\r
532616bb 289 If this interface is not supported, then return FALSE.\r
97f98500 290\r
a8c44645 291 @param[in, out] Md5Context Pointer to the MD5 context.\r
97f98500
HT
292 @param[out] HashValue Pointer to a buffer that receives the MD5 digest\r
293 value (16 bytes).\r
294\r
295 @retval TRUE MD5 digest computation succeeded.\r
296 @retval FALSE MD5 digest computation failed.\r
532616bb 297 @retval FALSE This interface is not supported.\r
97f98500
HT
298\r
299**/\r
300BOOLEAN\r
301EFIAPI\r
302Md5Final (\r
303 IN OUT VOID *Md5Context,\r
304 OUT UINT8 *HashValue\r
305 );\r
306\r
97f98500
HT
307/**\r
308 Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.\r
309\r
532616bb 310 If this interface is not supported, then return zero.\r
311\r
97f98500 312 @return The size, in bytes, of the context buffer required for SHA-1 hash operations.\r
532616bb 313 @retval 0 This interface is not supported.\r
97f98500
HT
314\r
315**/\r
316UINTN\r
317EFIAPI\r
318Sha1GetContextSize (\r
319 VOID\r
320 );\r
321\r
97f98500 322/**\r
a8c44645 323 Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for\r
97f98500
HT
324 subsequent use.\r
325\r
16d2c32c 326 If Sha1Context is NULL, then return FALSE.\r
532616bb 327 If this interface is not supported, then return FALSE.\r
97f98500 328\r
a8c44645 329 @param[out] Sha1Context Pointer to SHA-1 context being initialized.\r
97f98500 330\r
a8c44645 331 @retval TRUE SHA-1 context initialization succeeded.\r
332 @retval FALSE SHA-1 context initialization failed.\r
532616bb 333 @retval FALSE This interface is not supported.\r
97f98500
HT
334\r
335**/\r
336BOOLEAN\r
337EFIAPI\r
338Sha1Init (\r
a8c44645 339 OUT VOID *Sha1Context\r
97f98500
HT
340 );\r
341\r
a8c44645 342/**\r
343 Makes a copy of an existing SHA-1 context.\r
344\r
16d2c32c 345 If Sha1Context is NULL, then return FALSE.\r
346 If NewSha1Context is NULL, then return FALSE.\r
532616bb 347 If this interface is not supported, then return FALSE.\r
a8c44645 348\r
349 @param[in] Sha1Context Pointer to SHA-1 context being copied.\r
350 @param[out] NewSha1Context Pointer to new SHA-1 context.\r
351\r
352 @retval TRUE SHA-1 context copy succeeded.\r
353 @retval FALSE SHA-1 context copy failed.\r
532616bb 354 @retval FALSE This interface is not supported.\r
a8c44645 355\r
356**/\r
357BOOLEAN\r
358EFIAPI\r
359Sha1Duplicate (\r
360 IN CONST VOID *Sha1Context,\r
361 OUT VOID *NewSha1Context\r
362 );\r
97f98500
HT
363\r
364/**\r
a8c44645 365 Digests the input data and updates SHA-1 context.\r
366\r
367 This function performs SHA-1 digest on a data buffer of the specified size.\r
368 It can be called multiple times to compute the digest of long or discontinuous data streams.\r
369 SHA-1 context should be already correctly intialized by Sha1Init(), and should not be finalized\r
370 by Sha1Final(). Behavior with invalid context is undefined.\r
97f98500 371\r
16d2c32c 372 If Sha1Context is NULL, then return FALSE.\r
532616bb 373 If this interface is not supported, then return FALSE.\r
97f98500
HT
374\r
375 @param[in, out] Sha1Context Pointer to the SHA-1 context.\r
376 @param[in] Data Pointer to the buffer containing the data to be hashed.\r
a8c44645 377 @param[in] DataSize Size of Data buffer in bytes.\r
97f98500
HT
378\r
379 @retval TRUE SHA-1 data digest succeeded.\r
a8c44645 380 @retval FALSE SHA-1 data digest failed.\r
532616bb 381 @retval FALSE This interface is not supported.\r
97f98500
HT
382\r
383**/\r
384BOOLEAN\r
385EFIAPI\r
386Sha1Update (\r
387 IN OUT VOID *Sha1Context,\r
388 IN CONST VOID *Data,\r
a8c44645 389 IN UINTN DataSize\r
97f98500
HT
390 );\r
391\r
97f98500 392/**\r
a8c44645 393 Completes computation of the SHA-1 digest value.\r
394\r
395 This function completes SHA-1 hash computation and retrieves the digest value into\r
396 the specified memory. After this function has been called, the SHA-1 context cannot\r
397 be used again.\r
398 SHA-1 context should be already correctly intialized by Sha1Init(), and should not be\r
399 finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.\r
97f98500 400\r
16d2c32c 401 If Sha1Context is NULL, then return FALSE.\r
402 If HashValue is NULL, then return FALSE.\r
532616bb 403 If this interface is not supported, then return FALSE.\r
97f98500 404\r
a8c44645 405 @param[in, out] Sha1Context Pointer to the SHA-1 context.\r
97f98500
HT
406 @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest\r
407 value (20 bytes).\r
408\r
409 @retval TRUE SHA-1 digest computation succeeded.\r
410 @retval FALSE SHA-1 digest computation failed.\r
532616bb 411 @retval FALSE This interface is not supported.\r
97f98500
HT
412\r
413**/\r
414BOOLEAN\r
415EFIAPI\r
416Sha1Final (\r
417 IN OUT VOID *Sha1Context,\r
418 OUT UINT8 *HashValue\r
419 );\r
420\r
97f98500 421/**\r
a8c44645 422 Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.\r
97f98500 423\r
a8c44645 424 @return The size, in bytes, of the context buffer required for SHA-256 hash operations.\r
97f98500
HT
425\r
426**/\r
427UINTN\r
428EFIAPI\r
429Sha256GetContextSize (\r
430 VOID\r
431 );\r
432\r
97f98500
HT
433/**\r
434 Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for\r
435 subsequent use.\r
436\r
16d2c32c 437 If Sha256Context is NULL, then return FALSE.\r
97f98500 438\r
a8c44645 439 @param[out] Sha256Context Pointer to SHA-256 context being initialized.\r
97f98500
HT
440\r
441 @retval TRUE SHA-256 context initialization succeeded.\r
442 @retval FALSE SHA-256 context initialization failed.\r
443\r
444**/\r
445BOOLEAN\r
446EFIAPI\r
447Sha256Init (\r
a8c44645 448 OUT VOID *Sha256Context\r
97f98500
HT
449 );\r
450\r
a8c44645 451/**\r
452 Makes a copy of an existing SHA-256 context.\r
453\r
16d2c32c 454 If Sha256Context is NULL, then return FALSE.\r
455 If NewSha256Context is NULL, then return FALSE.\r
532616bb 456 If this interface is not supported, then return FALSE.\r
a8c44645 457\r
458 @param[in] Sha256Context Pointer to SHA-256 context being copied.\r
459 @param[out] NewSha256Context Pointer to new SHA-256 context.\r
460\r
461 @retval TRUE SHA-256 context copy succeeded.\r
462 @retval FALSE SHA-256 context copy failed.\r
532616bb 463 @retval FALSE This interface is not supported.\r
a8c44645 464\r
465**/\r
466BOOLEAN\r
467EFIAPI\r
468Sha256Duplicate (\r
469 IN CONST VOID *Sha256Context,\r
470 OUT VOID *NewSha256Context\r
471 );\r
97f98500
HT
472\r
473/**\r
a8c44645 474 Digests the input data and updates SHA-256 context.\r
475\r
476 This function performs SHA-256 digest on a data buffer of the specified size.\r
477 It can be called multiple times to compute the digest of long or discontinuous data streams.\r
478 SHA-256 context should be already correctly intialized by Sha256Init(), and should not be finalized\r
479 by Sha256Final(). Behavior with invalid context is undefined.\r
97f98500 480\r
16d2c32c 481 If Sha256Context is NULL, then return FALSE.\r
97f98500
HT
482\r
483 @param[in, out] Sha256Context Pointer to the SHA-256 context.\r
484 @param[in] Data Pointer to the buffer containing the data to be hashed.\r
a8c44645 485 @param[in] DataSize Size of Data buffer in bytes.\r
97f98500
HT
486\r
487 @retval TRUE SHA-256 data digest succeeded.\r
a8c44645 488 @retval FALSE SHA-256 data digest failed.\r
97f98500
HT
489\r
490**/\r
491BOOLEAN\r
492EFIAPI\r
493Sha256Update (\r
494 IN OUT VOID *Sha256Context,\r
495 IN CONST VOID *Data,\r
a8c44645 496 IN UINTN DataSize\r
97f98500
HT
497 );\r
498\r
97f98500 499/**\r
a8c44645 500 Completes computation of the SHA-256 digest value.\r
501\r
502 This function completes SHA-256 hash computation and retrieves the digest value into\r
503 the specified memory. After this function has been called, the SHA-256 context cannot\r
504 be used again.\r
505 SHA-256 context should be already correctly intialized by Sha256Init(), and should not be\r
506 finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.\r
97f98500 507\r
16d2c32c 508 If Sha256Context is NULL, then return FALSE.\r
509 If HashValue is NULL, then return FALSE.\r
97f98500 510\r
a8c44645 511 @param[in, out] Sha256Context Pointer to the SHA-256 context.\r
97f98500
HT
512 @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest\r
513 value (32 bytes).\r
514\r
515 @retval TRUE SHA-256 digest computation succeeded.\r
516 @retval FALSE SHA-256 digest computation failed.\r
517\r
518**/\r
519BOOLEAN\r
520EFIAPI\r
521Sha256Final (\r
522 IN OUT VOID *Sha256Context,\r
523 OUT UINT8 *HashValue\r
524 );\r
525\r
2ac68e8b
QL
526/**\r
527 Retrieves the size, in bytes, of the context buffer required for SHA-384 hash operations.\r
528\r
529 @return The size, in bytes, of the context buffer required for SHA-384 hash operations.\r
530\r
531**/\r
532UINTN\r
533EFIAPI\r
534Sha384GetContextSize (\r
535 VOID\r
536 );\r
537\r
538/**\r
539 Initializes user-supplied memory pointed by Sha384Context as SHA-384 hash context for\r
540 subsequent use.\r
541\r
542 If Sha384Context is NULL, then return FALSE.\r
543\r
544 @param[out] Sha384Context Pointer to SHA-384 context being initialized.\r
545\r
546 @retval TRUE SHA-384 context initialization succeeded.\r
547 @retval FALSE SHA-384 context initialization failed.\r
548\r
549**/\r
550BOOLEAN\r
551EFIAPI\r
552Sha384Init (\r
553 OUT VOID *Sha384Context\r
554 );\r
555\r
556/**\r
557 Makes a copy of an existing SHA-384 context.\r
558\r
559 If Sha384Context is NULL, then return FALSE.\r
560 If NewSha384Context is NULL, then return FALSE.\r
561 If this interface is not supported, then return FALSE.\r
562\r
563 @param[in] Sha384Context Pointer to SHA-384 context being copied.\r
564 @param[out] NewSha384Context Pointer to new SHA-384 context.\r
565\r
566 @retval TRUE SHA-384 context copy succeeded.\r
567 @retval FALSE SHA-384 context copy failed.\r
568 @retval FALSE This interface is not supported.\r
569\r
570**/\r
571BOOLEAN\r
572EFIAPI\r
573Sha384Duplicate (\r
574 IN CONST VOID *Sha384Context,\r
575 OUT VOID *NewSha384Context\r
576 );\r
577\r
578/**\r
579 Digests the input data and updates SHA-384 context.\r
580\r
581 This function performs SHA-384 digest on a data buffer of the specified size.\r
582 It can be called multiple times to compute the digest of long or discontinuous data streams.\r
583 SHA-384 context should be already correctly intialized by Sha384Init(), and should not be finalized\r
584 by Sha384Final(). Behavior with invalid context is undefined.\r
585\r
586 If Sha384Context is NULL, then return FALSE.\r
587\r
588 @param[in, out] Sha384Context Pointer to the SHA-384 context.\r
589 @param[in] Data Pointer to the buffer containing the data to be hashed.\r
590 @param[in] DataSize Size of Data buffer in bytes.\r
591\r
592 @retval TRUE SHA-384 data digest succeeded.\r
593 @retval FALSE SHA-384 data digest failed.\r
594\r
595**/\r
596BOOLEAN\r
597EFIAPI\r
598Sha384Update (\r
599 IN OUT VOID *Sha384Context,\r
600 IN CONST VOID *Data,\r
601 IN UINTN DataSize\r
602 );\r
603\r
604/**\r
605 Completes computation of the SHA-384 digest value.\r
606\r
607 This function completes SHA-384 hash computation and retrieves the digest value into\r
608 the specified memory. After this function has been called, the SHA-384 context cannot\r
609 be used again.\r
610 SHA-384 context should be already correctly intialized by Sha384Init(), and should not be\r
611 finalized by Sha384Final(). Behavior with invalid SHA-384 context is undefined.\r
612\r
613 If Sha384Context is NULL, then return FALSE.\r
614 If HashValue is NULL, then return FALSE.\r
615\r
616 @param[in, out] Sha384Context Pointer to the SHA-384 context.\r
617 @param[out] HashValue Pointer to a buffer that receives the SHA-384 digest\r
618 value (48 bytes).\r
619\r
620 @retval TRUE SHA-384 digest computation succeeded.\r
621 @retval FALSE SHA-384 digest computation failed.\r
622\r
623**/\r
624BOOLEAN\r
625EFIAPI\r
626Sha384Final (\r
627 IN OUT VOID *Sha384Context,\r
628 OUT UINT8 *HashValue\r
629 );\r
630\r
631/**\r
632 Retrieves the size, in bytes, of the context buffer required for SHA-512 hash operations.\r
633\r
634 @return The size, in bytes, of the context buffer required for SHA-512 hash operations.\r
635\r
636**/\r
637UINTN\r
638EFIAPI\r
639Sha512GetContextSize (\r
640 VOID\r
641 );\r
642\r
643/**\r
644 Initializes user-supplied memory pointed by Sha512Context as SHA-512 hash context for\r
645 subsequent use.\r
646\r
647 If Sha512Context is NULL, then return FALSE.\r
648\r
649 @param[out] Sha512Context Pointer to SHA-512 context being initialized.\r
650\r
651 @retval TRUE SHA-512 context initialization succeeded.\r
652 @retval FALSE SHA-512 context initialization failed.\r
653\r
654**/\r
655BOOLEAN\r
656EFIAPI\r
657Sha512Init (\r
658 OUT VOID *Sha512Context\r
659 );\r
660\r
661/**\r
662 Makes a copy of an existing SHA-512 context.\r
663\r
664 If Sha512Context is NULL, then return FALSE.\r
665 If NewSha512Context is NULL, then return FALSE.\r
666 If this interface is not supported, then return FALSE.\r
667\r
668 @param[in] Sha512Context Pointer to SHA-512 context being copied.\r
669 @param[out] NewSha512Context Pointer to new SHA-512 context.\r
670\r
671 @retval TRUE SHA-512 context copy succeeded.\r
672 @retval FALSE SHA-512 context copy failed.\r
673 @retval FALSE This interface is not supported.\r
674\r
675**/\r
676BOOLEAN\r
677EFIAPI\r
678Sha512Duplicate (\r
679 IN CONST VOID *Sha512Context,\r
680 OUT VOID *NewSha512Context\r
681 );\r
682\r
683/**\r
684 Digests the input data and updates SHA-512 context.\r
685\r
686 This function performs SHA-512 digest on a data buffer of the specified size.\r
687 It can be called multiple times to compute the digest of long or discontinuous data streams.\r
688 SHA-512 context should be already correctly intialized by Sha512Init(), and should not be finalized\r
689 by Sha512Final(). Behavior with invalid context is undefined.\r
690\r
691 If Sha512Context is NULL, then return FALSE.\r
692\r
693 @param[in, out] Sha512Context Pointer to the SHA-512 context.\r
694 @param[in] Data Pointer to the buffer containing the data to be hashed.\r
695 @param[in] DataSize Size of Data buffer in bytes.\r
696\r
697 @retval TRUE SHA-512 data digest succeeded.\r
698 @retval FALSE SHA-512 data digest failed.\r
699\r
700**/\r
701BOOLEAN\r
702EFIAPI\r
703Sha512Update (\r
704 IN OUT VOID *Sha512Context,\r
705 IN CONST VOID *Data,\r
706 IN UINTN DataSize\r
707 );\r
708\r
709/**\r
710 Completes computation of the SHA-512 digest value.\r
711\r
712 This function completes SHA-512 hash computation and retrieves the digest value into\r
713 the specified memory. After this function has been called, the SHA-512 context cannot\r
714 be used again.\r
715 SHA-512 context should be already correctly intialized by Sha512Init(), and should not be\r
716 finalized by Sha512Final(). Behavior with invalid SHA-512 context is undefined.\r
717\r
718 If Sha512Context is NULL, then return FALSE.\r
719 If HashValue is NULL, then return FALSE.\r
720\r
721 @param[in, out] Sha512Context Pointer to the SHA-512 context.\r
722 @param[out] HashValue Pointer to a buffer that receives the SHA-512 digest\r
723 value (64 bytes).\r
724\r
725 @retval TRUE SHA-512 digest computation succeeded.\r
726 @retval FALSE SHA-512 digest computation failed.\r
727\r
728**/\r
729BOOLEAN\r
730EFIAPI\r
731Sha512Final (\r
732 IN OUT VOID *Sha512Context,\r
733 OUT UINT8 *HashValue\r
734 );\r
97f98500
HT
735\r
736//=====================================================================================\r
737// MAC (Message Authentication Code) Primitive\r
738//=====================================================================================\r
739\r
a8c44645 740/**\r
741 Retrieves the size, in bytes, of the context buffer required for HMAC-MD5 operations.\r
742\r
532616bb 743 If this interface is not supported, then return zero.\r
744\r
a8c44645 745 @return The size, in bytes, of the context buffer required for HMAC-MD5 operations.\r
532616bb 746 @retval 0 This interface is not supported.\r
a8c44645 747\r
748**/\r
749UINTN\r
750EFIAPI\r
751HmacMd5GetContextSize (\r
752 VOID\r
753 );\r
754\r
755/**\r
756 Initializes user-supplied memory pointed by HmacMd5Context as HMAC-MD5 context for\r
757 subsequent use.\r
758\r
16d2c32c 759 If HmacMd5Context is NULL, then return FALSE.\r
532616bb 760 If this interface is not supported, then return FALSE.\r
a8c44645 761\r
762 @param[out] HmacMd5Context Pointer to HMAC-MD5 context being initialized.\r
763 @param[in] Key Pointer to the user-supplied key.\r
764 @param[in] KeySize Key size in bytes.\r
765\r
766 @retval TRUE HMAC-MD5 context initialization succeeded.\r
767 @retval FALSE HMAC-MD5 context initialization failed.\r
532616bb 768 @retval FALSE This interface is not supported.\r
a8c44645 769\r
770**/\r
771BOOLEAN\r
772EFIAPI\r
773HmacMd5Init (\r
774 OUT VOID *HmacMd5Context,\r
775 IN CONST UINT8 *Key,\r
776 IN UINTN KeySize\r
777 );\r
778\r
779/**\r
780 Makes a copy of an existing HMAC-MD5 context.\r
781\r
16d2c32c 782 If HmacMd5Context is NULL, then return FALSE.\r
783 If NewHmacMd5Context is NULL, then return FALSE.\r
532616bb 784 If this interface is not supported, then return FALSE.\r
a8c44645 785\r
786 @param[in] HmacMd5Context Pointer to HMAC-MD5 context being copied.\r
787 @param[out] NewHmacMd5Context Pointer to new HMAC-MD5 context.\r
788\r
789 @retval TRUE HMAC-MD5 context copy succeeded.\r
790 @retval FALSE HMAC-MD5 context copy failed.\r
532616bb 791 @retval FALSE This interface is not supported.\r
a8c44645 792\r
793**/\r
794BOOLEAN\r
795EFIAPI\r
796HmacMd5Duplicate (\r
797 IN CONST VOID *HmacMd5Context,\r
798 OUT VOID *NewHmacMd5Context\r
799 );\r
800\r
801/**\r
802 Digests the input data and updates HMAC-MD5 context.\r
803\r
804 This function performs HMAC-MD5 digest on a data buffer of the specified size.\r
805 It can be called multiple times to compute the digest of long or discontinuous data streams.\r
806 HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be\r
807 finalized by HmacMd5Final(). Behavior with invalid context is undefined.\r
808\r
16d2c32c 809 If HmacMd5Context is NULL, then return FALSE.\r
532616bb 810 If this interface is not supported, then return FALSE.\r
a8c44645 811\r
812 @param[in, out] HmacMd5Context Pointer to the HMAC-MD5 context.\r
813 @param[in] Data Pointer to the buffer containing the data to be digested.\r
814 @param[in] DataSize Size of Data buffer in bytes.\r
815\r
816 @retval TRUE HMAC-MD5 data digest succeeded.\r
817 @retval FALSE HMAC-MD5 data digest failed.\r
532616bb 818 @retval FALSE This interface is not supported.\r
a8c44645 819\r
820**/\r
821BOOLEAN\r
822EFIAPI\r
823HmacMd5Update (\r
824 IN OUT VOID *HmacMd5Context,\r
825 IN CONST VOID *Data,\r
826 IN UINTN DataSize\r
827 );\r
828\r
829/**\r
830 Completes computation of the HMAC-MD5 digest value.\r
831\r
832 This function completes HMAC-MD5 hash computation and retrieves the digest value into\r
833 the specified memory. After this function has been called, the HMAC-MD5 context cannot\r
834 be used again.\r
835 HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be\r
836 finalized by HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined.\r
837\r
16d2c32c 838 If HmacMd5Context is NULL, then return FALSE.\r
839 If HashValue is NULL, then return FALSE.\r
532616bb 840 If this interface is not supported, then return FALSE.\r
a8c44645 841\r
842 @param[in, out] HmacMd5Context Pointer to the HMAC-MD5 context.\r
843 @param[out] HashValue Pointer to a buffer that receives the HMAC-MD5 digest\r
844 value (16 bytes).\r
845\r
846 @retval TRUE HMAC-MD5 digest computation succeeded.\r
847 @retval FALSE HMAC-MD5 digest computation failed.\r
532616bb 848 @retval FALSE This interface is not supported.\r
a8c44645 849\r
850**/\r
851BOOLEAN\r
852EFIAPI\r
853HmacMd5Final (\r
854 IN OUT VOID *HmacMd5Context,\r
855 OUT UINT8 *HmacValue\r
856 );\r
857\r
858/**\r
859 Retrieves the size, in bytes, of the context buffer required for HMAC-SHA1 operations.\r
860\r
532616bb 861 If this interface is not supported, then return zero.\r
862\r
a8c44645 863 @return The size, in bytes, of the context buffer required for HMAC-SHA1 operations.\r
532616bb 864 @retval 0 This interface is not supported.\r
a8c44645 865\r
866**/\r
867UINTN\r
868EFIAPI\r
869HmacSha1GetContextSize (\r
870 VOID\r
871 );\r
872\r
873/**\r
874 Initializes user-supplied memory pointed by HmacSha1Context as HMAC-SHA1 context for\r
875 subsequent use.\r
876\r
16d2c32c 877 If HmacSha1Context is NULL, then return FALSE.\r
532616bb 878 If this interface is not supported, then return FALSE.\r
a8c44645 879\r
880 @param[out] HmacSha1Context Pointer to HMAC-SHA1 context being initialized.\r
881 @param[in] Key Pointer to the user-supplied key.\r
882 @param[in] KeySize Key size in bytes.\r
883\r
884 @retval TRUE HMAC-SHA1 context initialization succeeded.\r
885 @retval FALSE HMAC-SHA1 context initialization failed.\r
532616bb 886 @retval FALSE This interface is not supported.\r
a8c44645 887\r
888**/\r
889BOOLEAN\r
890EFIAPI\r
891HmacSha1Init (\r
892 OUT VOID *HmacSha1Context,\r
893 IN CONST UINT8 *Key,\r
894 IN UINTN KeySize\r
895 );\r
896\r
897/**\r
898 Makes a copy of an existing HMAC-SHA1 context.\r
899\r
16d2c32c 900 If HmacSha1Context is NULL, then return FALSE.\r
901 If NewHmacSha1Context is NULL, then return FALSE.\r
532616bb 902 If this interface is not supported, then return FALSE.\r
a8c44645 903\r
904 @param[in] HmacSha1Context Pointer to HMAC-SHA1 context being copied.\r
905 @param[out] NewHmacSha1Context Pointer to new HMAC-SHA1 context.\r
906\r
907 @retval TRUE HMAC-SHA1 context copy succeeded.\r
908 @retval FALSE HMAC-SHA1 context copy failed.\r
532616bb 909 @retval FALSE This interface is not supported.\r
a8c44645 910\r
911**/\r
912BOOLEAN\r
913EFIAPI\r
914HmacSha1Duplicate (\r
915 IN CONST VOID *HmacSha1Context,\r
916 OUT VOID *NewHmacSha1Context\r
917 );\r
918\r
919/**\r
920 Digests the input data and updates HMAC-SHA1 context.\r
921\r
922 This function performs HMAC-SHA1 digest on a data buffer of the specified size.\r
923 It can be called multiple times to compute the digest of long or discontinuous data streams.\r
924 HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should not\r
925 be finalized by HmacSha1Final(). Behavior with invalid context is undefined.\r
926\r
16d2c32c 927 If HmacSha1Context is NULL, then return FALSE.\r
532616bb 928 If this interface is not supported, then return FALSE.\r
a8c44645 929\r
930 @param[in, out] HmacSha1Context Pointer to the HMAC-SHA1 context.\r
931 @param[in] Data Pointer to the buffer containing the data to be digested.\r
932 @param[in] DataSize Size of Data buffer in bytes.\r
933\r
934 @retval TRUE HMAC-SHA1 data digest succeeded.\r
935 @retval FALSE HMAC-SHA1 data digest failed.\r
532616bb 936 @retval FALSE This interface is not supported.\r
a8c44645 937\r
938**/\r
939BOOLEAN\r
940EFIAPI\r
941HmacSha1Update (\r
942 IN OUT VOID *HmacSha1Context,\r
943 IN CONST VOID *Data,\r
944 IN UINTN DataSize\r
945 );\r
946\r
947/**\r
948 Completes computation of the HMAC-SHA1 digest value.\r
949\r
950 This function completes HMAC-SHA1 hash computation and retrieves the digest value into\r
951 the specified memory. After this function has been called, the HMAC-SHA1 context cannot\r
952 be used again.\r
953 HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should\r
954 not be finalized by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined.\r
955\r
16d2c32c 956 If HmacSha1Context is NULL, then return FALSE.\r
957 If HashValue is NULL, then return FALSE.\r
532616bb 958 If this interface is not supported, then return FALSE.\r
a8c44645 959\r
960 @param[in, out] HmacSha1Context Pointer to the HMAC-SHA1 context.\r
961 @param[out] HashValue Pointer to a buffer that receives the HMAC-SHA1 digest\r
962 value (20 bytes).\r
963\r
964 @retval TRUE HMAC-SHA1 digest computation succeeded.\r
965 @retval FALSE HMAC-SHA1 digest computation failed.\r
532616bb 966 @retval FALSE This interface is not supported.\r
a8c44645 967\r
968**/\r
969BOOLEAN\r
970EFIAPI\r
971HmacSha1Final (\r
972 IN OUT VOID *HmacSha1Context,\r
973 OUT UINT8 *HmacValue\r
974 );\r
97f98500 975\r
97f98500
HT
976//=====================================================================================\r
977// Symmetric Cryptography Primitive\r
978//=====================================================================================\r
979\r
a8c44645 980/**\r
981 Retrieves the size, in bytes, of the context buffer required for TDES operations.\r
982\r
532616bb 983 If this interface is not supported, then return zero.\r
984\r
a8c44645 985 @return The size, in bytes, of the context buffer required for TDES operations.\r
532616bb 986 @retval 0 This interface is not supported.\r
a8c44645 987\r
988**/\r
989UINTN\r
990EFIAPI\r
991TdesGetContextSize (\r
992 VOID\r
993 );\r
994\r
995/**\r
996 Initializes user-supplied memory as TDES context for subsequent use.\r
997\r
998 This function initializes user-supplied memory pointed by TdesContext as TDES context.\r
6b8ebcb8 999 In addition, it sets up all TDES key materials for subsequent encryption and decryption\r
a8c44645 1000 operations.\r
1001 There are 3 key options as follows:\r
1002 KeyLength = 64, Keying option 1: K1 == K2 == K3 (Backward compatibility with DES)\r
1003 KeyLength = 128, Keying option 2: K1 != K2 and K3 = K1 (Less Security)\r
1004 KeyLength = 192 Keying option 3: K1 != K2 != K3 (Strongest)\r
1005\r
16d2c32c 1006 If TdesContext is NULL, then return FALSE.\r
1007 If Key is NULL, then return FALSE.\r
1008 If KeyLength is not valid, then return FALSE.\r
532616bb 1009 If this interface is not supported, then return FALSE.\r
a8c44645 1010\r
1011 @param[out] TdesContext Pointer to TDES context being initialized.\r
1012 @param[in] Key Pointer to the user-supplied TDES key.\r
1013 @param[in] KeyLength Length of TDES key in bits.\r
1014\r
1015 @retval TRUE TDES context initialization succeeded.\r
1016 @retval FALSE TDES context initialization failed.\r
532616bb 1017 @retval FALSE This interface is not supported.\r
97f98500 1018\r
a8c44645 1019**/\r
1020BOOLEAN\r
1021EFIAPI\r
1022TdesInit (\r
1023 OUT VOID *TdesContext,\r
1024 IN CONST UINT8 *Key,\r
1025 IN UINTN KeyLength\r
1026 );\r
1027\r
1028/**\r
1029 Performs TDES encryption on a data buffer of the specified size in ECB mode.\r
1030\r
1031 This function performs TDES encryption on data buffer pointed by Input, of specified\r
1032 size of InputSize, in ECB mode.\r
1033 InputSize must be multiple of block size (8 bytes). This function does not perform\r
1034 padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1035 TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
1036 invalid TDES context is undefined.\r
1037\r
16d2c32c 1038 If TdesContext is NULL, then return FALSE.\r
1039 If Input is NULL, then return FALSE.\r
1040 If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
1041 If Output is NULL, then return FALSE.\r
532616bb 1042 If this interface is not supported, then return FALSE.\r
a8c44645 1043\r
1044 @param[in] TdesContext Pointer to the TDES context.\r
1045 @param[in] Input Pointer to the buffer containing the data to be encrypted.\r
1046 @param[in] InputSize Size of the Input buffer in bytes.\r
1047 @param[out] Output Pointer to a buffer that receives the TDES encryption output.\r
1048\r
1049 @retval TRUE TDES encryption succeeded.\r
1050 @retval FALSE TDES encryption failed.\r
532616bb 1051 @retval FALSE This interface is not supported.\r
a8c44645 1052\r
1053**/\r
1054BOOLEAN\r
1055EFIAPI\r
1056TdesEcbEncrypt (\r
1057 IN VOID *TdesContext,\r
1058 IN CONST UINT8 *Input,\r
1059 IN UINTN InputSize,\r
1060 OUT UINT8 *Output\r
1061 );\r
1062\r
1063/**\r
1064 Performs TDES decryption on a data buffer of the specified size in ECB mode.\r
1065\r
1066 This function performs TDES decryption on data buffer pointed by Input, of specified\r
1067 size of InputSize, in ECB mode.\r
1068 InputSize must be multiple of block size (8 bytes). This function does not perform\r
1069 padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1070 TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
1071 invalid TDES context is undefined.\r
1072\r
16d2c32c 1073 If TdesContext is NULL, then return FALSE.\r
1074 If Input is NULL, then return FALSE.\r
1075 If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
1076 If Output is NULL, then return FALSE.\r
532616bb 1077 If this interface is not supported, then return FALSE.\r
a8c44645 1078\r
1079 @param[in] TdesContext Pointer to the TDES context.\r
1080 @param[in] Input Pointer to the buffer containing the data to be decrypted.\r
1081 @param[in] InputSize Size of the Input buffer in bytes.\r
1082 @param[out] Output Pointer to a buffer that receives the TDES decryption output.\r
1083\r
1084 @retval TRUE TDES decryption succeeded.\r
1085 @retval FALSE TDES decryption failed.\r
532616bb 1086 @retval FALSE This interface is not supported.\r
a8c44645 1087\r
1088**/\r
1089BOOLEAN\r
1090EFIAPI\r
1091TdesEcbDecrypt (\r
1092 IN VOID *TdesContext,\r
1093 IN CONST UINT8 *Input,\r
1094 IN UINTN InputSize,\r
1095 OUT UINT8 *Output\r
1096 );\r
1097\r
1098/**\r
1099 Performs TDES encryption on a data buffer of the specified size in CBC mode.\r
1100\r
1101 This function performs TDES encryption on data buffer pointed by Input, of specified\r
1102 size of InputSize, in CBC mode.\r
1103 InputSize must be multiple of block size (8 bytes). This function does not perform\r
1104 padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1105 Initialization vector should be one block size (8 bytes).\r
1106 TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
1107 invalid TDES context is undefined.\r
1108\r
16d2c32c 1109 If TdesContext is NULL, then return FALSE.\r
1110 If Input is NULL, then return FALSE.\r
1111 If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
1112 If Ivec is NULL, then return FALSE.\r
1113 If Output is NULL, then return FALSE.\r
532616bb 1114 If this interface is not supported, then return FALSE.\r
a8c44645 1115\r
1116 @param[in] TdesContext Pointer to the TDES context.\r
1117 @param[in] Input Pointer to the buffer containing the data to be encrypted.\r
1118 @param[in] InputSize Size of the Input buffer in bytes.\r
1119 @param[in] Ivec Pointer to initialization vector.\r
1120 @param[out] Output Pointer to a buffer that receives the TDES encryption output.\r
1121\r
1122 @retval TRUE TDES encryption succeeded.\r
1123 @retval FALSE TDES encryption failed.\r
532616bb 1124 @retval FALSE This interface is not supported.\r
a8c44645 1125\r
1126**/\r
1127BOOLEAN\r
1128EFIAPI\r
1129TdesCbcEncrypt (\r
1130 IN VOID *TdesContext,\r
1131 IN CONST UINT8 *Input,\r
1132 IN UINTN InputSize,\r
1133 IN CONST UINT8 *Ivec,\r
1134 OUT UINT8 *Output\r
1135 );\r
1136\r
1137/**\r
1138 Performs TDES decryption on a data buffer of the specified size in CBC mode.\r
1139\r
1140 This function performs TDES decryption on data buffer pointed by Input, of specified\r
1141 size of InputSize, in CBC mode.\r
1142 InputSize must be multiple of block size (8 bytes). This function does not perform\r
1143 padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1144 Initialization vector should be one block size (8 bytes).\r
1145 TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
1146 invalid TDES context is undefined.\r
1147\r
16d2c32c 1148 If TdesContext is NULL, then return FALSE.\r
1149 If Input is NULL, then return FALSE.\r
1150 If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
1151 If Ivec is NULL, then return FALSE.\r
1152 If Output is NULL, then return FALSE.\r
532616bb 1153 If this interface is not supported, then return FALSE.\r
a8c44645 1154\r
1155 @param[in] TdesContext Pointer to the TDES context.\r
1156 @param[in] Input Pointer to the buffer containing the data to be encrypted.\r
1157 @param[in] InputSize Size of the Input buffer in bytes.\r
1158 @param[in] Ivec Pointer to initialization vector.\r
1159 @param[out] Output Pointer to a buffer that receives the TDES encryption output.\r
1160\r
1161 @retval TRUE TDES decryption succeeded.\r
1162 @retval FALSE TDES decryption failed.\r
532616bb 1163 @retval FALSE This interface is not supported.\r
a8c44645 1164\r
1165**/\r
1166BOOLEAN\r
1167EFIAPI\r
1168TdesCbcDecrypt (\r
1169 IN VOID *TdesContext,\r
1170 IN CONST UINT8 *Input,\r
1171 IN UINTN InputSize,\r
1172 IN CONST UINT8 *Ivec,\r
1173 OUT UINT8 *Output\r
1174 );\r
1175\r
1176/**\r
1177 Retrieves the size, in bytes, of the context buffer required for AES operations.\r
1178\r
532616bb 1179 If this interface is not supported, then return zero.\r
1180\r
a8c44645 1181 @return The size, in bytes, of the context buffer required for AES operations.\r
532616bb 1182 @retval 0 This interface is not supported.\r
a8c44645 1183\r
1184**/\r
1185UINTN\r
1186EFIAPI\r
1187AesGetContextSize (\r
1188 VOID\r
1189 );\r
1190\r
1191/**\r
1192 Initializes user-supplied memory as AES context for subsequent use.\r
1193\r
1194 This function initializes user-supplied memory pointed by AesContext as AES context.\r
6b8ebcb8 1195 In addition, it sets up all AES key materials for subsequent encryption and decryption\r
a8c44645 1196 operations.\r
1197 There are 3 options for key length, 128 bits, 192 bits, and 256 bits.\r
1198\r
16d2c32c 1199 If AesContext is NULL, then return FALSE.\r
1200 If Key is NULL, then return FALSE.\r
1201 If KeyLength is not valid, then return FALSE.\r
532616bb 1202 If this interface is not supported, then return FALSE.\r
a8c44645 1203\r
1204 @param[out] AesContext Pointer to AES context being initialized.\r
1205 @param[in] Key Pointer to the user-supplied AES key.\r
1206 @param[in] KeyLength Length of AES key in bits.\r
1207\r
1208 @retval TRUE AES context initialization succeeded.\r
1209 @retval FALSE AES context initialization failed.\r
532616bb 1210 @retval FALSE This interface is not supported.\r
a8c44645 1211\r
1212**/\r
1213BOOLEAN\r
1214EFIAPI\r
1215AesInit (\r
1216 OUT VOID *AesContext,\r
1217 IN CONST UINT8 *Key,\r
1218 IN UINTN KeyLength\r
1219 );\r
1220\r
1221/**\r
1222 Performs AES encryption on a data buffer of the specified size in ECB mode.\r
1223\r
1224 This function performs AES encryption on data buffer pointed by Input, of specified\r
1225 size of InputSize, in ECB mode.\r
1226 InputSize must be multiple of block size (16 bytes). This function does not perform\r
1227 padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1228 AesContext should be already correctly initialized by AesInit(). Behavior with\r
1229 invalid AES context is undefined.\r
1230\r
16d2c32c 1231 If AesContext is NULL, then return FALSE.\r
1232 If Input is NULL, then return FALSE.\r
1233 If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1234 If Output is NULL, then return FALSE.\r
532616bb 1235 If this interface is not supported, then return FALSE.\r
a8c44645 1236\r
1237 @param[in] AesContext Pointer to the AES context.\r
1238 @param[in] Input Pointer to the buffer containing the data to be encrypted.\r
1239 @param[in] InputSize Size of the Input buffer in bytes.\r
1240 @param[out] Output Pointer to a buffer that receives the AES encryption output.\r
1241\r
1242 @retval TRUE AES encryption succeeded.\r
1243 @retval FALSE AES encryption failed.\r
532616bb 1244 @retval FALSE This interface is not supported.\r
a8c44645 1245\r
1246**/\r
1247BOOLEAN\r
1248EFIAPI\r
1249AesEcbEncrypt (\r
1250 IN VOID *AesContext,\r
1251 IN CONST UINT8 *Input,\r
1252 IN UINTN InputSize,\r
1253 OUT UINT8 *Output\r
1254 );\r
1255\r
1256/**\r
1257 Performs AES decryption on a data buffer of the specified size in ECB mode.\r
1258\r
1259 This function performs AES decryption on data buffer pointed by Input, of specified\r
1260 size of InputSize, in ECB mode.\r
1261 InputSize must be multiple of block size (16 bytes). This function does not perform\r
1262 padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1263 AesContext should be already correctly initialized by AesInit(). Behavior with\r
1264 invalid AES context is undefined.\r
1265\r
16d2c32c 1266 If AesContext is NULL, then return FALSE.\r
1267 If Input is NULL, then return FALSE.\r
1268 If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1269 If Output is NULL, then return FALSE.\r
532616bb 1270 If this interface is not supported, then return FALSE.\r
a8c44645 1271\r
1272 @param[in] AesContext Pointer to the AES context.\r
1273 @param[in] Input Pointer to the buffer containing the data to be decrypted.\r
1274 @param[in] InputSize Size of the Input buffer in bytes.\r
1275 @param[out] Output Pointer to a buffer that receives the AES decryption output.\r
1276\r
1277 @retval TRUE AES decryption succeeded.\r
1278 @retval FALSE AES decryption failed.\r
532616bb 1279 @retval FALSE This interface is not supported.\r
a8c44645 1280\r
1281**/\r
1282BOOLEAN\r
1283EFIAPI\r
1284AesEcbDecrypt (\r
1285 IN VOID *AesContext,\r
1286 IN CONST UINT8 *Input,\r
1287 IN UINTN InputSize,\r
1288 OUT UINT8 *Output\r
1289 );\r
1290\r
1291/**\r
1292 Performs AES encryption on a data buffer of the specified size in CBC mode.\r
1293\r
1294 This function performs AES encryption on data buffer pointed by Input, of specified\r
1295 size of InputSize, in CBC mode.\r
1296 InputSize must be multiple of block size (16 bytes). This function does not perform\r
1297 padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1298 Initialization vector should be one block size (16 bytes).\r
1299 AesContext should be already correctly initialized by AesInit(). Behavior with\r
1300 invalid AES context is undefined.\r
1301\r
16d2c32c 1302 If AesContext is NULL, then return FALSE.\r
1303 If Input is NULL, then return FALSE.\r
1304 If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1305 If Ivec is NULL, then return FALSE.\r
1306 If Output is NULL, then return FALSE.\r
532616bb 1307 If this interface is not supported, then return FALSE.\r
a8c44645 1308\r
1309 @param[in] AesContext Pointer to the AES context.\r
1310 @param[in] Input Pointer to the buffer containing the data to be encrypted.\r
1311 @param[in] InputSize Size of the Input buffer in bytes.\r
1312 @param[in] Ivec Pointer to initialization vector.\r
1313 @param[out] Output Pointer to a buffer that receives the AES encryption output.\r
1314\r
1315 @retval TRUE AES encryption succeeded.\r
1316 @retval FALSE AES encryption failed.\r
532616bb 1317 @retval FALSE This interface is not supported.\r
a8c44645 1318\r
1319**/\r
1320BOOLEAN\r
1321EFIAPI\r
1322AesCbcEncrypt (\r
1323 IN VOID *AesContext,\r
1324 IN CONST UINT8 *Input,\r
1325 IN UINTN InputSize,\r
1326 IN CONST UINT8 *Ivec,\r
1327 OUT UINT8 *Output\r
1328 );\r
1329\r
1330/**\r
1331 Performs AES decryption on a data buffer of the specified size in CBC mode.\r
1332\r
1333 This function performs AES decryption on data buffer pointed by Input, of specified\r
1334 size of InputSize, in CBC mode.\r
1335 InputSize must be multiple of block size (16 bytes). This function does not perform\r
1336 padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1337 Initialization vector should be one block size (16 bytes).\r
1338 AesContext should be already correctly initialized by AesInit(). Behavior with\r
1339 invalid AES context is undefined.\r
1340\r
16d2c32c 1341 If AesContext is NULL, then return FALSE.\r
1342 If Input is NULL, then return FALSE.\r
1343 If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1344 If Ivec is NULL, then return FALSE.\r
1345 If Output is NULL, then return FALSE.\r
532616bb 1346 If this interface is not supported, then return FALSE.\r
a8c44645 1347\r
1348 @param[in] AesContext Pointer to the AES context.\r
1349 @param[in] Input Pointer to the buffer containing the data to be encrypted.\r
1350 @param[in] InputSize Size of the Input buffer in bytes.\r
1351 @param[in] Ivec Pointer to initialization vector.\r
1352 @param[out] Output Pointer to a buffer that receives the AES encryption output.\r
1353\r
1354 @retval TRUE AES decryption succeeded.\r
1355 @retval FALSE AES decryption failed.\r
532616bb 1356 @retval FALSE This interface is not supported.\r
a8c44645 1357\r
1358**/\r
1359BOOLEAN\r
1360EFIAPI\r
1361AesCbcDecrypt (\r
1362 IN VOID *AesContext,\r
1363 IN CONST UINT8 *Input,\r
1364 IN UINTN InputSize,\r
1365 IN CONST UINT8 *Ivec,\r
1366 OUT UINT8 *Output\r
1367 );\r
1368\r
1369/**\r
1370 Retrieves the size, in bytes, of the context buffer required for ARC4 operations.\r
1371\r
532616bb 1372 If this interface is not supported, then return zero.\r
1373\r
a8c44645 1374 @return The size, in bytes, of the context buffer required for ARC4 operations.\r
532616bb 1375 @retval 0 This interface is not supported.\r
a8c44645 1376\r
1377**/\r
1378UINTN\r
1379EFIAPI\r
1380Arc4GetContextSize (\r
1381 VOID\r
1382 );\r
1383\r
1384/**\r
1385 Initializes user-supplied memory as ARC4 context for subsequent use.\r
1386\r
1387 This function initializes user-supplied memory pointed by Arc4Context as ARC4 context.\r
6b8ebcb8 1388 In addition, it sets up all ARC4 key materials for subsequent encryption and decryption\r
a8c44645 1389 operations.\r
1390\r
16d2c32c 1391 If Arc4Context is NULL, then return FALSE.\r
1392 If Key is NULL, then return FALSE.\r
1393 If KeySize does not in the range of [5, 256] bytes, then return FALSE.\r
532616bb 1394 If this interface is not supported, then return FALSE.\r
a8c44645 1395\r
1396 @param[out] Arc4Context Pointer to ARC4 context being initialized.\r
1397 @param[in] Key Pointer to the user-supplied ARC4 key.\r
1398 @param[in] KeySize Size of ARC4 key in bytes.\r
1399\r
1400 @retval TRUE ARC4 context initialization succeeded.\r
1401 @retval FALSE ARC4 context initialization failed.\r
532616bb 1402 @retval FALSE This interface is not supported.\r
a8c44645 1403\r
1404**/\r
1405BOOLEAN\r
1406EFIAPI\r
1407Arc4Init (\r
1408 OUT VOID *Arc4Context,\r
1409 IN CONST UINT8 *Key,\r
1410 IN UINTN KeySize\r
1411 );\r
1412\r
1413/**\r
1414 Performs ARC4 encryption on a data buffer of the specified size.\r
1415\r
1416 This function performs ARC4 encryption on data buffer pointed by Input, of specified\r
1417 size of InputSize.\r
1418 Arc4Context should be already correctly initialized by Arc4Init(). Behavior with\r
1419 invalid ARC4 context is undefined.\r
1420\r
16d2c32c 1421 If Arc4Context is NULL, then return FALSE.\r
1422 If Input is NULL, then return FALSE.\r
1423 If Output is NULL, then return FALSE.\r
532616bb 1424 If this interface is not supported, then return FALSE.\r
a8c44645 1425\r
1426 @param[in] Arc4Context Pointer to the ARC4 context.\r
1427 @param[in] Input Pointer to the buffer containing the data to be encrypted.\r
1428 @param[in] InputSize Size of the Input buffer in bytes.\r
1429 @param[out] Output Pointer to a buffer that receives the ARC4 encryption output.\r
1430\r
1431 @retval TRUE ARC4 encryption succeeded.\r
1432 @retval FALSE ARC4 encryption failed.\r
532616bb 1433 @retval FALSE This interface is not supported.\r
a8c44645 1434\r
1435**/\r
1436BOOLEAN\r
1437EFIAPI\r
1438Arc4Encrypt (\r
1439 IN OUT VOID *Arc4Context,\r
1440 IN CONST UINT8 *Input,\r
1441 IN UINTN InputSize,\r
1442 OUT UINT8 *Output\r
1443 );\r
1444\r
1445/**\r
1446 Performs ARC4 decryption on a data buffer of the specified size.\r
1447\r
1448 This function performs ARC4 decryption on data buffer pointed by Input, of specified\r
1449 size of InputSize.\r
1450 Arc4Context should be already correctly initialized by Arc4Init(). Behavior with\r
1451 invalid ARC4 context is undefined.\r
1452\r
16d2c32c 1453 If Arc4Context is NULL, then return FALSE.\r
1454 If Input is NULL, then return FALSE.\r
1455 If Output is NULL, then return FALSE.\r
532616bb 1456 If this interface is not supported, then return FALSE.\r
a8c44645 1457\r
1458 @param[in] Arc4Context Pointer to the ARC4 context.\r
1459 @param[in] Input Pointer to the buffer containing the data to be decrypted.\r
1460 @param[in] InputSize Size of the Input buffer in bytes.\r
1461 @param[out] Output Pointer to a buffer that receives the ARC4 decryption output.\r
1462\r
1463 @retval TRUE ARC4 decryption succeeded.\r
1464 @retval FALSE ARC4 decryption failed.\r
532616bb 1465 @retval FALSE This interface is not supported.\r
a8c44645 1466\r
1467**/\r
1468BOOLEAN\r
1469EFIAPI\r
1470Arc4Decrypt (\r
1471 IN OUT VOID *Arc4Context,\r
1472 IN UINT8 *Input,\r
1473 IN UINTN InputSize,\r
1474 OUT UINT8 *Output\r
1475 );\r
1476\r
1477/**\r
1478 Resets the ARC4 context to the initial state.\r
1479\r
1480 The function resets the ARC4 context to the state it had immediately after the\r
1481 ARC4Init() function call.\r
1482 Contrary to ARC4Init(), Arc4Reset() requires no secret key as input, but ARC4 context\r
1483 should be already correctly initialized by ARC4Init().\r
1484\r
16d2c32c 1485 If Arc4Context is NULL, then return FALSE.\r
532616bb 1486 If this interface is not supported, then return FALSE.\r
a8c44645 1487\r
1488 @param[in, out] Arc4Context Pointer to the ARC4 context.\r
1489\r
1490 @retval TRUE ARC4 reset succeeded.\r
1491 @retval FALSE ARC4 reset failed.\r
532616bb 1492 @retval FALSE This interface is not supported.\r
a8c44645 1493\r
1494**/\r
1495BOOLEAN\r
1496EFIAPI\r
1497Arc4Reset (\r
1498 IN OUT VOID *Arc4Context\r
1499 );\r
97f98500
HT
1500\r
1501//=====================================================================================\r
1502// Asymmetric Cryptography Primitive\r
1503//=====================================================================================\r
1504\r
1505/**\r
a8c44645 1506 Allocates and initializes one RSA context for subsequent use.\r
97f98500 1507\r
a8c44645 1508 @return Pointer to the RSA context that has been initialized.\r
97f98500
HT
1509 If the allocations fails, RsaNew() returns NULL.\r
1510\r
1511**/\r
1512VOID *\r
1513EFIAPI\r
1514RsaNew (\r
1515 VOID\r
1516 );\r
1517\r
97f98500 1518/**\r
a8c44645 1519 Release the specified RSA context.\r
1520\r
16d2c32c 1521 If RsaContext is NULL, then return FALSE.\r
97f98500
HT
1522\r
1523 @param[in] RsaContext Pointer to the RSA context to be released.\r
1524\r
1525**/\r
1526VOID\r
1527EFIAPI\r
1528RsaFree (\r
1529 IN VOID *RsaContext\r
1530 );\r
1531\r
97f98500 1532/**\r
a8c44645 1533 Sets the tag-designated key component into the established RSA context.\r
1534\r
1535 This function sets the tag-designated RSA key component into the established\r
1536 RSA context from the user-specified non-negative integer (octet string format\r
1537 represented in RSA PKCS#1).\r
1538 If BigNumber is NULL, then the specified key componenet in RSA context is cleared.\r
97f98500 1539\r
16d2c32c 1540 If RsaContext is NULL, then return FALSE.\r
97f98500
HT
1541\r
1542 @param[in, out] RsaContext Pointer to RSA context being set.\r
1543 @param[in] KeyTag Tag of RSA key component being set.\r
1544 @param[in] BigNumber Pointer to octet integer buffer.\r
a8c44645 1545 If NULL, then the specified key componenet in RSA\r
1546 context is cleared.\r
1547 @param[in] BnSize Size of big number buffer in bytes.\r
1548 If BigNumber is NULL, then it is ignored.\r
97f98500 1549\r
a8c44645 1550 @retval TRUE RSA key component was set successfully.\r
1551 @retval FALSE Invalid RSA key component tag.\r
97f98500
HT
1552\r
1553**/\r
1554BOOLEAN\r
1555EFIAPI\r
1556RsaSetKey (\r
a8c44645 1557 IN OUT VOID *RsaContext,\r
1558 IN RSA_KEY_TAG KeyTag,\r
1559 IN CONST UINT8 *BigNumber,\r
1560 IN UINTN BnSize\r
1561 );\r
1562\r
1563/**\r
1564 Gets the tag-designated RSA key component from the established RSA context.\r
1565\r
1566 This function retrieves the tag-designated RSA key component from the\r
1567 established RSA context as a non-negative integer (octet string format\r
1568 represented in RSA PKCS#1).\r
1569 If specified key component has not been set or has been cleared, then returned\r
1570 BnSize is set to 0.\r
1571 If the BigNumber buffer is too small to hold the contents of the key, FALSE\r
1572 is returned and BnSize is set to the required buffer size to obtain the key.\r
1573\r
16d2c32c 1574 If RsaContext is NULL, then return FALSE.\r
1575 If BnSize is NULL, then return FALSE.\r
1576 If BnSize is large enough but BigNumber is NULL, then return FALSE.\r
532616bb 1577 If this interface is not supported, then return FALSE.\r
a8c44645 1578\r
1579 @param[in, out] RsaContext Pointer to RSA context being set.\r
1580 @param[in] KeyTag Tag of RSA key component being set.\r
1581 @param[out] BigNumber Pointer to octet integer buffer.\r
1582 @param[in, out] BnSize On input, the size of big number buffer in bytes.\r
1583 On output, the size of data returned in big number buffer in bytes.\r
1584\r
1585 @retval TRUE RSA key component was retrieved successfully.\r
1586 @retval FALSE Invalid RSA key component tag.\r
1587 @retval FALSE BnSize is too small.\r
532616bb 1588 @retval FALSE This interface is not supported.\r
a8c44645 1589\r
1590**/\r
1591BOOLEAN\r
1592EFIAPI\r
1593RsaGetKey (\r
1594 IN OUT VOID *RsaContext,\r
1595 IN RSA_KEY_TAG KeyTag,\r
1596 OUT UINT8 *BigNumber,\r
1597 IN OUT UINTN *BnSize\r
1598 );\r
1599\r
1600/**\r
1601 Generates RSA key components.\r
1602\r
1603 This function generates RSA key components. It takes RSA public exponent E and\r
1604 length in bits of RSA modulus N as input, and generates all key components.\r
1605 If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.\r
1606\r
1607 Before this function can be invoked, pseudorandom number generator must be correctly\r
1608 initialized by RandomSeed().\r
1609\r
16d2c32c 1610 If RsaContext is NULL, then return FALSE.\r
532616bb 1611 If this interface is not supported, then return FALSE.\r
a8c44645 1612\r
1613 @param[in, out] RsaContext Pointer to RSA context being set.\r
1614 @param[in] ModulusLength Length of RSA modulus N in bits.\r
1615 @param[in] PublicExponent Pointer to RSA public exponent.\r
2ac68e8b 1616 @param[in] PublicExponentSize Size of RSA public exponent buffer in bytes.\r
a8c44645 1617\r
1618 @retval TRUE RSA key component was generated successfully.\r
1619 @retval FALSE Invalid RSA key component tag.\r
532616bb 1620 @retval FALSE This interface is not supported.\r
a8c44645 1621\r
1622**/\r
1623BOOLEAN\r
1624EFIAPI\r
1625RsaGenerateKey (\r
1626 IN OUT VOID *RsaContext,\r
1627 IN UINTN ModulusLength,\r
1628 IN CONST UINT8 *PublicExponent,\r
1629 IN UINTN PublicExponentSize\r
1630 );\r
1631\r
1632/**\r
1633 Validates key components of RSA context.\r
952bd229
QL
1634 NOTE: This function performs integrity checks on all the RSA key material, so\r
1635 the RSA key structure must contain all the private key data.\r
a8c44645 1636\r
1637 This function validates key compoents of RSA context in following aspects:\r
1638 - Whether p is a prime\r
1639 - Whether q is a prime\r
1640 - Whether n = p * q\r
1641 - Whether d*e = 1 mod lcm(p-1,q-1)\r
1642\r
16d2c32c 1643 If RsaContext is NULL, then return FALSE.\r
532616bb 1644 If this interface is not supported, then return FALSE.\r
a8c44645 1645\r
1646 @param[in] RsaContext Pointer to RSA context to check.\r
1647\r
1648 @retval TRUE RSA key components are valid.\r
1649 @retval FALSE RSA key components are not valid.\r
532616bb 1650 @retval FALSE This interface is not supported.\r
a8c44645 1651\r
1652**/\r
1653BOOLEAN\r
1654EFIAPI\r
1655RsaCheckKey (\r
1656 IN VOID *RsaContext\r
97f98500
HT
1657 );\r
1658\r
a8c44645 1659/**\r
1660 Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.\r
1661\r
1662 This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in\r
1663 RSA PKCS#1.\r
1664 If the Signature buffer is too small to hold the contents of signature, FALSE\r
1665 is returned and SigSize is set to the required buffer size to obtain the signature.\r
1666\r
16d2c32c 1667 If RsaContext is NULL, then return FALSE.\r
1668 If MessageHash is NULL, then return FALSE.\r
1669 If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.\r
1670 If SigSize is large enough but Signature is NULL, then return FALSE.\r
532616bb 1671 If this interface is not supported, then return FALSE.\r
a8c44645 1672\r
1673 @param[in] RsaContext Pointer to RSA context for signature generation.\r
1674 @param[in] MessageHash Pointer to octet message hash to be signed.\r
1675 @param[in] HashSize Size of the message hash in bytes.\r
1676 @param[out] Signature Pointer to buffer to receive RSA PKCS1-v1_5 signature.\r
1677 @param[in, out] SigSize On input, the size of Signature buffer in bytes.\r
b7d320f8 1678 On output, the size of data returned in Signature buffer in bytes.\r
a8c44645 1679\r
1680 @retval TRUE Signature successfully generated in PKCS1-v1_5.\r
1681 @retval FALSE Signature generation failed.\r
1682 @retval FALSE SigSize is too small.\r
532616bb 1683 @retval FALSE This interface is not supported.\r
a8c44645 1684\r
1685**/\r
1686BOOLEAN\r
1687EFIAPI\r
1688RsaPkcs1Sign (\r
1689 IN VOID *RsaContext,\r
1690 IN CONST UINT8 *MessageHash,\r
1691 IN UINTN HashSize,\r
1692 OUT UINT8 *Signature,\r
1693 IN OUT UINTN *SigSize\r
1694 );\r
97f98500
HT
1695\r
1696/**\r
1697 Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in\r
1698 RSA PKCS#1.\r
1699\r
16d2c32c 1700 If RsaContext is NULL, then return FALSE.\r
1701 If MessageHash is NULL, then return FALSE.\r
1702 If Signature is NULL, then return FALSE.\r
1703 If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.\r
97f98500
HT
1704\r
1705 @param[in] RsaContext Pointer to RSA context for signature verification.\r
1706 @param[in] MessageHash Pointer to octet message hash to be checked.\r
a8c44645 1707 @param[in] HashSize Size of the message hash in bytes.\r
97f98500 1708 @param[in] Signature Pointer to RSA PKCS1-v1_5 signature to be verified.\r
a8c44645 1709 @param[in] SigSize Size of signature in bytes.\r
97f98500 1710\r
a8c44645 1711 @retval TRUE Valid signature encoded in PKCS1-v1_5.\r
1712 @retval FALSE Invalid signature or invalid RSA context.\r
97f98500
HT
1713\r
1714**/\r
1715BOOLEAN\r
1716EFIAPI\r
1717RsaPkcs1Verify (\r
1718 IN VOID *RsaContext,\r
1719 IN CONST UINT8 *MessageHash,\r
a8c44645 1720 IN UINTN HashSize,\r
8c5720b4 1721 IN CONST UINT8 *Signature,\r
a8c44645 1722 IN UINTN SigSize\r
97f98500
HT
1723 );\r
1724\r
4a567c96 1725/**\r
1726 Retrieve the RSA Private Key from the password-protected PEM key data.\r
1727\r
532616bb 1728 If PemData is NULL, then return FALSE.\r
1729 If RsaContext is NULL, then return FALSE.\r
1730 If this interface is not supported, then return FALSE.\r
1731\r
4a567c96 1732 @param[in] PemData Pointer to the PEM-encoded key data to be retrieved.\r
1733 @param[in] PemSize Size of the PEM key data in bytes.\r
1734 @param[in] Password NULL-terminated passphrase used for encrypted PEM key data.\r
1735 @param[out] RsaContext Pointer to new-generated RSA context which contain the retrieved\r
1736 RSA private key component. Use RsaFree() function to free the\r
1737 resource.\r
1738\r
4a567c96 1739 @retval TRUE RSA Private Key was retrieved successfully.\r
1740 @retval FALSE Invalid PEM key data or incorrect password.\r
532616bb 1741 @retval FALSE This interface is not supported.\r
4a567c96 1742\r
1743**/\r
1744BOOLEAN\r
1745EFIAPI\r
1746RsaGetPrivateKeyFromPem (\r
1747 IN CONST UINT8 *PemData,\r
1748 IN UINTN PemSize,\r
1749 IN CONST CHAR8 *Password,\r
1750 OUT VOID **RsaContext\r
1751 );\r
1752\r
1753/**\r
1754 Retrieve the RSA Public Key from one DER-encoded X509 certificate.\r
1755\r
532616bb 1756 If Cert is NULL, then return FALSE.\r
1757 If RsaContext is NULL, then return FALSE.\r
1758 If this interface is not supported, then return FALSE.\r
1759\r
4a567c96 1760 @param[in] Cert Pointer to the DER-encoded X509 certificate.\r
1761 @param[in] CertSize Size of the X509 certificate in bytes.\r
1762 @param[out] RsaContext Pointer to new-generated RSA context which contain the retrieved\r
1763 RSA public key component. Use RsaFree() function to free the\r
1764 resource.\r
1765\r
4a567c96 1766 @retval TRUE RSA Public Key was retrieved successfully.\r
1767 @retval FALSE Fail to retrieve RSA public key from X509 certificate.\r
532616bb 1768 @retval FALSE This interface is not supported.\r
4a567c96 1769\r
1770**/\r
1771BOOLEAN\r
1772EFIAPI\r
1773RsaGetPublicKeyFromX509 (\r
1774 IN CONST UINT8 *Cert,\r
1775 IN UINTN CertSize,\r
1776 OUT VOID **RsaContext\r
1777 );\r
1778\r
1779/**\r
1780 Retrieve the subject bytes from one X.509 certificate.\r
1781\r
532616bb 1782 If Cert is NULL, then return FALSE.\r
1783 If SubjectSize is NULL, then return FALSE.\r
1784 If this interface is not supported, then return FALSE.\r
1785\r
4a567c96 1786 @param[in] Cert Pointer to the DER-encoded X509 certificate.\r
1787 @param[in] CertSize Size of the X509 certificate in bytes.\r
1788 @param[out] CertSubject Pointer to the retrieved certificate subject bytes.\r
1789 @param[in, out] SubjectSize The size in bytes of the CertSubject buffer on input,\r
1790 and the size of buffer returned CertSubject on output.\r
1791\r
4a567c96 1792 @retval TRUE The certificate subject retrieved successfully.\r
1793 @retval FALSE Invalid certificate, or the SubjectSize is too small for the result.\r
1794 The SubjectSize will be updated with the required size.\r
532616bb 1795 @retval FALSE This interface is not supported.\r
4a567c96 1796\r
1797**/\r
1798BOOLEAN\r
1799EFIAPI\r
1800X509GetSubjectName (\r
1801 IN CONST UINT8 *Cert,\r
1802 IN UINTN CertSize,\r
1803 OUT UINT8 *CertSubject,\r
1804 IN OUT UINTN *SubjectSize\r
1805 );\r
1806\r
1807/**\r
1808 Verify one X509 certificate was issued by the trusted CA.\r
1809\r
532616bb 1810 If Cert is NULL, then return FALSE.\r
1811 If CACert is NULL, then return FALSE.\r
1812 If this interface is not supported, then return FALSE.\r
1813\r
4a567c96 1814 @param[in] Cert Pointer to the DER-encoded X509 certificate to be verified.\r
1815 @param[in] CertSize Size of the X509 certificate in bytes.\r
1816 @param[in] CACert Pointer to the DER-encoded trusted CA certificate.\r
1817 @param[in] CACertSize Size of the CA Certificate in bytes.\r
1818\r
4a567c96 1819 @retval TRUE The certificate was issued by the trusted CA.\r
1820 @retval FALSE Invalid certificate or the certificate was not issued by the given\r
1821 trusted CA.\r
532616bb 1822 @retval FALSE This interface is not supported.\r
4a567c96 1823\r
1824**/\r
1825BOOLEAN\r
1826EFIAPI\r
1827X509VerifyCert (\r
1828 IN CONST UINT8 *Cert,\r
1829 IN UINTN CertSize,\r
1830 IN CONST UINT8 *CACert,\r
1831 IN UINTN CACertSize\r
1832 );\r
1833\r
b7d320f8 1834/**\r
1835 Construct a X509 object from DER-encoded certificate data.\r
1836\r
16d2c32c 1837 If Cert is NULL, then return FALSE.\r
1838 If SingleX509Cert is NULL, then return FALSE.\r
532616bb 1839 If this interface is not supported, then return FALSE.\r
b7d320f8 1840\r
1841 @param[in] Cert Pointer to the DER-encoded certificate data.\r
1842 @param[in] CertSize The size of certificate data in bytes.\r
1843 @param[out] SingleX509Cert The generated X509 object.\r
1844\r
1845 @retval TRUE The X509 object generation succeeded.\r
1846 @retval FALSE The operation failed.\r
532616bb 1847 @retval FALSE This interface is not supported.\r
b7d320f8 1848\r
1849**/\r
1850BOOLEAN\r
1851EFIAPI\r
1852X509ConstructCertificate (\r
1853 IN CONST UINT8 *Cert,\r
1854 IN UINTN CertSize,\r
1855 OUT UINT8 **SingleX509Cert\r
1856 );\r
1857\r
1858/**\r
1859 Construct a X509 stack object from a list of DER-encoded certificate data.\r
1860\r
16d2c32c 1861 If X509Stack is NULL, then return FALSE.\r
532616bb 1862 If this interface is not supported, then return FALSE.\r
b7d320f8 1863\r
952bd229 1864 @param[in, out] X509Stack On input, pointer to an existing or NULL X509 stack object.\r
b7d320f8 1865 On output, pointer to the X509 stack object with new\r
1866 inserted X509 certificate.\r
1867 @param ... A list of DER-encoded single certificate data followed\r
1868 by certificate size. A NULL terminates the list. The\r
1869 pairs are the arguments to X509ConstructCertificate().\r
2ac68e8b 1870\r
b7d320f8 1871 @retval TRUE The X509 stack construction succeeded.\r
1872 @retval FALSE The construction operation failed.\r
532616bb 1873 @retval FALSE This interface is not supported.\r
b7d320f8 1874\r
1875**/\r
1876BOOLEAN\r
1877EFIAPI\r
1878X509ConstructCertificateStack (\r
1879 IN OUT UINT8 **X509Stack,\r
2ac68e8b 1880 ...\r
b7d320f8 1881 );\r
1882\r
1883/**\r
1884 Release the specified X509 object.\r
1885\r
532616bb 1886 If the interface is not supported, then ASSERT().\r
b7d320f8 1887\r
1888 @param[in] X509Cert Pointer to the X509 object to be released.\r
1889\r
1890**/\r
1891VOID\r
1892EFIAPI\r
1893X509Free (\r
1894 IN VOID *X509Cert\r
1895 );\r
1896\r
1897/**\r
1898 Release the specified X509 stack object.\r
1899\r
532616bb 1900 If the interface is not supported, then ASSERT().\r
b7d320f8 1901\r
1902 @param[in] X509Stack Pointer to the X509 stack object to be released.\r
1903\r
1904**/\r
1905VOID\r
1906EFIAPI\r
1907X509StackFree (\r
1908 IN VOID *X509Stack\r
1909 );\r
1910\r
12d95665
LQ
1911/**\r
1912 Retrieve the TBSCertificate from one given X.509 certificate.\r
1913\r
1914 @param[in] Cert Pointer to the given DER-encoded X509 certificate.\r
1915 @param[in] CertSize Size of the X509 certificate in bytes.\r
1916 @param[out] TBSCert DER-Encoded To-Be-Signed certificate.\r
1917 @param[out] TBSCertSize Size of the TBS certificate in bytes.\r
1918\r
1919 If Cert is NULL, then return FALSE.\r
1920 If TBSCert is NULL, then return FALSE.\r
1921 If TBSCertSize is NULL, then return FALSE.\r
1922 If this interface is not supported, then return FALSE.\r
1923\r
1924 @retval TRUE The TBSCertificate was retrieved successfully.\r
1925 @retval FALSE Invalid X.509 certificate.\r
1926\r
1927**/\r
1928BOOLEAN\r
1929EFIAPI\r
1930X509GetTBSCert (\r
1931 IN CONST UINT8 *Cert,\r
1932 IN UINTN CertSize,\r
1933 OUT UINT8 **TBSCert,\r
1934 OUT UINTN *TBSCertSize\r
1935 );\r
1936\r
e8b4eb04 1937/**\r
1938 Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:\r
1939 Cryptographic Message Syntax Standard". The input signed data could be wrapped\r
1940 in a ContentInfo structure.\r
1941\r
1942 If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then\r
1943 return FALSE. If P7Length overflow, then return FAlSE.\r
532616bb 1944 If this interface is not supported, then return FALSE.\r
e8b4eb04 1945\r
1946 @param[in] P7Data Pointer to the PKCS#7 message to verify.\r
1947 @param[in] P7Length Length of the PKCS#7 message in bytes.\r
1948 @param[out] CertStack Pointer to Signer's certificates retrieved from P7Data.\r
1949 It's caller's responsiblity to free the buffer.\r
1950 @param[out] StackLength Length of signer's certificates in bytes.\r
1951 @param[out] TrustedCert Pointer to a trusted certificate from Signer's certificates.\r
1952 It's caller's responsiblity to free the buffer.\r
1953 @param[out] CertLength Length of the trusted certificate in bytes.\r
1954\r
1955 @retval TRUE The operation is finished successfully.\r
1956 @retval FALSE Error occurs during the operation.\r
532616bb 1957 @retval FALSE This interface is not supported.\r
e8b4eb04 1958\r
1959**/\r
1960BOOLEAN\r
1961EFIAPI\r
1962Pkcs7GetSigners (\r
1963 IN CONST UINT8 *P7Data,\r
1964 IN UINTN P7Length,\r
1965 OUT UINT8 **CertStack,\r
1966 OUT UINTN *StackLength,\r
1967 OUT UINT8 **TrustedCert,\r
1968 OUT UINTN *CertLength\r
1969 );\r
1970\r
1971/**\r
1972 Wrap function to use free() to free allocated memory for certificates.\r
1973\r
532616bb 1974 If this interface is not supported, then ASSERT().\r
1975\r
e8b4eb04 1976 @param[in] Certs Pointer to the certificates to be freed.\r
1977\r
1978**/\r
1979VOID\r
1980EFIAPI\r
1981Pkcs7FreeSigners (\r
1982 IN UINT8 *Certs\r
1983 );\r
1984\r
b7d320f8 1985/**\r
1986 Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message\r
1987 Syntax Standard, version 1.5". This interface is only intended to be used for\r
1988 application to perform PKCS#7 functionality validation.\r
1989\r
532616bb 1990 If this interface is not supported, then return FALSE.\r
1991\r
b7d320f8 1992 @param[in] PrivateKey Pointer to the PEM-formatted private key data for\r
1993 data signing.\r
1994 @param[in] PrivateKeySize Size of the PEM private key data in bytes.\r
1995 @param[in] KeyPassword NULL-terminated passphrase used for encrypted PEM\r
1996 key data.\r
1997 @param[in] InData Pointer to the content to be signed.\r
1998 @param[in] InDataSize Size of InData in bytes.\r
1999 @param[in] SignCert Pointer to signer's DER-encoded certificate to sign with.\r
2000 @param[in] OtherCerts Pointer to an optional additional set of certificates to\r
2001 include in the PKCS#7 signedData (e.g. any intermediate\r
2002 CAs in the chain).\r
2003 @param[out] SignedData Pointer to output PKCS#7 signedData.\r
2004 @param[out] SignedDataSize Size of SignedData in bytes.\r
2005\r
2006 @retval TRUE PKCS#7 data signing succeeded.\r
2007 @retval FALSE PKCS#7 data signing failed.\r
532616bb 2008 @retval FALSE This interface is not supported.\r
b7d320f8 2009\r
2010**/\r
2011BOOLEAN\r
2012EFIAPI\r
2013Pkcs7Sign (\r
2014 IN CONST UINT8 *PrivateKey,\r
2015 IN UINTN PrivateKeySize,\r
2016 IN CONST UINT8 *KeyPassword,\r
2017 IN UINT8 *InData,\r
2018 IN UINTN InDataSize,\r
2019 IN UINT8 *SignCert,\r
2020 IN UINT8 *OtherCerts OPTIONAL,\r
2021 OUT UINT8 **SignedData,\r
2022 OUT UINTN *SignedDataSize\r
2023 );\r
2024\r
97f98500 2025/**\r
e8b4eb04 2026 Verifies the validility of a PKCS#7 signed data as described in "PKCS #7:\r
2027 Cryptographic Message Syntax Standard". The input signed data could be wrapped\r
2028 in a ContentInfo structure.\r
97f98500 2029\r
e8b4eb04 2030 If P7Data, TrustedCert or InData is NULL, then return FALSE.\r
2031 If P7Length, CertLength or DataLength overflow, then return FAlSE.\r
532616bb 2032 If this interface is not supported, then return FALSE.\r
97f98500
HT
2033\r
2034 @param[in] P7Data Pointer to the PKCS#7 message to verify.\r
e8b4eb04 2035 @param[in] P7Length Length of the PKCS#7 message in bytes.\r
97f98500
HT
2036 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which\r
2037 is used for certificate chain verification.\r
e8b4eb04 2038 @param[in] CertLength Length of the trusted certificate in bytes.\r
97f98500 2039 @param[in] InData Pointer to the content to be verified.\r
e8b4eb04 2040 @param[in] DataLength Length of InData in bytes.\r
97f98500 2041\r
a8c44645 2042 @retval TRUE The specified PKCS#7 signed data is valid.\r
2043 @retval FALSE Invalid PKCS#7 signed data.\r
532616bb 2044 @retval FALSE This interface is not supported.\r
97f98500
HT
2045\r
2046**/\r
2047BOOLEAN\r
2048EFIAPI\r
2049Pkcs7Verify (\r
2050 IN CONST UINT8 *P7Data,\r
e8b4eb04 2051 IN UINTN P7Length,\r
97f98500 2052 IN CONST UINT8 *TrustedCert,\r
e8b4eb04 2053 IN UINTN CertLength,\r
97f98500 2054 IN CONST UINT8 *InData,\r
e8b4eb04 2055 IN UINTN DataLength\r
a8c44645 2056 );\r
2057\r
afeb55e4
QL
2058/**\r
2059 Extracts the attached content from a PKCS#7 signed data if existed. The input signed\r
2060 data could be wrapped in a ContentInfo structure.\r
2061\r
2062 If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow,\r
2063 then return FAlSE. If the P7Data is not correctly formatted, then return FALSE.\r
2064\r
2065 Caution: This function may receive untrusted input. So this function will do\r
2066 basic check for PKCS#7 data structure.\r
2067\r
2068 @param[in] P7Data Pointer to the PKCS#7 signed data to process.\r
2069 @param[in] P7Length Length of the PKCS#7 signed data in bytes.\r
2070 @param[out] Content Pointer to the extracted content from the PKCS#7 signedData.\r
2071 It's caller's responsiblity to free the buffer.\r
2072 @param[out] ContentSize The size of the extracted content in bytes.\r
2073\r
2074 @retval TRUE The P7Data was correctly formatted for processing.\r
2075 @retval FALSE The P7Data was not correctly formatted for processing.\r
2076\r
2077*/\r
2078BOOLEAN\r
2079EFIAPI\r
2080Pkcs7GetAttachedContent (\r
2081 IN CONST UINT8 *P7Data,\r
2082 IN UINTN P7Length,\r
2083 OUT VOID **Content,\r
2084 OUT UINTN *ContentSize\r
2085 );\r
2086\r
b7d320f8 2087/**\r
2088 Verifies the validility of a PE/COFF Authenticode Signature as described in "Windows\r
2089 Authenticode Portable Executable Signature Format".\r
2090\r
16d2c32c 2091 If AuthData is NULL, then return FALSE.\r
2092 If ImageHash is NULL, then return FALSE.\r
532616bb 2093 If this interface is not supported, then return FALSE.\r
b7d320f8 2094\r
2095 @param[in] AuthData Pointer to the Authenticode Signature retrieved from signed\r
2096 PE/COFF image to be verified.\r
2097 @param[in] DataSize Size of the Authenticode Signature in bytes.\r
2098 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which\r
2099 is used for certificate chain verification.\r
2100 @param[in] CertSize Size of the trusted certificate in bytes.\r
2101 @param[in] ImageHash Pointer to the original image file hash value. The procudure\r
2102 for calculating the image hash value is described in Authenticode\r
2103 specification.\r
2104 @param[in] HashSize Size of Image hash value in bytes.\r
2105\r
2106 @retval TRUE The specified Authenticode Signature is valid.\r
2107 @retval FALSE Invalid Authenticode Signature.\r
532616bb 2108 @retval FALSE This interface is not supported.\r
b7d320f8 2109\r
2110**/\r
2111BOOLEAN\r
2112EFIAPI\r
2113AuthenticodeVerify (\r
2114 IN CONST UINT8 *AuthData,\r
2115 IN UINTN DataSize,\r
2116 IN CONST UINT8 *TrustedCert,\r
2117 IN UINTN CertSize,\r
2118 IN CONST UINT8 *ImageHash,\r
2119 IN UINTN HashSize\r
2120 );\r
2121\r
2ac68e8b
QL
2122/**\r
2123 Verifies the validility of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode\r
2124 signature.\r
2125\r
2126 If AuthData is NULL, then return FALSE.\r
12d95665 2127 If this interface is not supported, then return FALSE.\r
2ac68e8b
QL
2128\r
2129 @param[in] AuthData Pointer to the Authenticode Signature retrieved from signed\r
2130 PE/COFF image to be verified.\r
2131 @param[in] DataSize Size of the Authenticode Signature in bytes.\r
2132 @param[in] TsaCert Pointer to a trusted/root TSA certificate encoded in DER, which\r
2133 is used for TSA certificate chain verification.\r
2134 @param[in] CertSize Size of the trusted certificate in bytes.\r
2135 @param[out] SigningTime Return the time of timestamp generation time if the timestamp\r
2136 signature is valid.\r
2137\r
2138 @retval TRUE The specified Authenticode includes a valid RFC3161 Timestamp CounterSignature.\r
2139 @retval FALSE No valid RFC3161 Timestamp CounterSignature in the specified Authenticode data.\r
2140\r
2141**/\r
2142BOOLEAN\r
2143EFIAPI\r
2144ImageTimestampVerify (\r
2145 IN CONST UINT8 *AuthData,\r
2146 IN UINTN DataSize,\r
2147 IN CONST UINT8 *TsaCert,\r
2148 IN UINTN CertSize,\r
2149 OUT EFI_TIME *SigningTime\r
2150 );\r
2151\r
a8c44645 2152//=====================================================================================\r
2153// DH Key Exchange Primitive\r
2154//=====================================================================================\r
2155\r
2156/**\r
2157 Allocates and Initializes one Diffie-Hellman Context for subsequent use.\r
2158\r
2159 @return Pointer to the Diffie-Hellman Context that has been initialized.\r
2160 If the allocations fails, DhNew() returns NULL.\r
532616bb 2161 If the interface is not supported, DhNew() returns NULL.\r
a8c44645 2162\r
2163**/\r
2164VOID *\r
2165EFIAPI\r
2166DhNew (\r
2167 VOID\r
2168 );\r
2169\r
2170/**\r
2171 Release the specified DH context.\r
2172\r
532616bb 2173 If the interface is not supported, then ASSERT().\r
a8c44645 2174\r
2175 @param[in] DhContext Pointer to the DH context to be released.\r
2176\r
2177**/\r
2178VOID\r
2179EFIAPI\r
2180DhFree (\r
2181 IN VOID *DhContext\r
2182 );\r
2183\r
2184/**\r
2185 Generates DH parameter.\r
2186\r
2187 Given generator g, and length of prime number p in bits, this function generates p,\r
2188 and sets DH context according to value of g and p.\r
2ac68e8b 2189\r
a8c44645 2190 Before this function can be invoked, pseudorandom number generator must be correctly\r
2191 initialized by RandomSeed().\r
2192\r
16d2c32c 2193 If DhContext is NULL, then return FALSE.\r
2194 If Prime is NULL, then return FALSE.\r
532616bb 2195 If this interface is not supported, then return FALSE.\r
a8c44645 2196\r
2197 @param[in, out] DhContext Pointer to the DH context.\r
2198 @param[in] Generator Value of generator.\r
2199 @param[in] PrimeLength Length in bits of prime to be generated.\r
2200 @param[out] Prime Pointer to the buffer to receive the generated prime number.\r
2201\r
2202 @retval TRUE DH pamameter generation succeeded.\r
2203 @retval FALSE Value of Generator is not supported.\r
2204 @retval FALSE PRNG fails to generate random prime number with PrimeLength.\r
532616bb 2205 @retval FALSE This interface is not supported.\r
a8c44645 2206\r
2207**/\r
2208BOOLEAN\r
2209EFIAPI\r
2210DhGenerateParameter (\r
2211 IN OUT VOID *DhContext,\r
2212 IN UINTN Generator,\r
2213 IN UINTN PrimeLength,\r
2214 OUT UINT8 *Prime\r
2215 );\r
2216\r
2217/**\r
2218 Sets generator and prime parameters for DH.\r
2219\r
2220 Given generator g, and prime number p, this function and sets DH\r
2221 context accordingly.\r
2222\r
16d2c32c 2223 If DhContext is NULL, then return FALSE.\r
2224 If Prime is NULL, then return FALSE.\r
532616bb 2225 If this interface is not supported, then return FALSE.\r
a8c44645 2226\r
2227 @param[in, out] DhContext Pointer to the DH context.\r
2228 @param[in] Generator Value of generator.\r
2229 @param[in] PrimeLength Length in bits of prime to be generated.\r
2230 @param[in] Prime Pointer to the prime number.\r
2231\r
2232 @retval TRUE DH pamameter setting succeeded.\r
2233 @retval FALSE Value of Generator is not supported.\r
2234 @retval FALSE Value of Generator is not suitable for the Prime.\r
2235 @retval FALSE Value of Prime is not a prime number.\r
2236 @retval FALSE Value of Prime is not a safe prime number.\r
532616bb 2237 @retval FALSE This interface is not supported.\r
a8c44645 2238\r
2239**/\r
2240BOOLEAN\r
2241EFIAPI\r
2242DhSetParameter (\r
2243 IN OUT VOID *DhContext,\r
2244 IN UINTN Generator,\r
2245 IN UINTN PrimeLength,\r
2246 IN CONST UINT8 *Prime\r
97f98500
HT
2247 );\r
2248\r
a8c44645 2249/**\r
2250 Generates DH public key.\r
2251\r
2ac68e8b 2252 This function generates random secret exponent, and computes the public key, which is\r
a8c44645 2253 returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.\r
2254 If the PublicKey buffer is too small to hold the public key, FALSE is returned and\r
2255 PublicKeySize is set to the required buffer size to obtain the public key.\r
2256\r
16d2c32c 2257 If DhContext is NULL, then return FALSE.\r
2258 If PublicKeySize is NULL, then return FALSE.\r
2259 If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.\r
532616bb 2260 If this interface is not supported, then return FALSE.\r
a8c44645 2261\r
2262 @param[in, out] DhContext Pointer to the DH context.\r
2263 @param[out] PublicKey Pointer to the buffer to receive generated public key.\r
2264 @param[in, out] PublicKeySize On input, the size of PublicKey buffer in bytes.\r
2265 On output, the size of data returned in PublicKey buffer in bytes.\r
2266\r
2267 @retval TRUE DH public key generation succeeded.\r
2268 @retval FALSE DH public key generation failed.\r
2269 @retval FALSE PublicKeySize is not large enough.\r
532616bb 2270 @retval FALSE This interface is not supported.\r
a8c44645 2271\r
2272**/\r
2273BOOLEAN\r
2274EFIAPI\r
2275DhGenerateKey (\r
2276 IN OUT VOID *DhContext,\r
2277 OUT UINT8 *PublicKey,\r
2278 IN OUT UINTN *PublicKeySize\r
2279 );\r
2280\r
2281/**\r
2282 Computes exchanged common key.\r
2283\r
2284 Given peer's public key, this function computes the exchanged common key, based on its own\r
dda39f3a 2285 context including value of prime modulus and random secret exponent.\r
a8c44645 2286\r
16d2c32c 2287 If DhContext is NULL, then return FALSE.\r
2288 If PeerPublicKey is NULL, then return FALSE.\r
2289 If KeySize is NULL, then return FALSE.\r
dda39f3a 2290 If Key is NULL, then return FALSE.\r
2291 If KeySize is not large enough, then return FALSE.\r
532616bb 2292 If this interface is not supported, then return FALSE.\r
a8c44645 2293\r
2294 @param[in, out] DhContext Pointer to the DH context.\r
2295 @param[in] PeerPublicKey Pointer to the peer's public key.\r
2296 @param[in] PeerPublicKeySize Size of peer's public key in bytes.\r
2297 @param[out] Key Pointer to the buffer to receive generated key.\r
2298 @param[in, out] KeySize On input, the size of Key buffer in bytes.\r
2299 On output, the size of data returned in Key buffer in bytes.\r
2300\r
2301 @retval TRUE DH exchanged key generation succeeded.\r
2302 @retval FALSE DH exchanged key generation failed.\r
2303 @retval FALSE KeySize is not large enough.\r
532616bb 2304 @retval FALSE This interface is not supported.\r
a8c44645 2305\r
2306**/\r
2307BOOLEAN\r
2308EFIAPI\r
2309DhComputeKey (\r
2310 IN OUT VOID *DhContext,\r
2311 IN CONST UINT8 *PeerPublicKey,\r
2312 IN UINTN PeerPublicKeySize,\r
2313 OUT UINT8 *Key,\r
2314 IN OUT UINTN *KeySize\r
2315 );\r
2316\r
2317//=====================================================================================\r
2318// Pseudo-Random Generation Primitive\r
2319//=====================================================================================\r
2320\r
2321/**\r
2322 Sets up the seed value for the pseudorandom number generator.\r
2323\r
2324 This function sets up the seed value for the pseudorandom number generator.\r
2325 If Seed is not NULL, then the seed passed in is used.\r
2326 If Seed is NULL, then default seed is used.\r
532616bb 2327 If this interface is not supported, then return FALSE.\r
a8c44645 2328\r
2329 @param[in] Seed Pointer to seed value.\r
2330 If NULL, default seed is used.\r
2331 @param[in] SeedSize Size of seed value.\r
2332 If Seed is NULL, this parameter is ignored.\r
2333\r
2334 @retval TRUE Pseudorandom number generator has enough entropy for random generation.\r
2335 @retval FALSE Pseudorandom number generator does not have enough entropy for random generation.\r
532616bb 2336 @retval FALSE This interface is not supported.\r
a8c44645 2337\r
2338**/\r
2339BOOLEAN\r
2340EFIAPI\r
2341RandomSeed (\r
2342 IN CONST UINT8 *Seed OPTIONAL,\r
2343 IN UINTN SeedSize\r
2344 );\r
2345\r
2346/**\r
2347 Generates a pseudorandom byte stream of the specified size.\r
2348\r
16d2c32c 2349 If Output is NULL, then return FALSE.\r
532616bb 2350 If this interface is not supported, then return FALSE.\r
a8c44645 2351\r
2352 @param[out] Output Pointer to buffer to receive random value.\r
2353 @param[in] Size Size of randome bytes to generate.\r
2354\r
2355 @retval TRUE Pseudorandom byte stream generated successfully.\r
2356 @retval FALSE Pseudorandom number generator fails to generate due to lack of entropy.\r
532616bb 2357 @retval FALSE This interface is not supported.\r
a8c44645 2358\r
2359**/\r
2360BOOLEAN\r
2361EFIAPI\r
2362RandomBytes (\r
2363 OUT UINT8 *Output,\r
2364 IN UINTN Size\r
2365 );\r
97f98500 2366\r
afeb55e4 2367#endif // __BASE_CRYPT_LIB_H__\r