projects / mirror_edk2.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Add CryptoPkg (from UDK2010.UP3)
[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
4 primitives (MD5, SHA-1, SHA-256, RSA, etc) for UEFI security functionality enabling.\r
5\r
6Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>\r
7This program and the accompanying materials\r
8are licensed and made available under the terms and conditions of the BSD License\r
9which accompanies this distribution. The full text of the license may be found at\r
10http://opensource.org/licenses/bsd-license.php\r
11\r
12THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
13WITHOUT 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
38typedef 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
59UINTN\r
60EFIAPI\r
61Md5GetContextSize (\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
78BOOLEAN\r
79EFIAPI\r
80Md5Init (\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
100BOOLEAN\r
101EFIAPI\r
102Md5Update (\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
124BOOLEAN\r
125EFIAPI\r
126Md5Final (\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
138UINTN\r
139EFIAPI\r
140Sha1GetContextSize (\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
157BOOLEAN\r
158EFIAPI\r
159Sha1Init (\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
179BOOLEAN\r
180EFIAPI\r
181Sha1Update (\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
203BOOLEAN\r
204EFIAPI\r
205Sha1Final (\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
217UINTN\r
218EFIAPI\r
219Sha256GetContextSize (\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
236BOOLEAN\r
237EFIAPI\r
238Sha256Init (\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
258BOOLEAN\r
259EFIAPI\r
260Sha256Update (\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
282BOOLEAN\r
283EFIAPI\r
284Sha256Final (\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
319VOID *\r
320EFIAPI\r
321RsaNew (\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
332VOID\r
333EFIAPI\r
334RsaFree (\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
355BOOLEAN\r
356EFIAPI\r
357RsaSetKey (\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
384BOOLEAN\r
385EFIAPI\r
386RsaPkcs1Verify (\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
413BOOLEAN\r
414EFIAPI\r
415Pkcs7Verify (\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
EFI Development Kit II mirror for PVE