SignedCapsulePkg/Include/Library/EdkiiSystemCapsuleLib.h

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