2 Implement image verification services for secure boot service in UEFI2.3.1.
4 Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #include "DxeImageVerificationLib.h"
17 EFI_IMAGE_OPTIONAL_HEADER_PTR_UNION mNtHeader
;
19 UINT32 mPeCoffHeaderOffset
;
20 UINT8 mImageDigest
[MAX_DIGEST_SIZE
];
21 UINTN mImageDigestSize
;
22 EFI_IMAGE_DATA_DIRECTORY
*mSecDataDir
= NULL
;
23 UINT8
*mImageBase
= NULL
;
27 // Notify string for authorization UI.
29 CHAR16 mNotifyString1
[MAX_NOTIFY_STRING_LEN
] = L
"Image verification pass but not found in authorized database!";
30 CHAR16 mNotifyString2
[MAX_NOTIFY_STRING_LEN
] = L
"Launch this image anyway? (Yes/Defer/No)";
32 // Public Exponent of RSA Key.
34 CONST UINT8 mRsaE
[] = { 0x01, 0x00, 0x01 };
38 // OID ASN.1 Value for Hash Algorithms
40 UINT8 mHashOidValue
[] = {
41 0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05, // OBJ_md5
42 0x2B, 0x0E, 0x03, 0x02, 0x1A, // OBJ_sha1
43 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x04, // OBJ_sha224
44 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, // OBJ_sha256
45 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x02, // OBJ_sha384
46 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03, // OBJ_sha512
49 HASH_TABLE mHash
[] = {
50 { L
"SHA1", 20, &mHashOidValue
[8], 5, Sha1GetContextSize
, Sha1Init
, Sha1Update
, Sha1Final
},
51 { L
"SHA224", 28, &mHashOidValue
[13], 9, NULL
, NULL
, NULL
, NULL
},
52 { L
"SHA256", 32, &mHashOidValue
[22], 9, Sha256GetContextSize
,Sha256Init
, Sha256Update
, Sha256Final
},
53 { L
"SHA384", 48, &mHashOidValue
[31], 9, NULL
, NULL
, NULL
, NULL
},
54 { L
"SHA512", 64, &mHashOidValue
[40], 9, NULL
, NULL
, NULL
, NULL
}
61 @param[in] File This is a pointer to the device path of the file that is
64 @return UINT32 Image Type
69 IN CONST EFI_DEVICE_PATH_PROTOCOL
*File
73 EFI_HANDLE DeviceHandle
;
74 EFI_DEVICE_PATH_PROTOCOL
*TempDevicePath
;
75 EFI_BLOCK_IO_PROTOCOL
*BlockIo
;
78 // First check to see if File is from a Firmware Volume
81 TempDevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) File
;
82 Status
= gBS
->LocateDevicePath (
83 &gEfiFirmwareVolume2ProtocolGuid
,
87 if (!EFI_ERROR (Status
)) {
88 Status
= gBS
->OpenProtocol (
90 &gEfiFirmwareVolume2ProtocolGuid
,
94 EFI_OPEN_PROTOCOL_TEST_PROTOCOL
96 if (!EFI_ERROR (Status
)) {
102 // Next check to see if File is from a Block I/O device
105 TempDevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) File
;
106 Status
= gBS
->LocateDevicePath (
107 &gEfiBlockIoProtocolGuid
,
111 if (!EFI_ERROR (Status
)) {
113 Status
= gBS
->OpenProtocol (
115 &gEfiBlockIoProtocolGuid
,
119 EFI_OPEN_PROTOCOL_GET_PROTOCOL
121 if (!EFI_ERROR (Status
) && BlockIo
!= NULL
) {
122 if (BlockIo
->Media
!= NULL
) {
123 if (BlockIo
->Media
->RemovableMedia
) {
125 // Block I/O is present and specifies the media is removable
127 return IMAGE_FROM_REMOVABLE_MEDIA
;
130 // Block I/O is present and specifies the media is not removable
132 return IMAGE_FROM_FIXED_MEDIA
;
139 // File is not in a Firmware Volume or on a Block I/O device, so check to see if
140 // the device path supports the Simple File System Protocol.
143 TempDevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) File
;
144 Status
= gBS
->LocateDevicePath (
145 &gEfiSimpleFileSystemProtocolGuid
,
149 if (!EFI_ERROR (Status
)) {
151 // Simple File System is present without Block I/O, so assume media is fixed.
153 return IMAGE_FROM_FIXED_MEDIA
;
157 // File is not from an FV, Block I/O or Simple File System, so the only options
158 // left are a PCI Option ROM and a Load File Protocol such as a PXE Boot from a NIC.
160 TempDevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) File
;
161 while (!IsDevicePathEndType (TempDevicePath
)) {
162 switch (DevicePathType (TempDevicePath
)) {
164 case MEDIA_DEVICE_PATH
:
165 if (DevicePathSubType (TempDevicePath
) == MEDIA_RELATIVE_OFFSET_RANGE_DP
) {
166 return IMAGE_FROM_OPTION_ROM
;
170 case MESSAGING_DEVICE_PATH
:
171 if (DevicePathSubType(TempDevicePath
) == MSG_MAC_ADDR_DP
) {
172 return IMAGE_FROM_REMOVABLE_MEDIA
;
179 TempDevicePath
= NextDevicePathNode (TempDevicePath
);
181 return IMAGE_UNKNOWN
;
185 Caculate hash of Pe/Coff image based on the authenticode image hashing in
186 PE/COFF Specification 8.0 Appendix A
188 @param[in] HashAlg Hash algorithm type.
190 @retval TRUE Successfully hash image.
191 @retval FALSE Fail in hash image.
201 EFI_IMAGE_SECTION_HEADER
*Section
;
206 UINTN SumOfBytesHashed
;
207 EFI_IMAGE_SECTION_HEADER
*SectionHeader
;
210 UINTN SumOfSectionBytes
;
211 EFI_IMAGE_SECTION_HEADER
*SectionCache
;
214 SectionHeader
= NULL
;
217 if ((HashAlg
!= HASHALG_SHA1
) && (HashAlg
!= HASHALG_SHA256
)) {
222 // Initialize context of hash.
224 ZeroMem (mImageDigest
, MAX_DIGEST_SIZE
);
226 if (HashAlg
== HASHALG_SHA1
) {
227 mImageDigestSize
= SHA1_DIGEST_SIZE
;
228 mCertType
= gEfiCertSha1Guid
;
229 } else if (HashAlg
== HASHALG_SHA256
) {
230 mImageDigestSize
= SHA256_DIGEST_SIZE
;
231 mCertType
= gEfiCertSha256Guid
;
236 CtxSize
= mHash
[HashAlg
].GetContextSize();
238 HashCtx
= AllocatePool (CtxSize
);
239 if (HashCtx
== NULL
) {
243 // 1. Load the image header into memory.
245 // 2. Initialize a SHA hash context.
246 Status
= mHash
[HashAlg
].HashInit(HashCtx
);
252 // Measuring PE/COFF Image Header;
253 // But CheckSum field and SECURITY data directory (certificate) are excluded
255 Magic
= mNtHeader
.Pe32
->OptionalHeader
.Magic
;
257 // 3. Calculate the distance from the base of the image header to the image checksum address.
258 // 4. Hash the image header from its base to beginning of the image checksum.
260 HashBase
= mImageBase
;
261 if (Magic
== EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC
) {
265 HashSize
= (UINTN
) ((UINT8
*) (&mNtHeader
.Pe32
->OptionalHeader
.CheckSum
) - HashBase
);
266 } else if (Magic
== EFI_IMAGE_NT_OPTIONAL_HDR64_MAGIC
) {
270 HashSize
= (UINTN
) ((UINT8
*) (&mNtHeader
.Pe32Plus
->OptionalHeader
.CheckSum
) - HashBase
);
273 // Invalid header magic number.
279 Status
= mHash
[HashAlg
].HashUpdate(HashCtx
, HashBase
, HashSize
);
284 // 5. Skip over the image checksum (it occupies a single ULONG).
285 // 6. Get the address of the beginning of the Cert Directory.
286 // 7. Hash everything from the end of the checksum to the start of the Cert Directory.
288 if (Magic
== EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC
) {
292 HashBase
= (UINT8
*) &mNtHeader
.Pe32
->OptionalHeader
.CheckSum
+ sizeof (UINT32
);
293 HashSize
= (UINTN
) ((UINT8
*) (&mNtHeader
.Pe32
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
]) - HashBase
);
298 HashBase
= (UINT8
*) &mNtHeader
.Pe32Plus
->OptionalHeader
.CheckSum
+ sizeof (UINT32
);
299 HashSize
= (UINTN
) ((UINT8
*) (&mNtHeader
.Pe32Plus
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
]) - HashBase
);
302 Status
= mHash
[HashAlg
].HashUpdate(HashCtx
, HashBase
, HashSize
);
307 // 8. Skip over the Cert Directory. (It is sizeof(IMAGE_DATA_DIRECTORY) bytes.)
308 // 9. Hash everything from the end of the Cert Directory to the end of image header.
310 if (Magic
== EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC
) {
314 HashBase
= (UINT8
*) &mNtHeader
.Pe32
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
+ 1];
315 HashSize
= mNtHeader
.Pe32
->OptionalHeader
.SizeOfHeaders
- (UINTN
) ((UINT8
*) (&mNtHeader
.Pe32
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
+ 1]) - mImageBase
);
320 HashBase
= (UINT8
*) &mNtHeader
.Pe32Plus
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
+ 1];
321 HashSize
= mNtHeader
.Pe32Plus
->OptionalHeader
.SizeOfHeaders
- (UINTN
) ((UINT8
*) (&mNtHeader
.Pe32Plus
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
+ 1]) - mImageBase
);
324 Status
= mHash
[HashAlg
].HashUpdate(HashCtx
, HashBase
, HashSize
);
329 // 10. Set the SUM_OF_BYTES_HASHED to the size of the header.
331 if (Magic
== EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC
) {
335 SumOfBytesHashed
= mNtHeader
.Pe32
->OptionalHeader
.SizeOfHeaders
;
340 SumOfBytesHashed
= mNtHeader
.Pe32Plus
->OptionalHeader
.SizeOfHeaders
;
344 Section
= (EFI_IMAGE_SECTION_HEADER
*) (
346 mPeCoffHeaderOffset
+
348 sizeof (EFI_IMAGE_FILE_HEADER
) +
349 mNtHeader
.Pe32
->FileHeader
.SizeOfOptionalHeader
352 SectionCache
= Section
;
353 for (Index
= 0, SumOfSectionBytes
= 0; Index
< mNtHeader
.Pe32
->FileHeader
.NumberOfSections
; Index
++, SectionCache
++) {
354 SumOfSectionBytes
+= SectionCache
->SizeOfRawData
;
358 // Sanity check for file corruption. Sections raw data size should be smaller
361 if (SumOfSectionBytes
>= mImageSize
) {
367 // 11. Build a temporary table of pointers to all the IMAGE_SECTION_HEADER
368 // structures in the image. The 'NumberOfSections' field of the image
369 // header indicates how big the table should be. Do not include any
370 // IMAGE_SECTION_HEADERs in the table whose 'SizeOfRawData' field is zero.
372 SectionHeader
= (EFI_IMAGE_SECTION_HEADER
*) AllocateZeroPool (sizeof (EFI_IMAGE_SECTION_HEADER
) * mNtHeader
.Pe32
->FileHeader
.NumberOfSections
);
373 if (SectionHeader
== NULL
) {
378 // 12. Using the 'PointerToRawData' in the referenced section headers as
379 // a key, arrange the elements in the table in ascending order. In other
380 // words, sort the section headers according to the disk-file offset of
383 for (Index
= 0; Index
< mNtHeader
.Pe32
->FileHeader
.NumberOfSections
; Index
++) {
385 while ((Pos
> 0) && (Section
->PointerToRawData
< SectionHeader
[Pos
- 1].PointerToRawData
)) {
386 CopyMem (&SectionHeader
[Pos
], &SectionHeader
[Pos
- 1], sizeof (EFI_IMAGE_SECTION_HEADER
));
389 CopyMem (&SectionHeader
[Pos
], Section
, sizeof (EFI_IMAGE_SECTION_HEADER
));
394 // 13. Walk through the sorted table, bring the corresponding section
395 // into memory, and hash the entire section (using the 'SizeOfRawData'
396 // field in the section header to determine the amount of data to hash).
397 // 14. Add the section's 'SizeOfRawData' to SUM_OF_BYTES_HASHED .
398 // 15. Repeat steps 13 and 14 for all the sections in the sorted table.
400 for (Index
= 0; Index
< mNtHeader
.Pe32
->FileHeader
.NumberOfSections
; Index
++) {
401 Section
= &SectionHeader
[Index
];
402 if (Section
->SizeOfRawData
== 0) {
405 HashBase
= mImageBase
+ Section
->PointerToRawData
;
406 HashSize
= (UINTN
) Section
->SizeOfRawData
;
408 Status
= mHash
[HashAlg
].HashUpdate(HashCtx
, HashBase
, HashSize
);
413 SumOfBytesHashed
+= HashSize
;
417 // 16. If the file size is greater than SUM_OF_BYTES_HASHED, there is extra
418 // data in the file that needs to be added to the hash. This data begins
419 // at file offset SUM_OF_BYTES_HASHED and its length is:
420 // FileSize - (CertDirectory->Size)
422 if (mImageSize
> SumOfBytesHashed
) {
423 HashBase
= mImageBase
+ SumOfBytesHashed
;
424 if (Magic
== EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC
) {
430 mNtHeader
.Pe32
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
].Size
-
438 mNtHeader
.Pe32Plus
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
].Size
-
442 Status
= mHash
[HashAlg
].HashUpdate(HashCtx
, HashBase
, HashSize
);
447 Status
= mHash
[HashAlg
].HashFinal(HashCtx
, mImageDigest
);
450 if (HashCtx
!= NULL
) {
453 if (SectionHeader
!= NULL
) {
454 FreePool (SectionHeader
);
460 Recognize the Hash algorithm in PE/COFF Authenticode and caculate hash of
461 Pe/Coff image based on the authenticode image hashing in PE/COFF Specification
464 @retval EFI_UNSUPPORTED Hash algorithm is not supported.
465 @retval EFI_SUCCESS Hash successfully.
474 WIN_CERTIFICATE_EFI_PKCS
*PkcsCertData
;
476 PkcsCertData
= (WIN_CERTIFICATE_EFI_PKCS
*) (mImageBase
+ mSecDataDir
->VirtualAddress
);
478 for (Index
= 0; Index
< HASHALG_MAX
; Index
++) {
480 // Check the Hash algorithm in PE/COFF Authenticode.
481 // According to PKCS#7 Definition:
482 // SignedData ::= SEQUENCE {
484 // digestAlgorithms DigestAlgorithmIdentifiers,
485 // contentInfo ContentInfo,
487 // The DigestAlgorithmIdentifiers can be used to determine the hash algorithm in PE/COFF hashing
488 // This field has the fixed offset (+32) in final Authenticode ASN.1 data.
490 if (CompareMem (PkcsCertData
->CertData
+ 32, mHash
[Index
].OidValue
, mHash
[Index
].OidLength
) == 0) {
495 if (Index
== HASHALG_MAX
) {
496 return EFI_UNSUPPORTED
;
500 // HASH PE Image based on Hash algorithm in PE/COFF Authenticode.
502 if (!HashPeImage(Index
)) {
503 return EFI_UNSUPPORTED
;
511 Returns the size of a given image execution info table in bytes.
513 This function returns the size, in bytes, of the image execution info table specified by
514 ImageExeInfoTable. If ImageExeInfoTable is NULL, then 0 is returned.
516 @param ImageExeInfoTable A pointer to a image execution info table structure.
518 @retval 0 If ImageExeInfoTable is NULL.
519 @retval Others The size of a image execution info table in bytes.
523 GetImageExeInfoTableSize (
524 EFI_IMAGE_EXECUTION_INFO_TABLE
*ImageExeInfoTable
528 EFI_IMAGE_EXECUTION_INFO
*ImageExeInfoItem
;
531 if (ImageExeInfoTable
== NULL
) {
535 ImageExeInfoItem
= (EFI_IMAGE_EXECUTION_INFO
*) ((UINT8
*) ImageExeInfoTable
+ sizeof (EFI_IMAGE_EXECUTION_INFO_TABLE
));
536 TotalSize
= sizeof (EFI_IMAGE_EXECUTION_INFO_TABLE
);
537 for (Index
= 0; Index
< ImageExeInfoTable
->NumberOfImages
; Index
++) {
538 TotalSize
+= ReadUnaligned32 ((UINT32
*) &ImageExeInfoItem
->InfoSize
);
539 ImageExeInfoItem
= (EFI_IMAGE_EXECUTION_INFO
*) ((UINT8
*) ImageExeInfoItem
+ ReadUnaligned32 ((UINT32
*) &ImageExeInfoItem
->InfoSize
));
546 Create an Image Execution Information Table entry and add it to system configuration table.
548 @param[in] Action Describes the action taken by the firmware regarding this image.
549 @param[in] Name Input a null-terminated, user-friendly name.
550 @param[in] DevicePath Input device path pointer.
551 @param[in] Signature Input signature info in EFI_SIGNATURE_LIST data structure.
552 @param[in] SignatureSize Size of signature.
557 IN EFI_IMAGE_EXECUTION_ACTION Action
,
558 IN CHAR16
*Name OPTIONAL
,
559 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
560 IN EFI_SIGNATURE_LIST
*Signature OPTIONAL
,
561 IN UINTN SignatureSize
564 EFI_IMAGE_EXECUTION_INFO_TABLE
*ImageExeInfoTable
;
565 EFI_IMAGE_EXECUTION_INFO_TABLE
*NewImageExeInfoTable
;
566 EFI_IMAGE_EXECUTION_INFO
*ImageExeInfoEntry
;
567 UINTN ImageExeInfoTableSize
;
568 UINTN NewImageExeInfoEntrySize
;
570 UINTN DevicePathSize
;
572 ImageExeInfoTable
= NULL
;
573 NewImageExeInfoTable
= NULL
;
574 ImageExeInfoEntry
= NULL
;
577 if (DevicePath
== NULL
) {
582 NameStringLen
= StrSize (Name
);
585 ImageExeInfoTable
= NULL
;
586 EfiGetSystemConfigurationTable (&gEfiImageSecurityDatabaseGuid
, (VOID
**) &ImageExeInfoTable
);
587 if (ImageExeInfoTable
!= NULL
) {
589 // The table has been found!
590 // We must enlarge the table to accmodate the new exe info entry.
592 ImageExeInfoTableSize
= GetImageExeInfoTableSize (ImageExeInfoTable
);
596 // We should create a new table to append to the configuration table.
598 ImageExeInfoTableSize
= sizeof (EFI_IMAGE_EXECUTION_INFO_TABLE
);
601 DevicePathSize
= GetDevicePathSize (DevicePath
);
602 NewImageExeInfoEntrySize
= sizeof (EFI_IMAGE_EXECUTION_INFO
) + NameStringLen
+ DevicePathSize
+ SignatureSize
;
603 NewImageExeInfoTable
= (EFI_IMAGE_EXECUTION_INFO_TABLE
*) AllocateRuntimePool (ImageExeInfoTableSize
+ NewImageExeInfoEntrySize
);
604 if (NewImageExeInfoTable
== NULL
) {
608 if (ImageExeInfoTable
!= NULL
) {
609 CopyMem (NewImageExeInfoTable
, ImageExeInfoTable
, ImageExeInfoTableSize
);
611 NewImageExeInfoTable
->NumberOfImages
= 0;
613 NewImageExeInfoTable
->NumberOfImages
++;
614 ImageExeInfoEntry
= (EFI_IMAGE_EXECUTION_INFO
*) ((UINT8
*) NewImageExeInfoTable
+ ImageExeInfoTableSize
);
616 // Update new item's infomation.
618 WriteUnaligned32 ((UINT32
*) &ImageExeInfoEntry
->Action
, Action
);
619 WriteUnaligned32 ((UINT32
*) &ImageExeInfoEntry
->InfoSize
, (UINT32
) NewImageExeInfoEntrySize
);
622 CopyMem ((UINT8
*) &ImageExeInfoEntry
->InfoSize
+ sizeof (UINT32
), Name
, NameStringLen
);
625 (UINT8
*) &ImageExeInfoEntry
->InfoSize
+ sizeof (UINT32
) + NameStringLen
,
629 if (Signature
!= NULL
) {
631 (UINT8
*) &ImageExeInfoEntry
->InfoSize
+ sizeof (UINT32
) + NameStringLen
+ DevicePathSize
,
637 // Update/replace the image execution table.
639 gBS
->InstallConfigurationTable (&gEfiImageSecurityDatabaseGuid
, (VOID
*) NewImageExeInfoTable
);
642 // Free Old table data!
644 if (ImageExeInfoTable
!= NULL
) {
645 FreePool (ImageExeInfoTable
);
650 Discover if the UEFI image is authorized by user's policy setting.
652 @param[in] Policy Specify platform's policy setting.
654 @retval EFI_ACCESS_DENIED Image is not allowed to run.
655 @retval EFI_SECURITY_VIOLATION Image is deferred.
656 @retval EFI_SUCCESS Image is authorized to run.
667 Status
= EFI_ACCESS_DENIED
;
671 case QUERY_USER_ON_SECURITY_VIOLATION
:
673 CreatePopUp (EFI_LIGHTGRAY
| EFI_BACKGROUND_BLUE
, &Key
, mNotifyString1
, mNotifyString2
, NULL
);
674 if (Key
.UnicodeChar
== L
'Y' || Key
.UnicodeChar
== L
'y') {
675 Status
= EFI_SUCCESS
;
677 } else if (Key
.UnicodeChar
== L
'N' || Key
.UnicodeChar
== L
'n') {
678 Status
= EFI_ACCESS_DENIED
;
680 } else if (Key
.UnicodeChar
== L
'D' || Key
.UnicodeChar
== L
'd') {
681 Status
= EFI_SECURITY_VIOLATION
;
687 case ALLOW_EXECUTE_ON_SECURITY_VIOLATION
:
688 Status
= EFI_SUCCESS
;
691 case DEFER_EXECUTE_ON_SECURITY_VIOLATION
:
692 Status
= EFI_SECURITY_VIOLATION
;
695 case DENY_EXECUTE_ON_SECURITY_VIOLATION
:
696 Status
= EFI_ACCESS_DENIED
;
704 Check whether signature is in specified database.
706 @param[in] VariableName Name of database variable that is searched in.
707 @param[in] Signature Pointer to signature that is searched for.
708 @param[in] CertType Pointer to hash algrithom.
709 @param[in] SignatureSize Size of Signature.
711 @return TRUE Found the signature in the variable database.
712 @return FALSE Not found the signature in the variable database.
716 IsSignatureFoundInDatabase (
717 IN CHAR16
*VariableName
,
719 IN EFI_GUID
*CertType
,
720 IN UINTN SignatureSize
724 EFI_SIGNATURE_LIST
*CertList
;
725 EFI_SIGNATURE_DATA
*Cert
;
732 // Read signature database variable.
737 Status
= gRT
->GetVariable (VariableName
, &gEfiImageSecurityDatabaseGuid
, NULL
, &DataSize
, NULL
);
738 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
742 Data
= (UINT8
*) AllocateZeroPool (DataSize
);
747 Status
= gRT
->GetVariable (VariableName
, &gEfiImageSecurityDatabaseGuid
, NULL
, &DataSize
, Data
);
748 if (EFI_ERROR (Status
)) {
752 // Enumerate all signature data in SigDB to check if executable's signature exists.
754 CertList
= (EFI_SIGNATURE_LIST
*) Data
;
755 while ((DataSize
> 0) && (DataSize
>= CertList
->SignatureListSize
)) {
756 CertCount
= (CertList
->SignatureListSize
- CertList
->SignatureHeaderSize
) / CertList
->SignatureSize
;
757 Cert
= (EFI_SIGNATURE_DATA
*) ((UINT8
*) CertList
+ sizeof (EFI_SIGNATURE_LIST
) + CertList
->SignatureHeaderSize
);
758 if ((CertList
->SignatureSize
== sizeof(EFI_SIGNATURE_DATA
) - 1 + SignatureSize
) && (CompareGuid(&CertList
->SignatureType
, CertType
))) {
759 for (Index
= 0; Index
< CertCount
; Index
++) {
760 if (CompareMem (Cert
->SignatureData
, Signature
, SignatureSize
) == 0) {
762 // Find the signature in database.
768 Cert
= (EFI_SIGNATURE_DATA
*) ((UINT8
*) Cert
+ CertList
->SignatureSize
);
776 DataSize
-= CertList
->SignatureListSize
;
777 CertList
= (EFI_SIGNATURE_LIST
*) ((UINT8
*) CertList
+ CertList
->SignatureListSize
);
789 Verify PKCS#7 SignedData using certificate found in Variable which formatted
790 as EFI_SIGNATURE_LIST. The Variable may be PK, KEK, DB or DBX.
792 @param VariableName Name of Variable to search for Certificate.
793 @param VendorGuid Variable vendor GUID.
795 @retval TRUE Image pass verification.
796 @retval FALSE Image fail verification.
800 IsPkcsSignedDataVerifiedBySignatureList (
801 IN CHAR16
*VariableName
,
802 IN EFI_GUID
*VendorGuid
806 BOOLEAN VerifyStatus
;
807 WIN_CERTIFICATE_EFI_PKCS
*PkcsCertData
;
808 EFI_SIGNATURE_LIST
*CertList
;
809 EFI_SIGNATURE_DATA
*Cert
;
822 VerifyStatus
= FALSE
;
823 PkcsCertData
= (WIN_CERTIFICATE_EFI_PKCS
*) (mImageBase
+ mSecDataDir
->VirtualAddress
);
826 Status
= gRT
->GetVariable (VariableName
, VendorGuid
, NULL
, &DataSize
, NULL
);
827 if (Status
== EFI_BUFFER_TOO_SMALL
) {
828 Data
= (UINT8
*) AllocateZeroPool (DataSize
);
833 Status
= gRT
->GetVariable (VariableName
, VendorGuid
, NULL
, &DataSize
, (VOID
*) Data
);
834 if (EFI_ERROR (Status
)) {
839 // Find X509 certificate in Signature List to verify the signature in pkcs7 signed data.
841 CertList
= (EFI_SIGNATURE_LIST
*) Data
;
842 while ((DataSize
> 0) && (DataSize
>= CertList
->SignatureListSize
)) {
843 if (CompareGuid (&CertList
->SignatureType
, &gEfiCertX509Guid
)) {
844 Cert
= (EFI_SIGNATURE_DATA
*) ((UINT8
*) CertList
+ sizeof (EFI_SIGNATURE_LIST
) + CertList
->SignatureHeaderSize
);
845 CertCount
= (CertList
->SignatureListSize
- sizeof (EFI_SIGNATURE_LIST
) - CertList
->SignatureHeaderSize
) / CertList
->SignatureSize
;
846 for (Index
= 0; Index
< CertCount
; Index
++) {
848 // Iterate each Signature Data Node within this CertList for verify.
850 RootCert
= Cert
->SignatureData
;
851 RootCertSize
= CertList
->SignatureSize
;
854 // Call AuthenticodeVerify library to Verify Authenticode struct.
856 VerifyStatus
= AuthenticodeVerify (
857 PkcsCertData
->CertData
,
858 mSecDataDir
->Size
- sizeof(PkcsCertData
->Hdr
),
867 Cert
= (EFI_SIGNATURE_DATA
*) ((UINT8
*) Cert
+ CertList
->SignatureSize
);
870 DataSize
-= CertList
->SignatureListSize
;
871 CertList
= (EFI_SIGNATURE_LIST
*) ((UINT8
*) CertList
+ CertList
->SignatureListSize
);
884 Verify certificate in WIN_CERT_TYPE_PKCS_SIGNED_DATA format.
886 @retval EFI_SUCCESS Image pass verification.
887 @retval EFI_SECURITY_VIOLATION Image fail verification.
891 VerifyCertPkcsSignedData (
896 // 1: Find certificate from DBX forbidden database for revoked certificate.
898 if (IsPkcsSignedDataVerifiedBySignatureList (EFI_IMAGE_SECURITY_DATABASE1
, &gEfiImageSecurityDatabaseGuid
)) {
900 // DBX is forbidden database, if Authenticode verification pass with
901 // one of the certificate in DBX, this image should be rejected.
903 return EFI_SECURITY_VIOLATION
;
907 // 2: Find certificate from KEK database and try to verify authenticode struct.
909 if (IsPkcsSignedDataVerifiedBySignatureList (EFI_KEY_EXCHANGE_KEY_NAME
, &gEfiGlobalVariableGuid
)) {
914 // 3: Find certificate from DB database and try to verify authenticode struct.
916 if (IsPkcsSignedDataVerifiedBySignatureList (EFI_IMAGE_SECURITY_DATABASE
, &gEfiImageSecurityDatabaseGuid
)) {
919 return EFI_SECURITY_VIOLATION
;
924 Verify certificate in WIN_CERTIFICATE_UEFI_GUID format.
926 @retval EFI_SUCCESS Image pass verification.
927 @retval EFI_SECURITY_VIOLATION Image fail verification.
928 @retval other error value
937 WIN_CERTIFICATE_UEFI_GUID
*EfiCert
;
938 EFI_SIGNATURE_LIST
*KekList
;
939 EFI_SIGNATURE_DATA
*KekItem
;
940 EFI_CERT_BLOCK_RSA_2048_SHA256
*CertBlock
;
957 EfiCert
= (WIN_CERTIFICATE_UEFI_GUID
*) (mImageBase
+ mSecDataDir
->VirtualAddress
);
958 CertBlock
= (EFI_CERT_BLOCK_RSA_2048_SHA256
*) EfiCert
->CertData
;
959 if (!CompareGuid (&EfiCert
->CertType
, &gEfiCertTypeRsa2048Sha256Guid
)) {
961 // Invalid Certificate Data Type.
963 return EFI_SECURITY_VIOLATION
;
967 // Get KEK database variable data size
969 Result
= gRT
->GetVariable (EFI_KEY_EXCHANGE_KEY_NAME
, &gEfiGlobalVariableGuid
, NULL
, &KekDataSize
, NULL
);
970 if (Result
!= EFI_BUFFER_TOO_SMALL
) {
971 return EFI_SECURITY_VIOLATION
;
975 // Get KEK database variable.
977 KekList
= GetEfiGlobalVariable (EFI_KEY_EXCHANGE_KEY_NAME
);
978 if (KekList
== NULL
) {
979 return EFI_SECURITY_VIOLATION
;
983 // Enumerate all Kek items in this list to verify the variable certificate data.
984 // If anyone is authenticated successfully, it means the variable is correct!
986 while ((KekDataSize
> 0) && (KekDataSize
>= KekList
->SignatureListSize
)) {
987 if (CompareGuid (&KekList
->SignatureType
, &gEfiCertRsa2048Guid
)) {
988 KekItem
= (EFI_SIGNATURE_DATA
*) ((UINT8
*) KekList
+ sizeof (EFI_SIGNATURE_LIST
) + KekList
->SignatureHeaderSize
);
989 KekCount
= (KekList
->SignatureListSize
- sizeof (EFI_SIGNATURE_LIST
) - KekList
->SignatureHeaderSize
) / KekList
->SignatureSize
;
990 for (Index
= 0; Index
< KekCount
; Index
++) {
991 if (CompareMem (KekItem
->SignatureData
, CertBlock
->PublicKey
, EFI_CERT_TYPE_RSA2048_SIZE
) == 0) {
995 KekItem
= (EFI_SIGNATURE_DATA
*) ((UINT8
*) KekItem
+ KekList
->SignatureSize
);
998 KekDataSize
-= KekList
->SignatureListSize
;
999 KekList
= (EFI_SIGNATURE_LIST
*) ((UINT8
*) KekList
+ KekList
->SignatureListSize
);
1004 // Signed key is not a trust one.
1010 // Now, we found the corresponding security policy.
1011 // Verify the data payload.
1020 // Set RSA Key Components.
1021 // NOTE: Only N and E are needed to be set as RSA public key for signature verification.
1023 Status
= RsaSetKey (Rsa
, RsaKeyN
, CertBlock
->PublicKey
, EFI_CERT_TYPE_RSA2048_SIZE
);
1027 Status
= RsaSetKey (Rsa
, RsaKeyE
, mRsaE
, sizeof (mRsaE
));
1032 // Verify the signature.
1034 Status
= RsaPkcs1Verify (
1038 CertBlock
->Signature
,
1039 EFI_CERT_TYPE_RSA2048_SHA256_SIZE
1043 if (KekList
!= NULL
) {
1052 return EFI_SECURITY_VIOLATION
;
1057 Provide verification service for signed images, which include both signature validation
1058 and platform policy control. For signature types, both UEFI WIN_CERTIFICATE_UEFI_GUID and
1059 MSFT Authenticode type signatures are supported.
1061 In this implementation, only verify external executables when in USER MODE.
1062 Executables from FV is bypass, so pass in AuthenticationStatus is ignored.
1064 The image verification process is:
1065 Is the Image signed?
1067 Does the image verify against a certificate (root or intermediate) in the allowed db?
1069 Image verification fail
1070 Is the Image's Hash not in forbidden database and the Image's Hash in allowed db?
1073 Is the Image's Hash in the forbidden database (DBX)?
1076 Is the Image's Hash in the allowed database (DB)?
1082 @param[in] AuthenticationStatus
1083 This is the authentication status returned from the security
1084 measurement services for the input file.
1085 @param[in] File This is a pointer to the device path of the file that is
1086 being dispatched. This will optionally be used for logging.
1087 @param[in] FileBuffer File buffer matches the input file device path.
1088 @param[in] FileSize Size of File buffer matches the input file device path.
1090 @retval EFI_SUCCESS The file specified by File did authenticate, and the
1091 platform policy dictates that the DXE Core may use File.
1092 @retval EFI_INVALID_PARAMETER Input argument is incorrect.
1093 @retval EFI_OUT_RESOURCE Fail to allocate memory.
1094 @retval EFI_SECURITY_VIOLATION The file specified by File did not authenticate, and
1095 the platform policy dictates that File should be placed
1096 in the untrusted state. A file may be promoted from
1097 the untrusted to the trusted state at a future time
1098 with a call to the Trust() DXE Service.
1099 @retval EFI_ACCESS_DENIED The file specified by File did not authenticate, and
1100 the platform policy dictates that File should not be
1101 used for any purpose.
1106 DxeImageVerificationHandler (
1107 IN UINT32 AuthenticationStatus
,
1108 IN CONST EFI_DEVICE_PATH_PROTOCOL
*File
,
1109 IN VOID
*FileBuffer
,
1115 EFI_IMAGE_DOS_HEADER
*DosHdr
;
1116 EFI_STATUS VerifyStatus
;
1118 EFI_SIGNATURE_LIST
*SignatureList
;
1119 UINTN SignatureListSize
;
1120 EFI_SIGNATURE_DATA
*Signature
;
1121 EFI_IMAGE_EXECUTION_ACTION Action
;
1122 WIN_CERTIFICATE
*WinCertificate
;
1124 UINT8
*SecureBootEnable
;
1127 return EFI_INVALID_PARAMETER
;
1130 SignatureList
= NULL
;
1131 SignatureListSize
= 0;
1132 WinCertificate
= NULL
;
1133 Action
= EFI_IMAGE_EXECUTION_AUTH_UNTESTED
;
1134 Status
= EFI_ACCESS_DENIED
;
1136 // Check the image type and get policy setting.
1138 switch (GetImageType (File
)) {
1141 Policy
= ALWAYS_EXECUTE
;
1144 case IMAGE_FROM_OPTION_ROM
:
1145 Policy
= PcdGet32 (PcdOptionRomImageVerificationPolicy
);
1148 case IMAGE_FROM_REMOVABLE_MEDIA
:
1149 Policy
= PcdGet32 (PcdRemovableMediaImageVerificationPolicy
);
1152 case IMAGE_FROM_FIXED_MEDIA
:
1153 Policy
= PcdGet32 (PcdFixedMediaImageVerificationPolicy
);
1157 Policy
= DENY_EXECUTE_ON_SECURITY_VIOLATION
;
1161 // If policy is always/never execute, return directly.
1163 if (Policy
== ALWAYS_EXECUTE
) {
1165 } else if (Policy
== NEVER_EXECUTE
) {
1166 return EFI_ACCESS_DENIED
;
1169 SecureBootEnable
= GetVariable (EFI_SECURE_BOOT_ENABLE_NAME
, &gEfiSecureBootEnableDisableGuid
);
1171 // Skip verification if SecureBootEnable variable doesn't exist.
1173 if (SecureBootEnable
== NULL
) {
1178 // Skip verification if SecureBootEnable is disabled.
1180 if (*SecureBootEnable
== SECURE_BOOT_DISABLE
) {
1181 FreePool (SecureBootEnable
);
1185 SetupMode
= GetEfiGlobalVariable (EFI_SETUP_MODE_NAME
);
1188 // SetupMode doesn't exist means no AuthVar driver is dispatched,
1189 // skip verification.
1191 if (SetupMode
== NULL
) {
1196 // If platform is in SETUP MODE, skip verification.
1198 if (*SetupMode
== SETUP_MODE
) {
1199 FreePool (SetupMode
);
1203 // Read the Dos header.
1205 if (FileBuffer
== NULL
) {
1206 FreePool (SetupMode
);
1207 return EFI_INVALID_PARAMETER
;
1209 mImageBase
= (UINT8
*) FileBuffer
;
1210 mImageSize
= FileSize
;
1211 DosHdr
= (EFI_IMAGE_DOS_HEADER
*) mImageBase
;
1212 if (DosHdr
->e_magic
== EFI_IMAGE_DOS_SIGNATURE
) {
1214 // DOS image header is present,
1215 // so read the PE header after the DOS image header.
1217 mPeCoffHeaderOffset
= DosHdr
->e_lfanew
;
1219 mPeCoffHeaderOffset
= 0;
1222 // Check PE/COFF image.
1224 mNtHeader
.Pe32
= (EFI_IMAGE_NT_HEADERS32
*) (mImageBase
+ mPeCoffHeaderOffset
);
1225 if (mNtHeader
.Pe32
->Signature
!= EFI_IMAGE_NT_SIGNATURE
) {
1227 // It is not a valid Pe/Coff file.
1229 return EFI_ACCESS_DENIED
;
1232 Magic
= mNtHeader
.Pe32
->OptionalHeader
.Magic
;
1233 if (Magic
== EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC
) {
1237 mSecDataDir
= (EFI_IMAGE_DATA_DIRECTORY
*) &mNtHeader
.Pe32
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
];
1238 } else if (Magic
== EFI_IMAGE_NT_OPTIONAL_HDR64_MAGIC
) {
1240 // Use PE32+ offset.
1242 mSecDataDir
= (EFI_IMAGE_DATA_DIRECTORY
*) &mNtHeader
.Pe32Plus
->OptionalHeader
.DataDirectory
[EFI_IMAGE_DIRECTORY_ENTRY_SECURITY
];
1245 // Invalid header magic number.
1247 Status
= EFI_INVALID_PARAMETER
;
1251 if (mSecDataDir
->VirtualAddress
>= mImageSize
) {
1253 // Sanity check to see if this file is corrupted.
1255 Status
= EFI_INVALID_PARAMETER
;
1259 if (mSecDataDir
->Size
== 0) {
1261 // This image is not signed.
1263 if (!HashPeImage (HASHALG_SHA256
)) {
1267 if (IsSignatureFoundInDatabase (EFI_IMAGE_SECURITY_DATABASE1
, mImageDigest
, &mCertType
, mImageDigestSize
)) {
1269 // Image Hash is in forbidden database (DBX).
1271 Action
= EFI_IMAGE_EXECUTION_AUTH_UNTESTED
;
1272 Status
= EFI_ACCESS_DENIED
;
1276 if (IsSignatureFoundInDatabase (EFI_IMAGE_SECURITY_DATABASE
, mImageDigest
, &mCertType
, mImageDigestSize
)) {
1278 // Image Hash is in allowed database (DB).
1284 // Image Hash is not found in both forbidden and allowed database.
1286 Action
= EFI_IMAGE_EXECUTION_AUTH_UNTESTED
;
1287 Status
= EFI_ACCESS_DENIED
;
1292 // Verify signature of executables.
1294 WinCertificate
= (WIN_CERTIFICATE
*) (mImageBase
+ mSecDataDir
->VirtualAddress
);
1296 switch (WinCertificate
->wCertificateType
) {
1298 case WIN_CERT_TYPE_EFI_GUID
:
1300 // Verify UEFI GUID type.
1302 if (!HashPeImage (HASHALG_SHA256
)) {
1306 VerifyStatus
= VerifyCertUefiGuid ();
1309 case WIN_CERT_TYPE_PKCS_SIGNED_DATA
:
1311 // Verify Pkcs signed data type.
1313 Status
= HashPeImageByType();
1314 if (EFI_ERROR (Status
)) {
1318 VerifyStatus
= VerifyCertPkcsSignedData ();
1321 // For image verification against enrolled certificate(root or intermediate),
1322 // no need to check image's hash in the allowed database.
1324 if (!EFI_ERROR (VerifyStatus
)) {
1325 if (!IsSignatureFoundInDatabase (EFI_IMAGE_SECURITY_DATABASE1
, mImageDigest
, &mCertType
, mImageDigestSize
)) {
1332 Status
= EFI_ACCESS_DENIED
;
1336 // Get image hash value as executable's signature.
1338 SignatureListSize
= sizeof (EFI_SIGNATURE_LIST
) + sizeof (EFI_SIGNATURE_DATA
) - 1 + mImageDigestSize
;
1339 SignatureList
= (EFI_SIGNATURE_LIST
*) AllocateZeroPool (SignatureListSize
);
1340 if (SignatureList
== NULL
) {
1341 Status
= EFI_OUT_OF_RESOURCES
;
1344 SignatureList
->SignatureHeaderSize
= 0;
1345 SignatureList
->SignatureListSize
= (UINT32
) SignatureListSize
;
1346 SignatureList
->SignatureSize
= (UINT32
) mImageDigestSize
;
1347 CopyMem (&SignatureList
->SignatureType
, &mCertType
, sizeof (EFI_GUID
));
1348 Signature
= (EFI_SIGNATURE_DATA
*) ((UINT8
*) SignatureList
+ sizeof (EFI_SIGNATURE_LIST
));
1349 CopyMem (Signature
->SignatureData
, mImageDigest
, mImageDigestSize
);
1351 // Signature database check after verification.
1353 if (EFI_ERROR (VerifyStatus
)) {
1355 // Verification failure.
1357 if (!IsSignatureFoundInDatabase (EFI_IMAGE_SECURITY_DATABASE1
, mImageDigest
, &mCertType
, mImageDigestSize
) &&
1358 IsSignatureFoundInDatabase (EFI_IMAGE_SECURITY_DATABASE
, mImageDigest
, &mCertType
, mImageDigestSize
)) {
1360 // Verification fail, Image Hash is not in forbidden database (DBX),
1361 // and Image Hash is in allowed database (DB).
1363 Status
= EFI_SUCCESS
;
1365 Action
= EFI_IMAGE_EXECUTION_AUTH_SIG_FAILED
;
1366 Status
= EFI_ACCESS_DENIED
;
1368 } else if (IsSignatureFoundInDatabase (EFI_IMAGE_SECURITY_DATABASE1
, Signature
->SignatureData
, &mCertType
, mImageDigestSize
)) {
1370 // Executable signature verification passes, but is found in forbidden signature database.
1372 Action
= EFI_IMAGE_EXECUTION_AUTH_SIG_FOUND
;
1373 Status
= EFI_ACCESS_DENIED
;
1374 } else if (IsSignatureFoundInDatabase (EFI_IMAGE_SECURITY_DATABASE
, Signature
->SignatureData
, &mCertType
, mImageDigestSize
)) {
1376 // Executable signature is found in authorized signature database.
1378 Status
= EFI_SUCCESS
;
1381 // Executable signature verification passes, but cannot be found in authorized signature database.
1382 // Get platform policy to determine the action.
1384 Action
= EFI_IMAGE_EXECUTION_AUTH_SIG_PASSED
;
1385 Status
= ImageAuthorization (Policy
);
1389 if (Status
!= EFI_SUCCESS
) {
1391 // Policy decides to defer or reject the image; add its information in image executable information table.
1393 AddImageExeInfo (Action
, NULL
, File
, SignatureList
, SignatureListSize
);
1396 if (SignatureList
!= NULL
) {
1397 FreePool (SignatureList
);
1400 FreePool (SetupMode
);
1406 When VariableWriteArchProtocol install, create "SecureBoot" variable.
1408 @param[in] Event Event whose notification function is being invoked.
1409 @param[in] Context Pointer to the notification function's context.
1414 VariableWriteCallBack (
1419 UINT8 SecureBootMode
;
1420 UINT8
*SecureBootModePtr
;
1422 VOID
*ProtocolPointer
;
1424 Status
= gBS
->LocateProtocol (&gEfiVariableWriteArchProtocolGuid
, NULL
, &ProtocolPointer
);
1425 if (EFI_ERROR (Status
)) {
1430 // Check whether "SecureBoot" variable exists.
1431 // If this library is built-in, it means firmware has capability to perform
1432 // driver signing verification.
1434 SecureBootModePtr
= GetEfiGlobalVariable (EFI_SECURE_BOOT_MODE_NAME
);
1435 if (SecureBootModePtr
== NULL
) {
1436 SecureBootMode
= SECURE_BOOT_MODE_DISABLE
;
1438 // Authenticated variable driver will update "SecureBoot" depending on SetupMode variable.
1441 EFI_SECURE_BOOT_MODE_NAME
,
1442 &gEfiGlobalVariableGuid
,
1443 EFI_VARIABLE_BOOTSERVICE_ACCESS
| EFI_VARIABLE_RUNTIME_ACCESS
| EFI_VARIABLE_NON_VOLATILE
,
1448 FreePool (SecureBootModePtr
);
1453 Register security measurement handler.
1455 @param ImageHandle ImageHandle of the loaded driver.
1456 @param SystemTable Pointer to the EFI System Table.
1458 @retval EFI_SUCCESS The handlers were registered successfully.
1462 DxeImageVerificationLibConstructor (
1463 IN EFI_HANDLE ImageHandle
,
1464 IN EFI_SYSTEM_TABLE
*SystemTable
1470 // Register callback function upon VariableWriteArchProtocol.
1472 EfiCreateProtocolNotifyEvent (
1473 &gEfiVariableWriteArchProtocolGuid
,
1475 VariableWriteCallBack
,
1480 return RegisterSecurityHandler (
1481 DxeImageVerificationHandler
,
1482 EFI_AUTH_OPERATION_VERIFY_IMAGE
| EFI_AUTH_OPERATION_IMAGE_REQUIRED