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