AuthServiceInternal.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369
  1. /** @file
  2. The internal header file includes the common header files, defines
  3. internal structure and functions used by AuthService module.
  4. Caution: This module requires additional review when modified.
  5. This driver will have external input - variable data. It may be input in SMM mode.
  6. This external input must be validated carefully to avoid security issue like
  7. buffer overflow, integer overflow.
  8. Variable attribute should also be checked to avoid authentication bypass.
  9. The whole SMM authentication variable design relies on the integrity of flash part and SMM.
  10. which is assumed to be protected by platform. All variable code and metadata in flash/SMM Memory
  11. may not be modified without authorization. If platform fails to protect these resources,
  12. the authentication service provided in this driver will be broken, and the behavior is undefined.
  13. Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
  14. SPDX-License-Identifier: BSD-2-Clause-Patent
  15. **/
  16. #ifndef _AUTHSERVICE_INTERNAL_H_
  17. #define _AUTHSERVICE_INTERNAL_H_
  18. #include <Library/AuthVariableLib.h>
  19. #include <Library/BaseLib.h>
  20. #include <Library/BaseMemoryLib.h>
  21. #include <Library/DebugLib.h>
  22. #include <Library/MemoryAllocationLib.h>
  23. #include <Library/BaseCryptLib.h>
  24. #include <Library/PlatformSecureLib.h>
  25. #include <Guid/AuthenticatedVariableFormat.h>
  26. #include <Guid/ImageAuthentication.h>
  27. #define TWO_BYTE_ENCODE 0x82
  28. ///
  29. /// Struct to record signature requirement defined by UEFI spec.
  30. /// For SigHeaderSize and SigDataSize, ((UINT32) ~0) means NO exact length requirement for this field.
  31. ///
  32. typedef struct {
  33. EFI_GUID SigType;
  34. // Expected SignatureHeader size in Bytes.
  35. UINT32 SigHeaderSize;
  36. // Expected SignatureData size in Bytes.
  37. UINT32 SigDataSize;
  38. } EFI_SIGNATURE_ITEM;
  39. typedef enum {
  40. AuthVarTypePk,
  41. AuthVarTypeKek,
  42. AuthVarTypePriv,
  43. AuthVarTypePayload
  44. } AUTHVAR_TYPE;
  45. ///
  46. /// "certdb" variable stores the signer's certificates for non PK/KEK/DB/DBX
  47. /// variables with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS|EFI_VARIABLE_NON_VOLATILE set.
  48. /// "certdbv" variable stores the signer's certificates for non PK/KEK/DB/DBX
  49. /// variables with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
  50. ///
  51. /// GUID: gEfiCertDbGuid
  52. ///
  53. /// We need maintain atomicity.
  54. ///
  55. /// Format:
  56. /// +----------------------------+
  57. /// | UINT32 | <-- CertDbListSize, including this UINT32
  58. /// +----------------------------+
  59. /// | AUTH_CERT_DB_DATA | <-- First CERT
  60. /// +----------------------------+
  61. /// | ........ |
  62. /// +----------------------------+
  63. /// | AUTH_CERT_DB_DATA | <-- Last CERT
  64. /// +----------------------------+
  65. ///
  66. #define EFI_CERT_DB_NAME L"certdb"
  67. #define EFI_CERT_DB_VOLATILE_NAME L"certdbv"
  68. #pragma pack(1)
  69. typedef struct {
  70. EFI_GUID VendorGuid;
  71. UINT32 CertNodeSize;
  72. UINT32 NameSize;
  73. UINT32 CertDataSize;
  74. /// CHAR16 VariableName[NameSize];
  75. /// UINT8 CertData[CertDataSize];
  76. } AUTH_CERT_DB_DATA;
  77. #pragma pack()
  78. extern UINT8 *mCertDbStore;
  79. extern UINT32 mMaxCertDbSize;
  80. extern UINT32 mPlatformMode;
  81. extern UINT8 mVendorKeyState;
  82. extern VOID *mHashCtx;
  83. extern AUTH_VAR_LIB_CONTEXT_IN *mAuthVarLibContextIn;
  84. /**
  85. Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
  86. Caution: This function may receive untrusted input.
  87. This function may be invoked in SMM mode, and datasize and data are external input.
  88. This function will do basic validation, before parse the data.
  89. This function will parse the authentication carefully to avoid security issues, like
  90. buffer overflow, integer overflow.
  91. @param[in] VariableName Name of Variable to be found.
  92. @param[in] VendorGuid Variable vendor GUID.
  93. @param[in] Data Data pointer.
  94. @param[in] DataSize Size of Data found. If size is less than the
  95. data, this value contains the required size.
  96. @param[in] Attributes Attribute value of the variable.
  97. @param[in] AuthVarType Verify against PK, KEK database, private database or certificate in data payload.
  98. @param[out] VarDel Delete the variable or not.
  99. @retval EFI_INVALID_PARAMETER Invalid parameter.
  100. @retval EFI_SECURITY_VIOLATION The variable does NOT pass the validation
  101. check carried out by the firmware.
  102. @retval EFI_OUT_OF_RESOURCES Failed to process variable due to lack
  103. of resources.
  104. @retval EFI_SUCCESS Variable pass validation successfully.
  105. **/
  106. EFI_STATUS
  107. VerifyTimeBasedPayloadAndUpdate (
  108. IN CHAR16 *VariableName,
  109. IN EFI_GUID *VendorGuid,
  110. IN VOID *Data,
  111. IN UINTN DataSize,
  112. IN UINT32 Attributes,
  113. IN AUTHVAR_TYPE AuthVarType,
  114. OUT BOOLEAN *VarDel
  115. );
  116. /**
  117. Delete matching signer's certificates when deleting common authenticated
  118. variable by corresponding VariableName and VendorGuid from "certdb" or
  119. "certdbv" according to authenticated variable attributes.
  120. @param[in] VariableName Name of authenticated Variable.
  121. @param[in] VendorGuid Vendor GUID of authenticated Variable.
  122. @param[in] Attributes Attributes of authenticated variable.
  123. @retval EFI_INVALID_PARAMETER Any input parameter is invalid.
  124. @retval EFI_NOT_FOUND Fail to find "certdb"/"certdbv" or matching certs.
  125. @retval EFI_OUT_OF_RESOURCES The operation is failed due to lack of resources.
  126. @retval EFI_SUCCESS The operation is completed successfully.
  127. **/
  128. EFI_STATUS
  129. DeleteCertsFromDb (
  130. IN CHAR16 *VariableName,
  131. IN EFI_GUID *VendorGuid,
  132. IN UINT32 Attributes
  133. );
  134. /**
  135. Clean up signer's certificates for common authenticated variable
  136. by corresponding VariableName and VendorGuid from "certdb".
  137. Sytem may break down during Timebased Variable update & certdb update,
  138. make them inconsistent, this function is called in AuthVariable Init to ensure
  139. consistency
  140. @retval EFI_NOT_FOUND Fail to find matching certs.
  141. @retval EFI_SUCCESS Find matching certs and output parameters.
  142. **/
  143. EFI_STATUS
  144. CleanCertsFromDb (
  145. VOID
  146. );
  147. /**
  148. Filter out the duplicated EFI_SIGNATURE_DATA from the new data by comparing to the original data.
  149. @param[in] Data Pointer to original EFI_SIGNATURE_LIST.
  150. @param[in] DataSize Size of Data buffer.
  151. @param[in, out] NewData Pointer to new EFI_SIGNATURE_LIST.
  152. @param[in, out] NewDataSize Size of NewData buffer.
  153. **/
  154. EFI_STATUS
  155. FilterSignatureList (
  156. IN VOID *Data,
  157. IN UINTN DataSize,
  158. IN OUT VOID *NewData,
  159. IN OUT UINTN *NewDataSize
  160. );
  161. /**
  162. Process variable with platform key for verification.
  163. Caution: This function may receive untrusted input.
  164. This function may be invoked in SMM mode, and datasize and data are external input.
  165. This function will do basic validation, before parse the data.
  166. This function will parse the authentication carefully to avoid security issues, like
  167. buffer overflow, integer overflow.
  168. This function will check attribute carefully to avoid authentication bypass.
  169. @param[in] VariableName Name of Variable to be found.
  170. @param[in] VendorGuid Variable vendor GUID.
  171. @param[in] Data Data pointer.
  172. @param[in] DataSize Size of Data found. If size is less than the
  173. data, this value contains the required size.
  174. @param[in] Attributes Attribute value of the variable
  175. @param[in] IsPk Indicate whether it is to process pk.
  176. @return EFI_INVALID_PARAMETER Invalid parameter.
  177. @return EFI_SECURITY_VIOLATION The variable does NOT pass the validation.
  178. check carried out by the firmware.
  179. @return EFI_SUCCESS Variable passed validation successfully.
  180. **/
  181. EFI_STATUS
  182. ProcessVarWithPk (
  183. IN CHAR16 *VariableName,
  184. IN EFI_GUID *VendorGuid,
  185. IN VOID *Data,
  186. IN UINTN DataSize,
  187. IN UINT32 Attributes OPTIONAL,
  188. IN BOOLEAN IsPk
  189. );
  190. /**
  191. Process variable with key exchange key for verification.
  192. Caution: This function may receive untrusted input.
  193. This function may be invoked in SMM mode, and datasize and data are external input.
  194. This function will do basic validation, before parse the data.
  195. This function will parse the authentication carefully to avoid security issues, like
  196. buffer overflow, integer overflow.
  197. This function will check attribute carefully to avoid authentication bypass.
  198. @param[in] VariableName Name of Variable to be found.
  199. @param[in] VendorGuid Variable vendor GUID.
  200. @param[in] Data Data pointer.
  201. @param[in] DataSize Size of Data found. If size is less than the
  202. data, this value contains the required size.
  203. @param[in] Attributes Attribute value of the variable.
  204. @return EFI_INVALID_PARAMETER Invalid parameter.
  205. @return EFI_SECURITY_VIOLATION The variable does NOT pass the validation
  206. check carried out by the firmware.
  207. @return EFI_SUCCESS Variable pass validation successfully.
  208. **/
  209. EFI_STATUS
  210. ProcessVarWithKek (
  211. IN CHAR16 *VariableName,
  212. IN EFI_GUID *VendorGuid,
  213. IN VOID *Data,
  214. IN UINTN DataSize,
  215. IN UINT32 Attributes OPTIONAL
  216. );
  217. /**
  218. Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
  219. Caution: This function may receive untrusted input.
  220. This function may be invoked in SMM mode, and datasize and data are external input.
  221. This function will do basic validation, before parse the data.
  222. This function will parse the authentication carefully to avoid security issues, like
  223. buffer overflow, integer overflow.
  224. This function will check attribute carefully to avoid authentication bypass.
  225. @param[in] VariableName Name of the variable.
  226. @param[in] VendorGuid Variable vendor GUID.
  227. @param[in] Data Data pointer.
  228. @param[in] DataSize Size of Data.
  229. @param[in] Attributes Attribute value of the variable.
  230. @return EFI_INVALID_PARAMETER Invalid parameter.
  231. @return EFI_WRITE_PROTECTED Variable is write-protected and needs authentication with
  232. EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS or EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set.
  233. @return EFI_OUT_OF_RESOURCES The Database to save the public key is full.
  234. @return EFI_SECURITY_VIOLATION The variable is with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS
  235. set, but the AuthInfo does NOT pass the validation
  236. check carried out by the firmware.
  237. @return EFI_SUCCESS Variable is not write-protected or pass validation successfully.
  238. **/
  239. EFI_STATUS
  240. ProcessVariable (
  241. IN CHAR16 *VariableName,
  242. IN EFI_GUID *VendorGuid,
  243. IN VOID *Data,
  244. IN UINTN DataSize,
  245. IN UINT32 Attributes
  246. );
  247. /**
  248. Finds variable in storage blocks of volatile and non-volatile storage areas.
  249. This code finds variable in storage blocks of volatile and non-volatile storage areas.
  250. If VariableName is an empty string, then we just return the first
  251. qualified variable without comparing VariableName and VendorGuid.
  252. @param[in] VariableName Name of the variable to be found.
  253. @param[in] VendorGuid Variable vendor GUID to be found.
  254. @param[out] Data Pointer to data address.
  255. @param[out] DataSize Pointer to data size.
  256. @retval EFI_INVALID_PARAMETER If VariableName is not an empty string,
  257. while VendorGuid is NULL.
  258. @retval EFI_SUCCESS Variable successfully found.
  259. @retval EFI_NOT_FOUND Variable not found
  260. **/
  261. EFI_STATUS
  262. AuthServiceInternalFindVariable (
  263. IN CHAR16 *VariableName,
  264. IN EFI_GUID *VendorGuid,
  265. OUT VOID **Data,
  266. OUT UINTN *DataSize
  267. );
  268. /**
  269. Update the variable region with Variable information.
  270. @param[in] VariableName Name of variable.
  271. @param[in] VendorGuid Guid of variable.
  272. @param[in] Data Data pointer.
  273. @param[in] DataSize Size of Data.
  274. @param[in] Attributes Attribute value of the variable.
  275. @retval EFI_SUCCESS The update operation is success.
  276. @retval EFI_INVALID_PARAMETER Invalid parameter.
  277. @retval EFI_WRITE_PROTECTED Variable is write-protected.
  278. @retval EFI_OUT_OF_RESOURCES There is not enough resource.
  279. **/
  280. EFI_STATUS
  281. AuthServiceInternalUpdateVariable (
  282. IN CHAR16 *VariableName,
  283. IN EFI_GUID *VendorGuid,
  284. IN VOID *Data,
  285. IN UINTN DataSize,
  286. IN UINT32 Attributes
  287. );
  288. /**
  289. Update the variable region with Variable information.
  290. @param[in] VariableName Name of variable.
  291. @param[in] VendorGuid Guid of variable.
  292. @param[in] Data Data pointer.
  293. @param[in] DataSize Size of Data.
  294. @param[in] Attributes Attribute value of the variable.
  295. @param[in] TimeStamp Value of associated TimeStamp.
  296. @retval EFI_SUCCESS The update operation is success.
  297. @retval EFI_INVALID_PARAMETER Invalid parameter.
  298. @retval EFI_WRITE_PROTECTED Variable is write-protected.
  299. @retval EFI_OUT_OF_RESOURCES There is not enough resource.
  300. **/
  301. EFI_STATUS
  302. AuthServiceInternalUpdateVariableWithTimeStamp (
  303. IN CHAR16 *VariableName,
  304. IN EFI_GUID *VendorGuid,
  305. IN VOID *Data,
  306. IN UINTN DataSize,
  307. IN UINT32 Attributes,
  308. IN EFI_TIME *TimeStamp
  309. );
  310. #endif