SignedCapsulePkg/Include/Library/EdkiiSystemCapsuleLib.h

   1 /** @file
   2   EDKII System Capsule library.
   3
   4 Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9
  10 #ifndef __EDKII_SYSTEM_CAPSULE_LIB_H__
  11 #define __EDKII_SYSTEM_CAPSULE_LIB_H__
  12
  13 #include <Guid/EdkiiSystemFmpCapsule.h>
  14
  15 /**
  16   Extract ImageFmpInfo from system firmware.
  17
  18   @param[in]  SystemFirmwareImage     The System Firmware image.
  19   @param[in]  SystemFirmwareImageSize The size of the System Firmware image in bytes.
  20   @param[out] ImageFmpInfo            The ImageFmpInfo.
  21   @param[out] ImageFmpInfoSize        The size of the ImageFmpInfo in bytes.
  22
  23   @retval TRUE  The ImageFmpInfo is extracted.
  24   @retval FALSE The ImageFmpInfo is not extracted.
  25 **/
  26 BOOLEAN
  27 EFIAPI
  28 ExtractSystemFirmwareImageFmpInfo (
  29   IN VOID                                      *SystemFirmwareImage,
  30   IN UINTN                                     SystemFirmwareImageSize,
  31   OUT EDKII_SYSTEM_FIRMWARE_IMAGE_DESCRIPTOR   **ImageFmpInfo,
  32   OUT UINTN                                    *ImageFmpInfoSize
  33   );
  34
  35 /**
  36   Extract the driver FV from an authenticated image.
  37
  38   @param[in]  AuthenticatedImage      The authenticated capsule image.
  39   @param[in]  AuthenticatedImageSize  The size of the authenticated capsule image in bytes.
  40   @param[out] DriverFvImage           The driver FV image.
  41   @param[out] DriverFvImageSize       The size of the driver FV image in bytes.
  42
  43   @retval TRUE  The driver Fv is extracted.
  44   @retval FALSE The driver Fv is not extracted.
  45 **/
  46 BOOLEAN
  47 EFIAPI
  48 ExtractDriverFvImage (
  49   IN VOID                         *AuthenticatedImage,
  50   IN UINTN                        AuthenticatedImageSize,
  51   OUT VOID                        **DriverFvImage,
  52   OUT UINTN                       *DriverFvImageSize
  53   );
  54
  55 /**
  56   Extract the config image from an authenticated image.
  57
  58   @param[in]  AuthenticatedImage      The authenticated capsule image.
  59   @param[in]  AuthenticatedImageSize  The size of the authenticated capsule image in bytes.
  60   @param[out] ConfigImage             The config image.
  61   @param[out] ConfigImageSize         The size of the config image in bytes.
  62
  63   @retval TRUE  The config image is extracted.
  64   @retval FALSE The config image is not extracted.
  65 **/
  66 BOOLEAN
  67 EFIAPI
  68 ExtractConfigImage (
  69   IN VOID                         *AuthenticatedImage,
  70   IN UINTN                        AuthenticatedImageSize,
  71   OUT VOID                        **ConfigImage,
  72   OUT UINTN                       *ConfigImageSize
  73   );
  74
  75 /**
  76   Extract the System Firmware image from an authenticated image.
  77
  78   @param[in]  AuthenticatedImage      The authenticated capsule image.
  79   @param[in]  AuthenticatedImageSize  The size of the authenticated capsule image in bytes.
  80   @param[out] SystemFirmwareImage     The System Firmware image.
  81   @param[out] SystemFirmwareImageSize The size of the System Firmware image in bytes.
  82
  83   @retval TRUE  The System Firmware image is extracted.
  84   @retval FALSE The System Firmware image is not extracted.
  85 **/
  86 BOOLEAN
  87 EFIAPI
  88 ExtractSystemFirmwareImage (
  89   IN VOID                         *AuthenticatedImage,
  90   IN UINTN                        AuthenticatedImageSize,
  91   OUT VOID                        **SystemFirmwareImage,
  92   OUT UINTN                       *SystemFirmwareImageSize
  93   );
  94
  95 /**
  96   Extract the authenticated image from an FMP capsule image.
  97
  98   @param[in]  Image                   The FMP capsule image, including EFI_FIRMWARE_IMAGE_AUTHENTICATION.
  99   @param[in]  ImageSize               The size of FMP capsule image in bytes.
 100   @param[out] LastAttemptStatus       The last attempt status, which will be recorded in ESRT and FMP EFI_FIRMWARE_IMAGE_DESCRIPTOR.
 101   @param[out] AuthenticatedImage      The authenticated capsule image, excluding EFI_FIRMWARE_IMAGE_AUTHENTICATION.
 102   @param[out] AuthenticatedImageSize  The size of the authenticated capsule image in bytes.
 103
 104   @retval TRUE  The authenticated image is extracted.
 105   @retval FALSE The authenticated image is not extracted.
 106 **/
 107 BOOLEAN
 108 EFIAPI
 109 ExtractAuthenticatedImage (
 110   IN VOID                         *Image,
 111   IN UINTN                        ImageSize,
 112   OUT UINT32                      *LastAttemptStatus,
 113   OUT VOID                        **AuthenticatedImage,
 114   OUT UINTN                       *AuthenticatedImageSize
 115   );
 116
 117 /**
 118   Authenticated system firmware FMP capsule image.
 119
 120   Caution: This function may receive untrusted input.
 121
 122   @param[in]  Image                   The FMP capsule image, including EFI_FIRMWARE_IMAGE_AUTHENTICATION.
 123   @param[in]  ImageSize               The size of FMP capsule image in bytes.
 124   @param[in]  ForceVersionMatch       TRUE: The version of capsule must be as same as the version of current image.
 125                                       FALSE: The version of capsule must be as same as greater than the lowest
 126                                              supported version of current image.
 127   @param[out] LastAttemptVersion      The last attempt version, which will be recorded in ESRT and FMP EFI_FIRMWARE_IMAGE_DESCRIPTOR.
 128   @param[out] LastAttemptStatus       The last attempt status, which will be recorded in ESRT and FMP EFI_FIRMWARE_IMAGE_DESCRIPTOR.
 129   @param[out] AuthenticatedImage      The authenticated capsule image, excluding EFI_FIRMWARE_IMAGE_AUTHENTICATION.
 130   @param[out] AuthenticatedImageSize  The size of the authenticated capsule image in bytes.
 131
 132   @retval TRUE  Authentication passes and the authenticated image is extracted.
 133   @retval FALSE Authentication fails and the authenticated image is not extracted.
 134 **/
 135 EFI_STATUS
 136 EFIAPI
 137 CapsuleAuthenticateSystemFirmware (
 138   IN VOID                         *Image,
 139   IN UINTN                        ImageSize,
 140   IN BOOLEAN                      ForceVersionMatch,
 141   OUT UINT32                      *LastAttemptVersion,
 142   OUT UINT32                      *LastAttemptStatus,
 143   OUT VOID                        **AuthenticatedImage,
 144   OUT UINTN                       *AuthenticatedImageSize
 145   );
 146
 147 #endif
 148