SecurityPkg/Include/Library/HashLib.h

   1 /** @file
   2   This library abstract TPM2 hash calculation.
   3   The platform can choose multiply hash, while caller just need invoke these API.
   4   Then all hash value will be returned and/or extended.
   5
   6 Copyright (c) 2013 - 2016, 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 _HASH_LIB_H_
  18 #define _HASH_LIB_H_
  19
  20 #include <Uefi.h>
  21 #include <Protocol/Hash.h>
  22
  23 typedef UINTN  HASH_HANDLE;
  24
  25 /**
  26   Start hash sequence.
  27
  28   @param HashHandle Hash handle.
  29
  30   @retval EFI_SUCCESS          Hash sequence start and HandleHandle returned.
  31   @retval EFI_OUT_OF_RESOURCES No enough resource to start hash.
  32 **/
  33 EFI_STATUS
  34 EFIAPI
  35 HashStart (
  36   OUT HASH_HANDLE    *HashHandle
  37   );
  38
  39 /**
  40   Update hash sequence data.
  41
  42   @param HashHandle    Hash handle.
  43   @param DataToHash    Data to be hashed.
  44   @param DataToHashLen Data size.
  45
  46   @retval EFI_SUCCESS     Hash sequence updated.
  47 **/
  48 EFI_STATUS
  49 EFIAPI
  50 HashUpdate (
  51   IN HASH_HANDLE    HashHandle,
  52   IN VOID           *DataToHash,
  53   IN UINTN          DataToHashLen
  54   );
  55
  56 /**
  57   Hash sequence complete and extend to PCR.
  58
  59   @param HashHandle    Hash handle.
  60   @param PcrIndex      PCR to be extended.
  61   @param DataToHash    Data to be hashed.
  62   @param DataToHashLen Data size.
  63   @param DigestList    Digest list.
  64
  65   @retval EFI_SUCCESS     Hash sequence complete and DigestList is returned.
  66 **/
  67 EFI_STATUS
  68 EFIAPI
  69 HashCompleteAndExtend (
  70   IN HASH_HANDLE         HashHandle,
  71   IN TPMI_DH_PCR         PcrIndex,
  72   IN VOID                *DataToHash,
  73   IN UINTN               DataToHashLen,
  74   OUT TPML_DIGEST_VALUES *DigestList
  75   );
  76
  77 /**
  78   Hash data and extend to PCR.
  79
  80   @param PcrIndex      PCR to be extended.
  81   @param DataToHash    Data to be hashed.
  82   @param DataToHashLen Data size.
  83   @param DigestList    Digest list.
  84
  85   @retval EFI_SUCCESS     Hash data and DigestList is returned.
  86 **/
  87 EFI_STATUS
  88 EFIAPI
  89 HashAndExtend (
  90   IN TPMI_DH_PCR                    PcrIndex,
  91   IN VOID                           *DataToHash,
  92   IN UINTN                          DataToHashLen,
  93   OUT TPML_DIGEST_VALUES            *DigestList
  94   );
  95
  96 /**
  97   Start hash sequence.
  98
  99   @param HashHandle Hash handle.
 100
 101   @retval EFI_SUCCESS          Hash sequence start and HandleHandle returned.
 102   @retval EFI_OUT_OF_RESOURCES No enough resource to start hash.
 103 **/
 104 typedef
 105 EFI_STATUS
 106 (EFIAPI *HASH_INIT) (
 107   OUT HASH_HANDLE    *HashHandle
 108   );
 109
 110 /**
 111   Update hash sequence data.
 112
 113   @param HashHandle    Hash handle.
 114   @param DataToHash    Data to be hashed.
 115   @param DataToHashLen Data size.
 116
 117   @retval EFI_SUCCESS     Hash sequence updated.
 118 **/
 119 typedef
 120 EFI_STATUS
 121 (EFIAPI *HASH_UPDATE) (
 122   IN HASH_HANDLE    HashHandle,
 123   IN VOID           *DataToHash,
 124   IN UINTN          DataToHashLen
 125   );
 126
 127 /**
 128   Complete hash sequence complete.
 129
 130   @param HashHandle    Hash handle.
 131   @param DigestList    Digest list.
 132
 133   @retval EFI_SUCCESS     Hash sequence complete and DigestList is returned.
 134 **/
 135 typedef
 136 EFI_STATUS
 137 (EFIAPI *HASH_FINAL) (
 138   IN HASH_HANDLE         HashHandle,
 139   OUT TPML_DIGEST_VALUES *DigestList
 140   );
 141
 142 #define HASH_ALGORITHM_SHA1_GUID    EFI_HASH_ALGORITHM_SHA1_GUID
 143 #define HASH_ALGORITHM_SHA256_GUID  EFI_HASH_ALGORITHM_SHA256_GUID
 144 #define HASH_ALGORITHM_SHA384_GUID  EFI_HASH_ALGORITHM_SHA384_GUID
 145 #define HASH_ALGORITHM_SHA512_GUID  EFI_HASH_ALGORITHM_SHA512_GUID
 146
 147 typedef struct {
 148   EFI_GUID                           HashGuid;
 149   HASH_INIT                          HashInit;
 150   HASH_UPDATE                        HashUpdate;
 151   HASH_FINAL                         HashFinal;
 152 } HASH_INTERFACE;
 153
 154 /**
 155   This service register Hash.
 156
 157   @param HashInterface  Hash interface
 158
 159   @retval EFI_SUCCESS          This hash interface is registered successfully.
 160   @retval EFI_UNSUPPORTED      System does not support register this interface.
 161   @retval EFI_ALREADY_STARTED  System already register this interface.
 162 **/
 163 EFI_STATUS
 164 EFIAPI
 165 RegisterHashInterfaceLib (
 166   IN HASH_INTERFACE   *HashInterface
 167   );
 168
 169 #endif