]>
git.proxmox.com Git - mirror_edk2.git/blob - CryptoPkg/Include/Library/BaseCryptLib.h
2 Defines base cryptographic library APIs.
3 The Base Cryptographic Library provides implementations of basic cryptography
4 primitives (MD5, SHA-1, SHA-256, RSA, etc) for UEFI security functionality enabling.
6 Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>
7 This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17 #ifndef __BASE_CRYPT_LIB_H__
18 #define __BASE_CRYPT_LIB_H__
21 /// MD5 digest size in bytes
23 #define MD5_DIGEST_SIZE 16
26 /// SHA-1 digest size in bytes.
28 #define SHA1_DIGEST_SIZE 20
31 /// SHA-256 digest size in bytes
33 #define SHA256_DIGEST_SIZE 32
36 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.
39 RsaKeyN
, ///< RSA public Modulus (N)
40 RsaKeyE
, ///< RSA Public exponent (e)
41 RsaKeyD
, ///< RSA Private exponent (d)
42 RsaKeyP
, ///< RSA secret prime factor of Modulus (p)
43 RsaKeyQ
, ///< RSA secret prime factor of Modules (q)
44 RsaKeyDp
, ///< p's CRT exponent (== d mod (p - 1))
45 RsaKeyDq
, ///< q's CRT exponent (== d mod (q - 1))
46 RsaKeyQInv
///< The CRT coefficient (== 1/q mod p)
49 //=====================================================================================
50 // One-Way Cryptographic Hash Primitives
51 //=====================================================================================
54 Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.
56 @return The size, in bytes, of the context buffer required for MD5 hash operations.
67 Initializes user-supplied memory pointed by Md5Context as MD5 hash context for
70 If Md5Context is NULL, then ASSERT().
72 @param[in, out] Md5Context Pointer to MD5 Context being initialized.
74 @retval TRUE MD5 context initialization succeeded.
75 @retval FALSE MD5 context initialization failed.
81 IN OUT VOID
*Md5Context
86 Performs MD5 digest on a data buffer of the specified length. This function can
87 be called multiple times to compute the digest of long or discontinuous data streams.
89 If Md5Context is NULL, then ASSERT().
91 @param[in, out] Md5Context Pointer to the MD5 context.
92 @param[in] Data Pointer to the buffer containing the data to be hashed.
93 @param[in] DataLength Length of Data buffer in bytes.
95 @retval TRUE MD5 data digest succeeded.
96 @retval FALSE Invalid MD5 context. After Md5Final function has been called, the
97 MD5 context cannot be reused.
103 IN OUT VOID
*Md5Context
,
110 Completes MD5 hash computation and retrieves the digest value into the specified
111 memory. After this function has been called, the MD5 context cannot be used again.
113 If Md5Context is NULL, then ASSERT().
114 If HashValue is NULL, then ASSERT().
116 @param[in, out] Md5Context Pointer to the MD5 context
117 @param[out] HashValue Pointer to a buffer that receives the MD5 digest
120 @retval TRUE MD5 digest computation succeeded.
121 @retval FALSE MD5 digest computation failed.
127 IN OUT VOID
*Md5Context
,
133 Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
135 @return The size, in bytes, of the context buffer required for SHA-1 hash operations.
146 Initializes user-supplied memory pointed by Sha1Context as the SHA-1 hash context for
149 If Sha1Context is NULL, then ASSERT().
151 @param[in, out] Sha1Context Pointer to the SHA-1 Context being initialized.
153 @retval TRUE SHA-1 initialization succeeded.
154 @retval FALSE SHA-1 initialization failed.
160 IN OUT VOID
*Sha1Context
165 Performs SHA-1 digest on a data buffer of the specified length. This function can
166 be called multiple times to compute the digest of long or discontinuous data streams.
168 If Sha1Context is NULL, then ASSERT().
170 @param[in, out] Sha1Context Pointer to the SHA-1 context.
171 @param[in] Data Pointer to the buffer containing the data to be hashed.
172 @param[in] DataLength Length of Data buffer in bytes.
174 @retval TRUE SHA-1 data digest succeeded.
175 @retval FALSE Invalid SHA-1 context. After Sha1Final function has been called, the
176 SHA-1 context cannot be reused.
182 IN OUT VOID
*Sha1Context
,
189 Completes SHA-1 hash computation and retrieves the digest value into the specified
190 memory. After this function has been called, the SHA-1 context cannot be used again.
192 If Sha1Context is NULL, then ASSERT().
193 If HashValue is NULL, then ASSERT().
195 @param[in, out] Sha1Context Pointer to the SHA-1 context
196 @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest
199 @retval TRUE SHA-1 digest computation succeeded.
200 @retval FALSE SHA-1 digest computation failed.
206 IN OUT VOID
*Sha1Context
,
212 Retrieves the size, in bytes, of the context buffer required for SHA-256 operations.
214 @return The size, in bytes, of the context buffer required for SHA-256 operations.
219 Sha256GetContextSize (
225 Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for
228 If Sha256Context is NULL, then ASSERT().
230 @param[in, out] Sha256Context Pointer to SHA-256 Context being initialized.
232 @retval TRUE SHA-256 context initialization succeeded.
233 @retval FALSE SHA-256 context initialization failed.
239 IN OUT VOID
*Sha256Context
244 Performs SHA-256 digest on a data buffer of the specified length. This function can
245 be called multiple times to compute the digest of long or discontinuous data streams.
247 If Sha256Context is NULL, then ASSERT().
249 @param[in, out] Sha256Context Pointer to the SHA-256 context.
250 @param[in] Data Pointer to the buffer containing the data to be hashed.
251 @param[in] DataLength Length of Data buffer in bytes.
253 @retval TRUE SHA-256 data digest succeeded.
254 @retval FALSE Invalid SHA-256 context. After Sha256Final function has been called, the
255 SHA-256 context cannot be reused.
261 IN OUT VOID
*Sha256Context
,
268 Completes SHA-256 hash computation and retrieves the digest value into the specified
269 memory. After this function has been called, the SHA-256 context cannot be used again.
271 If Sha256Context is NULL, then ASSERT().
272 If HashValue is NULL, then ASSERT().
274 @param[in, out] Sha256Context Pointer to SHA-256 context
275 @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest
278 @retval TRUE SHA-256 digest computation succeeded.
279 @retval FALSE SHA-256 digest computation failed.
285 IN OUT VOID
*Sha256Context
,
290 //=====================================================================================
291 // MAC (Message Authentication Code) Primitive
292 //=====================================================================================
295 /// No MAC supports for minimum scope required by UEFI
299 //=====================================================================================
300 // Symmetric Cryptography Primitive
301 //=====================================================================================
304 /// No symmetric cryptographic supports for minimum scope required by UEFI
308 //=====================================================================================
309 // Asymmetric Cryptography Primitive
310 //=====================================================================================
313 Allocates and Initializes one RSA Context for subsequent use.
315 @return Pointer to the RSA Context that has been initialized.
316 If the allocations fails, RsaNew() returns NULL.
327 Release the specified RSA Context.
329 @param[in] RsaContext Pointer to the RSA context to be released.
340 Sets the tag-designated RSA key component into the established RSA context from
341 the user-specified nonnegative integer (octet string format represented in RSA
344 If RsaContext is NULL, then ASSERT().
346 @param[in, out] RsaContext Pointer to RSA context being set.
347 @param[in] KeyTag Tag of RSA key component being set.
348 @param[in] BigNumber Pointer to octet integer buffer.
349 @param[in] BnLength Length of big number buffer in bytes.
351 @return TRUE RSA key component was set successfully.
352 @return FALSE Invalid RSA key component tag.
358 IN OUT VOID
*RsaContext
,
359 IN RSA_KEY_TAG KeyTag
,
360 IN CONST UINT8
*BigNumber
,
366 Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
369 If RsaContext is NULL, then ASSERT().
370 If MessageHash is NULL, then ASSERT().
371 If Signature is NULL, then ASSERT().
372 If HashLength is not equal to the size of MD5, SHA-1 or SHA-256 digest, then ASSERT().
374 @param[in] RsaContext Pointer to RSA context for signature verification.
375 @param[in] MessageHash Pointer to octet message hash to be checked.
376 @param[in] HashLength Length of the message hash in bytes.
377 @param[in] Signature Pointer to RSA PKCS1-v1_5 signature to be verified.
378 @param[in] SigLength Length of signature in bytes.
380 @return TRUE Valid signature encoded in PKCS1-v1_5.
381 @return FALSE Invalid signature or invalid RSA context.
388 IN CONST UINT8
*MessageHash
,
396 Verifies the validility of a PKCS#7 signed data as described in "PKCS #7: Cryptographic
397 Message Syntax Standard".
399 If P7Data is NULL, then ASSERT().
401 @param[in] P7Data Pointer to the PKCS#7 message to verify.
402 @param[in] P7Length Length of the PKCS#7 message in bytes.
403 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which
404 is used for certificate chain verification.
405 @param[in] CertLength Length of the trusted certificate in bytes.
406 @param[in] InData Pointer to the content to be verified.
407 @param[in] DataLength Length of InData in bytes.
409 @return TRUE The specified PKCS#7 signed data is valid.
410 @return FALSE Invalid PKCS#7 signed data.
416 IN CONST UINT8
*P7Data
,
418 IN CONST UINT8
*TrustedCert
,
420 IN CONST UINT8
*InData
,
425 #endif // __BASE_CRYPT_LIB_H__