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 - 2011, 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 with RestoreAllLockBoxInPlace()
  66 //
  67 #define LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE  BIT0
  68
  69 /**
  70   This function will update confidential information to lockbox.
  71
  72   @param Guid   the guid to identify the original confidential information
  73   @param Offset the offset of the original confidential information
  74   @param Buffer the address of the updated confidential information
  75   @param Length the length of the updated confidential information
  76
  77   @retval RETURN_SUCCESS            the information is saved successfully.
  78   @retval RETURN_INVALID_PARAMETER  the Guid is NULL, or Buffer is NULL, or Length is 0.
  79   @retval RETURN_NOT_FOUND          the requested GUID not found.
  80   @retval RETURN_BUFFER_TOO_SMALL   the original buffer to too small to hold new information.
  81   @retval RETURN_ACCESS_DENIED      it is too late to invoke this interface
  82   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
  83   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
  84 **/
  85 RETURN_STATUS
  86 EFIAPI
  87 UpdateLockBox (
  88   IN  GUID                        *Guid,
  89   IN  UINTN                       Offset,
  90   IN  VOID                        *Buffer,
  91   IN  UINTN                       Length
  92   );
  93
  94 /**
  95   This function will restore confidential information from lockbox.
  96
  97   @param Guid   the guid to identify the confidential information
  98   @param Buffer the address of the restored confidential information
  99                 NULL means restored to original address, Length MUST be NULL at same time.
 100   @param Length the length of the restored confidential information
 101
 102   @retval RETURN_SUCCESS            the information is restored successfully.
 103   @retval RETURN_INVALID_PARAMETER  the Guid is NULL, or one of Buffer and Length is NULL.
 104   @retval RETURN_WRITE_PROTECTED    Buffer and Length are NULL, but the LockBox has no
 105                                     LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE attribute.
 106   @retval RETURN_BUFFER_TOO_SMALL   the Length is too small to hold the confidential information.
 107   @retval RETURN_NOT_FOUND          the requested GUID not found.
 108   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
 109   @retval RETURN_ACCESS_DENIED      not allow to restore to the address
 110   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
 111 **/
 112 RETURN_STATUS
 113 EFIAPI
 114 RestoreLockBox (
 115   IN  GUID                        *Guid,
 116   IN  VOID                        *Buffer, OPTIONAL
 117   IN  OUT UINTN                   *Length  OPTIONAL
 118   );
 119
 120 /**
 121   This function will restore confidential information from all lockbox which have RestoreInPlace attribute.
 122
 123   @retval RETURN_SUCCESS            the information is restored successfully.
 124   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
 125   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
 126 **/
 127 RETURN_STATUS
 128 EFIAPI
 129 RestoreAllLockBoxInPlace (
 130   VOID
 131   );
 132
 133 #endif