]> git.proxmox.com Git - mirror_edk2.git/blob - CryptoPkg/Include/Library/BaseCryptLib.h
projects / mirror_edk2.git / blob
? search:


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