MdeModulePkg/Include/Library/LockBoxLib.h

   1 /** @file
   2   This library is only intended to be used by DXE modules that need save
   3   confidential information to LockBox and get it by PEI modules in S3 phase.
   4
   5 Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR>
   6
   7 This program and the accompanying materials
   8 are licensed and made available under the terms and conditions
   9 of the BSD License which accompanies this distribution.  The
  10 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 **/
  17
  18 #ifndef _LOCK_BOX_LIB_H_
  19 #define _LOCK_BOX_LIB_H_
  20
  21 /**
  22   This function will save confidential information to lockbox.
  23
  24   @param Guid       the guid to identify the confidential information
  25   @param Buffer     the address of the confidential information
  26   @param Length     the length of the confidential information
  27
  28   @retval RETURN_SUCCESS            the information is saved successfully.
  29   @retval RETURN_INVALID_PARAMETER  the Guid is NULL, or Buffer is NULL, or Length is 0
  30   @retval RETURN_ALREADY_STARTED    the requested GUID already exist.
  31   @retval RETURN_OUT_OF_RESOURCES   no enough resource to save the information.
  32   @retval RETURN_ACCESS_DENIED      it is too late to invoke this interface
  33   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
  34   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
  35 **/
  36 RETURN_STATUS
  37 EFIAPI
  38 SaveLockBox (
  39   IN  GUID                        *Guid,
  40   IN  VOID                        *Buffer,
  41   IN  UINTN                       Length
  42   );
  43
  44 /**
  45   This function will set lockbox attributes.
  46
  47   @param Guid       the guid to identify the confidential information
  48   @param Attributes the attributes of the lockbox
  49
  50   @retval RETURN_SUCCESS            the information is saved successfully.
  51   @retval RETURN_INVALID_PARAMETER  attributes is invalid.
  52   @retval RETURN_NOT_FOUND          the requested GUID not found.
  53   @retval RETURN_ACCESS_DENIED      it is too late to invoke this interface
  54   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
  55   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
  56 **/
  57 RETURN_STATUS
  58 EFIAPI
  59 SetLockBoxAttributes (
  60   IN  GUID                        *Guid,
  61   IN  UINT64                      Attributes
  62   );
  63
  64 //
  65 // With this flag, this LockBox can be restored to this Buffer
  66 // with RestoreAllLockBoxInPlace()
  67 //
  68 #define LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE     BIT0
  69 //
  70 // With this flag, this LockBox can be restored in S3 resume only.
  71 // This LockBox can not be restored after SmmReadyToLock in normal boot
  72 // and after EndOfS3Resume in S3 resume.
  73 // It can not be set together with LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE.
  74 //
  75 #define LOCK_BOX_ATTRIBUTE_RESTORE_IN_S3_ONLY   BIT1
  76
  77 /**
  78   This function will update confidential information to lockbox.
  79
  80   @param Guid   the guid to identify the original confidential information
  81   @param Offset the offset of the original confidential information
  82   @param Buffer the address of the updated confidential information
  83   @param Length the length of the updated confidential information
  84
  85   @retval RETURN_SUCCESS            the information is saved successfully.
  86   @retval RETURN_INVALID_PARAMETER  the Guid is NULL, or Buffer is NULL, or Length is 0.
  87   @retval RETURN_NOT_FOUND          the requested GUID not found.
  88   @retval RETURN_BUFFER_TOO_SMALL   the original buffer to too small to hold new information.
  89   @retval RETURN_ACCESS_DENIED      it is too late to invoke this interface
  90   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
  91   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
  92 **/
  93 RETURN_STATUS
  94 EFIAPI
  95 UpdateLockBox (
  96   IN  GUID                        *Guid,
  97   IN  UINTN                       Offset,
  98   IN  VOID                        *Buffer,
  99   IN  UINTN                       Length
 100   );
 101
 102 /**
 103   This function will restore confidential information from lockbox.
 104
 105   @param Guid   the guid to identify the confidential information
 106   @param Buffer the address of the restored confidential information
 107                 NULL means restored to original address, Length MUST be NULL at same time.
 108   @param Length the length of the restored confidential information
 109
 110   @retval RETURN_SUCCESS            the information is restored successfully.
 111   @retval RETURN_INVALID_PARAMETER  the Guid is NULL, or one of Buffer and Length is NULL.
 112   @retval RETURN_WRITE_PROTECTED    Buffer and Length are NULL, but the LockBox has no
 113                                     LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE attribute.
 114   @retval RETURN_BUFFER_TOO_SMALL   the Length is too small to hold the confidential information.
 115   @retval RETURN_NOT_FOUND          the requested GUID not found.
 116   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
 117   @retval RETURN_ACCESS_DENIED      not allow to restore to the address
 118   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
 119 **/
 120 RETURN_STATUS
 121 EFIAPI
 122 RestoreLockBox (
 123   IN  GUID                        *Guid,
 124   IN  VOID                        *Buffer, OPTIONAL
 125   IN  OUT UINTN                   *Length  OPTIONAL
 126   );
 127
 128 /**
 129   This function will restore confidential information from all lockbox which have RestoreInPlace attribute.
 130
 131   @retval RETURN_SUCCESS            the information is restored successfully.
 132   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
 133   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
 134 **/
 135 RETURN_STATUS
 136 EFIAPI
 137 RestoreAllLockBoxInPlace (
 138   VOID
 139   );
 140
 141 #endif