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 (MD5, SHA-1, SHA-256, RSA, etc) for UEFI security functionality enabling.
   5
   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
  11
  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.
  14
  15 **/
  16
  17 #ifndef __BASE_CRYPT_LIB_H__
  18 #define __BASE_CRYPT_LIB_H__
  19
  20 ///
  21 /// MD5 digest size in bytes
  22 ///
  23 #define MD5_DIGEST_SIZE     16
  24
  25 ///
  26 /// SHA-1 digest size in bytes.
  27 ///
  28 #define SHA1_DIGEST_SIZE    20
  29
  30 ///
  31 /// SHA-256 digest size in bytes
  32 ///
  33 #define SHA256_DIGEST_SIZE  32
  34
  35 ///
  36 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.
  37 ///
  38 typedef enum {
  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)
  47 } RSA_KEY_TAG;
  48
  49 //=====================================================================================
  50 //    One-Way Cryptographic Hash Primitives
  51 //=====================================================================================
  52
  53 /**
  54   Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.
  55
  56   @return  The size, in bytes, of the context buffer required for MD5 hash operations.
  57
  58 **/
  59 UINTN
  60 EFIAPI
  61 Md5GetContextSize (
  62   VOID
  63   );
  64
  65
  66 /**
  67   Initializes user-supplied memory pointed by Md5Context as MD5 hash context for
  68   subsequent use.
  69
  70   If Md5Context is NULL, then ASSERT().
  71
  72   @param[in, out]  Md5Context  Pointer to MD5 Context being initialized.
  73
  74   @retval TRUE   MD5 context initialization succeeded.
  75   @retval FALSE  MD5 context initialization failed.
  76
  77 **/
  78 BOOLEAN
  79 EFIAPI
  80 Md5Init (
  81   IN OUT  VOID  *Md5Context
  82   );
  83
  84
  85 /**
  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.
  88
  89   If Md5Context is NULL, then ASSERT().
  90
  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.
  94
  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.
  98
  99 **/
 100 BOOLEAN
 101 EFIAPI
 102 Md5Update (
 103   IN OUT  VOID        *Md5Context,
 104   IN      CONST VOID  *Data,
 105   IN      UINTN       DataLength
 106   );
 107
 108
 109 /**
 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.
 112
 113   If Md5Context is NULL, then ASSERT().
 114   If HashValue is NULL, then ASSERT().
 115
 116   @param[in, out]  Md5Context  Pointer to the MD5 context
 117   @param[out]      HashValue   Pointer to a buffer that receives the MD5 digest
 118                                value (16 bytes).
 119
 120   @retval TRUE   MD5 digest computation succeeded.
 121   @retval FALSE  MD5 digest computation failed.
 122
 123 **/
 124 BOOLEAN
 125 EFIAPI
 126 Md5Final (
 127   IN OUT  VOID   *Md5Context,
 128   OUT     UINT8  *HashValue
 129   );
 130
 131
 132 /**
 133   Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
 134
 135   @return  The size, in bytes, of the context buffer required for SHA-1 hash operations.
 136
 137 **/
 138 UINTN
 139 EFIAPI
 140 Sha1GetContextSize (
 141   VOID
 142   );
 143
 144
 145 /**
 146   Initializes user-supplied memory pointed by Sha1Context as the SHA-1 hash context for
 147   subsequent use.
 148
 149   If Sha1Context is NULL, then ASSERT().
 150
 151   @param[in, out]  Sha1Context  Pointer to the SHA-1 Context being initialized.
 152
 153   @retval TRUE   SHA-1 initialization succeeded.
 154   @retval FALSE  SHA-1 initialization failed.
 155
 156 **/
 157 BOOLEAN
 158 EFIAPI
 159 Sha1Init (
 160   IN OUT  VOID  *Sha1Context
 161   );
 162
 163
 164 /**
 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.
 167
 168   If Sha1Context is NULL, then ASSERT().
 169
 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.
 173
 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.
 177
 178 **/
 179 BOOLEAN
 180 EFIAPI
 181 Sha1Update (
 182   IN OUT  VOID        *Sha1Context,
 183   IN      CONST VOID  *Data,
 184   IN      UINTN       DataLength
 185   );
 186
 187
 188 /**
 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.
 191
 192   If Sha1Context is NULL, then ASSERT().
 193   If HashValue is NULL, then ASSERT().
 194
 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
 197                                 value (20 bytes).
 198
 199   @retval TRUE   SHA-1 digest computation succeeded.
 200   @retval FALSE  SHA-1 digest computation failed.
 201
 202 **/
 203 BOOLEAN
 204 EFIAPI
 205 Sha1Final (
 206   IN OUT  VOID   *Sha1Context,
 207   OUT     UINT8  *HashValue
 208   );
 209
 210
 211 /**
 212   Retrieves the size, in bytes, of the context buffer required for SHA-256 operations.
 213
 214   @return  The size, in bytes, of the context buffer required for SHA-256 operations.
 215
 216 **/
 217 UINTN
 218 EFIAPI
 219 Sha256GetContextSize (
 220   VOID
 221   );
 222
 223
 224 /**
 225   Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for
 226   subsequent use.
 227
 228   If Sha256Context is NULL, then ASSERT().
 229
 230   @param[in, out]  Sha256Context  Pointer to SHA-256 Context being initialized.
 231
 232   @retval TRUE   SHA-256 context initialization succeeded.
 233   @retval FALSE  SHA-256 context initialization failed.
 234
 235 **/
 236 BOOLEAN
 237 EFIAPI
 238 Sha256Init (
 239   IN OUT  VOID  *Sha256Context
 240   );
 241
 242
 243 /**
 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.
 246
 247   If Sha256Context is NULL, then ASSERT().
 248
 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.
 252
 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.
 256
 257 **/
 258 BOOLEAN
 259 EFIAPI
 260 Sha256Update (
 261   IN OUT  VOID        *Sha256Context,
 262   IN      CONST VOID  *Data,
 263   IN      UINTN       DataLength
 264   );
 265
 266
 267 /**
 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.
 270
 271   If Sha256Context is NULL, then ASSERT().
 272   If HashValue is NULL, then ASSERT().
 273
 274   @param[in, out]  Sha256Context  Pointer to SHA-256 context
 275   @param[out]      HashValue      Pointer to a buffer that receives the SHA-256 digest
 276                                   value (32 bytes).
 277
 278   @retval TRUE   SHA-256 digest computation succeeded.
 279   @retval FALSE  SHA-256 digest computation failed.
 280
 281 **/
 282 BOOLEAN
 283 EFIAPI
 284 Sha256Final (
 285   IN OUT  VOID   *Sha256Context,
 286   OUT     UINT8  *HashValue
 287   );
 288
 289
 290 //=====================================================================================
 291 //    MAC (Message Authentication Code) Primitive
 292 //=====================================================================================
 293
 294 ///
 295 /// No MAC supports for minimum scope required by UEFI
 296 ///
 297
 298
 299 //=====================================================================================
 300 //    Symmetric Cryptography Primitive
 301 //=====================================================================================
 302
 303 ///
 304 /// No symmetric cryptographic supports for minimum scope required by UEFI
 305 ///
 306
 307
 308 //=====================================================================================
 309 //    Asymmetric Cryptography Primitive
 310 //=====================================================================================
 311
 312 /**
 313   Allocates and Initializes one RSA Context for subsequent use.
 314
 315   @return  Pointer to the RSA Context that has been initialized.
 316            If the allocations fails, RsaNew() returns NULL.
 317
 318 **/
 319 VOID *
 320 EFIAPI
 321 RsaNew (
 322   VOID
 323   );
 324
 325
 326 /**
 327   Release the specified RSA Context.
 328
 329   @param[in]  RsaContext  Pointer to the RSA context to be released.
 330
 331 **/
 332 VOID
 333 EFIAPI
 334 RsaFree (
 335   IN  VOID  *RsaContext
 336   );
 337
 338
 339 /**
 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
 342   PKCS#1).
 343
 344   If RsaContext is NULL, then ASSERT().
 345
 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.
 350
 351   @return  TRUE   RSA key component was set successfully.
 352   @return  FALSE  Invalid RSA key component tag.
 353
 354 **/
 355 BOOLEAN
 356 EFIAPI
 357 RsaSetKey (
 358   IN OUT VOID         *RsaContext,
 359   IN     RSA_KEY_TAG  KeyTag,
 360   IN     CONST UINT8  *BigNumber,
 361   IN     UINTN        BnLength
 362   );
 363
 364
 365 /**
 366   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
 367   RSA PKCS#1.
 368
 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().
 373
 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.
 379
 380   @return  TRUE   Valid signature encoded in PKCS1-v1_5.
 381   @return  FALSE  Invalid signature or invalid RSA context.
 382
 383 **/
 384 BOOLEAN
 385 EFIAPI
 386 RsaPkcs1Verify (
 387   IN  VOID         *RsaContext,
 388   IN  CONST UINT8  *MessageHash,
 389   IN  UINTN        HashLength,
 390   IN  UINT8        *Signature,
 391   IN  UINTN        SigLength
 392   );
 393
 394
 395 /**
 396   Verifies the validility of a PKCS#7 signed data as described in "PKCS #7: Cryptographic
 397   Message Syntax Standard".
 398
 399   If P7Data is NULL, then ASSERT().
 400
 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.
 408
 409   @return  TRUE  The specified PKCS#7 signed data is valid.
 410   @return  FALSE Invalid PKCS#7 signed data.
 411
 412 **/
 413 BOOLEAN
 414 EFIAPI
 415 Pkcs7Verify (
 416   IN  CONST UINT8  *P7Data,
 417   IN  UINTN        P7Length,
 418   IN  CONST UINT8  *TrustedCert,
 419   IN  UINTN        CertLength,
 420   IN  CONST UINT8  *InData,
 421   IN  UINTN        DataLength
 422   );
 423
 424
 425 #endif // __BASE_CRYPT_LIB_H__