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