1 /** @file 2 This file declares GUIDed section extraction protocol. 3 4 This interface provides a means of decoding a GUID defined encapsulation 5 section. There may be multiple different GUIDs associated with the GUIDed 6 section extraction protocol. That is, all instances of the GUIDed section 7 extraction protocol must have the same interface structure. 8 9 @par Revision Reference: PI 10 Version 1.00. 11 12 Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> 13 14 This program and the accompanying materials are licensed and made available 15 under the terms and conditions of the BSD License which accompanies this 16 distribution. The full text of the license may be found at 17 http://opensource.org/licenses/bsd-license.php 18 19 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 20 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 21 22 **/ 23 24 #ifndef __EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL_H__ 25 #define __EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL_H__ 26 27 // 28 // Forward reference for pure ANSI compatability 29 30 typedef struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL; 31 32 33 /** 34 The ExtractSection() function processes the input section and 35 allocates a buffer from the pool in which it returns the section 36 contents. If the section being extracted contains 37 authentication information (the section's 38 GuidedSectionHeader.Attributes field has the 39 EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values 40 returned in AuthenticationStatus must reflect the results of 41 the authentication operation. Depending on the algorithm and 42 size of the encapsulated data, the time that is required to do 43 a full authentication may be prohibitively long for some 44 classes of systems. To indicate this, use 45 EFI_SECURITY_POLICY_PROTOCOL_GUID, which may be published by 46 the security policy driver (see the Platform Initialization 47 Driver Execution Environment Core Interface Specification for 48 more details and the GUID definition). If the 49 EFI_SECURITY_POLICY_PROTOCOL_GUID exists in the handle 50 database, then, if possible, full authentication should be 51 skipped and the section contents simply returned in the 52 OutputBuffer. In this case, the 53 EFI_AUTH_STATUS_PLATFORM_OVERRIDE bit AuthenticationStatus 54 must be set on return. ExtractSection() is callable only from 55 TPL_NOTIFY and below. Behavior of ExtractSection() at any 56 EFI_TPL above TPL_NOTIFY is undefined. Type EFI_TPL is 57 defined in RaiseTPL() in the UEFI 2.0 specification. 58 59 60 @param This Indicates the 61 EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance. 62 63 @param InputSection Buffer containing the input GUIDed section 64 to be processed. OutputBuffer OutputBuffer 65 is allocated from boot services pool 66 memory and contains the new section 67 stream. The caller is responsible for 68 freeing this buffer. 69 70 @param OutputSize A pointer to a caller-allocated UINTN in 71 which the size of OutputBuffer allocation 72 is stored. If the function returns 73 anything other than EFI_SUCCESS, the value 74 of OutputSize is undefined. 75 76 @param AuthenticationStatus A pointer to a caller-allocated 77 UINT32 that indicates the 78 authentication status of the 79 output buffer. If the input 80 section's 81 GuidedSectionHeader.Attributes 82 field has the 83 EFI_GUIDED_SECTION_AUTH_STATUS_VAL 84 bit as clear, AuthenticationStatus 85 must return zero. Both local bits 86 (19:16) and aggregate bits (3:0) 87 in AuthenticationStatus are 88 returned by ExtractSection(). 89 These bits reflect the status of 90 the extraction operation. The bit 91 pattern in both regions must be 92 the same, as the local and 93 aggregate authentication statuses 94 have equivalent meaning at this 95 level. If the function returns 96 anything other than EFI_SUCCESS, 97 the value of AuthenticationStatus 98 is undefined. 99 100 101 @retval EFI_SUCCESS The InputSection was successfully 102 processed and the section contents were 103 returned. 104 105 @retval EFI_OUT_OF_RESOURCES The system has insufficient 106 resources to process the 107 request. 108 109 @retval EFI_INVALID_PARAMETER The GUID in InputSection does 110 not match this instance of the 111 GUIDed Section Extraction 112 Protocol. 113 114 **/ 115 typedef 116 EFI_STATUS 117 (EFIAPI *EFI_EXTRACT_GUIDED_SECTION)( 118 IN CONST EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL *This, 119 IN CONST VOID *InputSection, 120 OUT VOID **OutputBuffer, 121 OUT UINTN *OutputSize, 122 OUT UINT32 *AuthenticationStatus 123 ); 124 125 126 /** 127 128 Takes the GUIDed section as input and produces the section 129 stream data. See the ExtractSection() function description. 130 131 **/ 132 struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL { 133 EFI_EXTRACT_GUIDED_SECTION ExtractSection; 134 }; 135 136 // 137 // Protocol GUID definition. Each GUIDed section extraction protocol has the 138 // same interface but with different GUID. All the GUIDs is defined here. 139 // May add multiple GUIDs here. 140 // 141 #define EFI_CRC32_GUIDED_SECTION_EXTRACTION_PROTOCOL_GUID \ 142 { \ 143 0xFC1BCDB0, 0x7D31, 0x49aa, {0x93, 0x6A, 0xA4, 0x60, 0x0D, 0x9D, 0xD0, 0x83 } \ 144 } 145 146 // 147 // may add other GUID here 148 // 149 extern EFI_GUID gEfiCrc32GuidedSectionExtractionProtocolGuid; 150 151 #endif 152