556026e1be097ebaabd4b98014465fe79f96a99b
[mirror_edk2.git] / CryptoPkg / Include / Library / BaseCryptLib.h
1 /** @file\r
2   Defines base cryptographic library APIs.\r
3   The Base Cryptographic Library provides implementations of basic cryptography\r
4   primitives (MD5, SHA-1, SHA-256, RSA, etc) for UEFI security functionality enabling.\r
5 \r
6 Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>\r
7 This program and the accompanying materials\r
8 are licensed and made available under the terms and conditions of the BSD License\r
9 which accompanies this distribution.  The full text of the license may be found at\r
10 http://opensource.org/licenses/bsd-license.php\r
11 \r
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
14 \r
15 **/\r
16 \r
17 #ifndef __BASE_CRYPT_LIB_H__\r
18 #define __BASE_CRYPT_LIB_H__\r
19 \r
20 ///\r
21 /// MD5 digest size in bytes\r
22 ///\r
23 #define MD5_DIGEST_SIZE     16\r
24 \r
25 ///\r
26 /// SHA-1 digest size in bytes.\r
27 ///\r
28 #define SHA1_DIGEST_SIZE    20\r
29 \r
30 ///\r
31 /// SHA-256 digest size in bytes\r
32 ///\r
33 #define SHA256_DIGEST_SIZE  32\r
34 \r
35 ///\r
36 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.\r
37 ///\r
38 typedef enum {\r
39   RsaKeyN,      ///< RSA public Modulus (N)\r
40   RsaKeyE,      ///< RSA Public exponent (e)\r
41   RsaKeyD,      ///< RSA Private exponent (d)\r
42   RsaKeyP,      ///< RSA secret prime factor of Modulus (p)\r
43   RsaKeyQ,      ///< RSA secret prime factor of Modules (q)\r
44   RsaKeyDp,     ///< p's CRT exponent (== d mod (p - 1))\r
45   RsaKeyDq,     ///< q's CRT exponent (== d mod (q - 1))\r
46   RsaKeyQInv    ///< The CRT coefficient (== 1/q mod p)\r
47 } RSA_KEY_TAG;\r
48 \r
49 //=====================================================================================\r
50 //    One-Way Cryptographic Hash Primitives\r
51 //=====================================================================================\r
52 \r
53 /**\r
54   Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.\r
55 \r
56   @return  The size, in bytes, of the context buffer required for MD5 hash operations.\r
57 \r
58 **/\r
59 UINTN\r
60 EFIAPI\r
61 Md5GetContextSize (\r
62   VOID\r
63   );\r
64 \r
65 \r
66 /**\r
67   Initializes user-supplied memory pointed by Md5Context as MD5 hash context for\r
68   subsequent use.\r
69 \r
70   If Md5Context is NULL, then ASSERT().\r
71 \r
72   @param[in, out]  Md5Context  Pointer to MD5 Context being initialized.\r
73 \r
74   @retval TRUE   MD5 context initialization succeeded.\r
75   @retval FALSE  MD5 context initialization failed.\r
76 \r
77 **/\r
78 BOOLEAN\r
79 EFIAPI\r
80 Md5Init (\r
81   IN OUT  VOID  *Md5Context\r
82   );\r
83 \r
84 \r
85 /**\r
86   Performs MD5 digest on a data buffer of the specified length. This function can\r
87   be called multiple times to compute the digest of long or discontinuous data streams.\r
88 \r
89   If Md5Context is NULL, then ASSERT().\r
90 \r
91   @param[in, out]  Md5Context  Pointer to the MD5 context.\r
92   @param[in]       Data        Pointer to the buffer containing the data to be hashed.\r
93   @param[in]       DataLength  Length of Data buffer in bytes.\r
94 \r
95   @retval TRUE   MD5 data digest succeeded.\r
96   @retval FALSE  Invalid MD5 context. After Md5Final function has been called, the\r
97                  MD5 context cannot be reused.\r
98 \r
99 **/\r
100 BOOLEAN\r
101 EFIAPI\r
102 Md5Update (\r
103   IN OUT  VOID        *Md5Context,\r
104   IN      CONST VOID  *Data,\r
105   IN      UINTN       DataLength\r
106   );\r
107 \r
108 \r
109 /**\r
110   Completes MD5 hash computation and retrieves the digest value into the specified\r
111   memory. After this function has been called, the MD5 context cannot be used again.\r
112 \r
113   If Md5Context is NULL, then ASSERT().\r
114   If HashValue is NULL, then ASSERT().\r
115 \r
116   @param[in, out]  Md5Context  Pointer to the MD5 context\r
117   @param[out]      HashValue   Pointer to a buffer that receives the MD5 digest\r
118                                value (16 bytes).\r
119 \r
120   @retval TRUE   MD5 digest computation succeeded.\r
121   @retval FALSE  MD5 digest computation failed.\r
122 \r
123 **/\r
124 BOOLEAN\r
125 EFIAPI\r
126 Md5Final (\r
127   IN OUT  VOID   *Md5Context,\r
128   OUT     UINT8  *HashValue\r
129   );\r
130 \r
131 \r
132 /**\r
133   Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.\r
134 \r
135   @return  The size, in bytes, of the context buffer required for SHA-1 hash operations.\r
136 \r
137 **/\r
138 UINTN\r
139 EFIAPI\r
140 Sha1GetContextSize (\r
141   VOID\r
142   );\r
143 \r
144 \r
145 /**\r
146   Initializes user-supplied memory pointed by Sha1Context as the SHA-1 hash context for\r
147   subsequent use.\r
148 \r
149   If Sha1Context is NULL, then ASSERT().\r
150 \r
151   @param[in, out]  Sha1Context  Pointer to the SHA-1 Context being initialized.\r
152 \r
153   @retval TRUE   SHA-1 initialization succeeded.\r
154   @retval FALSE  SHA-1 initialization failed.\r
155 \r
156 **/\r
157 BOOLEAN\r
158 EFIAPI\r
159 Sha1Init (\r
160   IN OUT  VOID  *Sha1Context\r
161   );\r
162 \r
163 \r
164 /**\r
165   Performs SHA-1 digest on a data buffer of the specified length. This function can\r
166   be called multiple times to compute the digest of long or discontinuous data streams.\r
167 \r
168   If Sha1Context is NULL, then ASSERT().\r
169 \r
170   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.\r
171   @param[in]       Data         Pointer to the buffer containing the data to be hashed.\r
172   @param[in]       DataLength   Length of Data buffer in bytes.\r
173 \r
174   @retval TRUE   SHA-1 data digest succeeded.\r
175   @retval FALSE  Invalid SHA-1 context. After Sha1Final function has been called, the\r
176                  SHA-1 context cannot be reused.\r
177 \r
178 **/\r
179 BOOLEAN\r
180 EFIAPI\r
181 Sha1Update (\r
182   IN OUT  VOID        *Sha1Context,\r
183   IN      CONST VOID  *Data,\r
184   IN      UINTN       DataLength\r
185   );\r
186 \r
187 \r
188 /**\r
189   Completes SHA-1 hash computation and retrieves the digest value into the specified\r
190   memory. After this function has been called, the SHA-1 context cannot be used again.\r
191 \r
192   If Sha1Context is NULL, then ASSERT().\r
193   If HashValue is NULL, then ASSERT().\r
194 \r
195   @param[in, out]  Sha1Context  Pointer to the SHA-1 context\r
196   @param[out]      HashValue    Pointer to a buffer that receives the SHA-1 digest\r
197                                 value (20 bytes).\r
198 \r
199   @retval TRUE   SHA-1 digest computation succeeded.\r
200   @retval FALSE  SHA-1 digest computation failed.\r
201 \r
202 **/\r
203 BOOLEAN\r
204 EFIAPI\r
205 Sha1Final (\r
206   IN OUT  VOID   *Sha1Context,\r
207   OUT     UINT8  *HashValue\r
208   );\r
209 \r
210 \r
211 /**\r
212   Retrieves the size, in bytes, of the context buffer required for SHA-256 operations.\r
213 \r
214   @return  The size, in bytes, of the context buffer required for SHA-256 operations.\r
215 \r
216 **/\r
217 UINTN\r
218 EFIAPI\r
219 Sha256GetContextSize (\r
220   VOID\r
221   );\r
222 \r
223 \r
224 /**\r
225   Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for\r
226   subsequent use.\r
227 \r
228   If Sha256Context is NULL, then ASSERT().\r
229 \r
230   @param[in, out]  Sha256Context  Pointer to SHA-256 Context being initialized.\r
231 \r
232   @retval TRUE   SHA-256 context initialization succeeded.\r
233   @retval FALSE  SHA-256 context initialization failed.\r
234 \r
235 **/\r
236 BOOLEAN\r
237 EFIAPI\r
238 Sha256Init (\r
239   IN OUT  VOID  *Sha256Context\r
240   );\r
241 \r
242 \r
243 /**\r
244   Performs SHA-256 digest on a data buffer of the specified length. This function can\r
245   be called multiple times to compute the digest of long or discontinuous data streams.\r
246 \r
247   If Sha256Context is NULL, then ASSERT().\r
248 \r
249   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.\r
250   @param[in]       Data           Pointer to the buffer containing the data to be hashed.\r
251   @param[in]       DataLength     Length of Data buffer in bytes.\r
252 \r
253   @retval TRUE   SHA-256 data digest succeeded.\r
254   @retval FALSE  Invalid SHA-256 context. After Sha256Final function has been called, the\r
255                  SHA-256 context cannot be reused.\r
256 \r
257 **/\r
258 BOOLEAN\r
259 EFIAPI\r
260 Sha256Update (\r
261   IN OUT  VOID        *Sha256Context,\r
262   IN      CONST VOID  *Data,\r
263   IN      UINTN       DataLength\r
264   );\r
265 \r
266 \r
267 /**\r
268   Completes SHA-256 hash computation and retrieves the digest value into the specified\r
269   memory. After this function has been called, the SHA-256 context cannot be used again.\r
270 \r
271   If Sha256Context is NULL, then ASSERT().\r
272   If HashValue is NULL, then ASSERT().\r
273 \r
274   @param[in, out]  Sha256Context  Pointer to SHA-256 context\r
275   @param[out]      HashValue      Pointer to a buffer that receives the SHA-256 digest\r
276                                   value (32 bytes).\r
277 \r
278   @retval TRUE   SHA-256 digest computation succeeded.\r
279   @retval FALSE  SHA-256 digest computation failed.\r
280 \r
281 **/\r
282 BOOLEAN\r
283 EFIAPI\r
284 Sha256Final (\r
285   IN OUT  VOID   *Sha256Context,\r
286   OUT     UINT8  *HashValue\r
287   );\r
288 \r
289 \r
290 //=====================================================================================\r
291 //    MAC (Message Authentication Code) Primitive\r
292 //=====================================================================================\r
293 \r
294 ///\r
295 /// No MAC supports for minimum scope required by UEFI\r
296 ///\r
297 \r
298 \r
299 //=====================================================================================\r
300 //    Symmetric Cryptography Primitive\r
301 //=====================================================================================\r
302 \r
303 ///\r
304 /// No symmetric cryptographic supports for minimum scope required by UEFI\r
305 ///\r
306 \r
307 \r
308 //=====================================================================================\r
309 //    Asymmetric Cryptography Primitive\r
310 //=====================================================================================\r
311 \r
312 /**\r
313   Allocates and Initializes one RSA Context for subsequent use.\r
314 \r
315   @return  Pointer to the RSA Context that has been initialized.\r
316            If the allocations fails, RsaNew() returns NULL.\r
317 \r
318 **/\r
319 VOID *\r
320 EFIAPI\r
321 RsaNew (\r
322   VOID\r
323   );\r
324 \r
325 \r
326 /**\r
327   Release the specified RSA Context.\r
328 \r
329   @param[in]  RsaContext  Pointer to the RSA context to be released.\r
330 \r
331 **/\r
332 VOID\r
333 EFIAPI\r
334 RsaFree (\r
335   IN  VOID  *RsaContext\r
336   );\r
337 \r
338 \r
339 /**\r
340   Sets the tag-designated RSA key component into the established RSA context from\r
341   the user-specified nonnegative integer (octet string format represented in RSA\r
342   PKCS#1).\r
343 \r
344   If RsaContext is NULL, then ASSERT().\r
345 \r
346   @param[in, out]  RsaContext  Pointer to RSA context being set.\r
347   @param[in]       KeyTag      Tag of RSA key component being set.\r
348   @param[in]       BigNumber   Pointer to octet integer buffer.\r
349   @param[in]       BnLength    Length of big number buffer in bytes.\r
350 \r
351   @return  TRUE   RSA key component was set successfully.\r
352   @return  FALSE  Invalid RSA key component tag.\r
353 \r
354 **/\r
355 BOOLEAN\r
356 EFIAPI\r
357 RsaSetKey (\r
358   IN OUT VOID         *RsaContext,\r
359   IN     RSA_KEY_TAG  KeyTag,\r
360   IN     CONST UINT8  *BigNumber,\r
361   IN     UINTN        BnLength\r
362   );\r
363 \r
364 \r
365 /**\r
366   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in\r
367   RSA PKCS#1.\r
368 \r
369   If RsaContext is NULL, then ASSERT().\r
370   If MessageHash is NULL, then ASSERT().\r
371   If Signature is NULL, then ASSERT().\r
372   If HashLength is not equal to the size of MD5, SHA-1 or SHA-256 digest, then ASSERT().\r
373 \r
374   @param[in]  RsaContext   Pointer to RSA context for signature verification.\r
375   @param[in]  MessageHash  Pointer to octet message hash to be checked.\r
376   @param[in]  HashLength   Length of the message hash in bytes.\r
377   @param[in]  Signature    Pointer to RSA PKCS1-v1_5 signature to be verified.\r
378   @param[in]  SigLength    Length of signature in bytes.\r
379 \r
380   @return  TRUE   Valid signature encoded in PKCS1-v1_5.\r
381   @return  FALSE  Invalid signature or invalid RSA context.\r
382 \r
383 **/\r
384 BOOLEAN\r
385 EFIAPI\r
386 RsaPkcs1Verify (\r
387   IN  VOID         *RsaContext,\r
388   IN  CONST UINT8  *MessageHash,\r
389   IN  UINTN        HashLength,\r
390   IN  UINT8        *Signature,\r
391   IN  UINTN        SigLength\r
392   );\r
393 \r
394 \r
395 /**\r
396   Verifies the validility of a PKCS#7 signed data as described in "PKCS #7: Cryptographic\r
397   Message Syntax Standard".\r
398 \r
399   If P7Data is NULL, then ASSERT().\r
400 \r
401   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.\r
402   @param[in]  P7Length     Length of the PKCS#7 message in bytes.\r
403   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which\r
404                            is used for certificate chain verification.\r
405   @param[in]  CertLength   Length of the trusted certificate in bytes.\r
406   @param[in]  InData       Pointer to the content to be verified.\r
407   @param[in]  DataLength   Length of InData in bytes.\r
408 \r
409   @return  TRUE  The specified PKCS#7 signed data is valid.\r
410   @return  FALSE Invalid PKCS#7 signed data.\r
411 \r
412 **/\r
413 BOOLEAN\r
414 EFIAPI\r
415 Pkcs7Verify (\r
416   IN  CONST UINT8  *P7Data,\r
417   IN  UINTN        P7Length,\r
418   IN  CONST UINT8  *TrustedCert,\r
419   IN  UINTN        CertLength,\r
420   IN  CONST UINT8  *InData,\r
421   IN  UINTN        DataLength\r
422   );\r
423 \r
424 \r
425 #endif // __BASE_CRYPT_LIB_H__\r