MdeModulePkg/Library/VariablePolicyHelperLib/VariablePolicyHelperLib.c

/** @file -- VariablePolicyHelperLib.c
This library contains helper functions for marshalling and registering
new policies with the VariablePolicy infrastructure.

This library is currently written against VariablePolicy revision 0x00010000.

Copyright (c) Microsoft Corporation.
SPDX-License-Identifier: BSD-2-Clause-Patent

**/

#include <Uefi.h>

#include <Library/BaseLib.h>
#include <Library/DebugLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/MemoryAllocationLib.h>

#include <Protocol/VariablePolicy.h>

/**
  This internal helper function populates the header structure,
  all common fields, and takes care of fix-ups.

  NOTE: Only use this internally. Assumes correctly-sized buffers.

  @param[out] EntPtr      Pointer to the buffer to be populated.
  @param[in]  Namespace   Pointer to an EFI_GUID for the target variable namespace that this policy will protect.
  @param[in]  MinSize     MinSize for the VariablePolicy.
  @param[in]  MaxSize     MaxSize for the VariablePolicy.
  @param[in]  AttributesMustHave    AttributesMustHave for the VariablePolicy.
  @param[in]  AttributesCantHave    AttributesCantHave for the VariablePolicy.
  @param[in]  LockPolicyType        LockPolicyType for the VariablePolicy.

**/
STATIC
VOID
PopulateCommonData (
  OUT VARIABLE_POLICY_ENTRY   *EntPtr,
  IN CONST  EFI_GUID          *Namespace,
  IN        UINT32            MinSize,
  IN        UINT32            MaxSize,
  IN        UINT32            AttributesMustHave,
  IN        UINT32            AttributesCantHave,
  IN        UINT8             LockPolicyType
  )
{
  EntPtr->Version             = VARIABLE_POLICY_ENTRY_REVISION;
  CopyGuid( &EntPtr->Namespace, Namespace );
  EntPtr->MinSize             = MinSize;
  EntPtr->MaxSize             = MaxSize;
  EntPtr->AttributesMustHave  = AttributesMustHave;
  EntPtr->AttributesCantHave  = AttributesCantHave;
  EntPtr->LockPolicyType      = LockPolicyType;

  // NOTE: As a heler, fix up MaxSize for compatibility with the old model.
  if (EntPtr->MaxSize == 0) {
    EntPtr->MaxSize = VARIABLE_POLICY_NO_MAX_SIZE;
  }

  return;
}


/**
  This helper function will allocate and populate a new VariablePolicy
  structure for a policy that does not contain any sub-structures (such as
  VARIABLE_LOCK_ON_VAR_STATE_POLICY).

  NOTE: Caller will need to free structure once finished.

  @param[in]  Namespace   Pointer to an EFI_GUID for the target variable namespace that this policy will protect.
  @param[in]  Name        [Optional] If provided, a pointer to the CHAR16 array for the target variable name.
                          Otherwise, will create a policy that targets an entire namespace.
  @param[in]  MinSize     MinSize for the VariablePolicy.
  @param[in]  MaxSize     MaxSize for the VariablePolicy.
  @param[in]  AttributesMustHave    AttributesMustHave for the VariablePolicy.
  @param[in]  AttributesCantHave    AttributesCantHave for the VariablePolicy.
  @param[in]  LockPolicyType        LockPolicyType for the VariablePolicy.
  @param[out] NewEntry    If successful, will be set to a pointer to the allocated buffer containing the
                          new policy.

  @retval     EFI_SUCCESS             Operation completed successfully and structure is populated.
  @retval     EFI_INVALID_PARAMETER   Namespace is NULL.
  @retval     EFI_INVALID_PARAMETER   LockPolicyType is invalid for a basic structure.
  @retval     EFI_BUFFER_TOO_SMALL    Finished structure would not fit in UINT16 size.
  @retval     EFI_OUT_OF_RESOURCES    Could not allocate sufficient space for structure.

**/
EFI_STATUS
EFIAPI
CreateBasicVariablePolicy (
  IN CONST  EFI_GUID          *Namespace,
  IN CONST  CHAR16            *Name OPTIONAL,
  IN        UINT32            MinSize,
  IN        UINT32            MaxSize,
  IN        UINT32            AttributesMustHave,
  IN        UINT32            AttributesCantHave,
  IN        UINT8             LockPolicyType,
  OUT VARIABLE_POLICY_ENTRY   **NewEntry
  )
{
  UINTN                   TotalSize;
  UINTN                   NameSize;
  VARIABLE_POLICY_ENTRY   *EntPtr;
  CHAR16                  *CopyName;

  // Check some initial invalid parameters for this function.
  if (Namespace == NULL || NewEntry == NULL) {
    return EFI_INVALID_PARAMETER;
  }
  if (LockPolicyType != VARIABLE_POLICY_TYPE_NO_LOCK &&
      LockPolicyType != VARIABLE_POLICY_TYPE_LOCK_NOW &&
      LockPolicyType != VARIABLE_POLICY_TYPE_LOCK_ON_CREATE) {
    return EFI_INVALID_PARAMETER;
  }

  //
  // Set NameSize to suppress incorrect compiler/analyzer warnings
  //
  NameSize  = 0;

  // Now we've gotta determine the total size of the buffer required for
  // the VariablePolicy structure.
  TotalSize = sizeof( VARIABLE_POLICY_ENTRY );
  if (Name != NULL) {
    NameSize = StrnSizeS( Name, MAX_UINT16 );
    TotalSize += NameSize;
  }
  // Make sure the size fits within a VARIABLE_POLICY_ENTRY.Size.
  ASSERT( TotalSize <= MAX_UINT16 );
  if (TotalSize > MAX_UINT16) {
    return EFI_BUFFER_TOO_SMALL;
  }

  // Allocate a buffer to hold all the data. We're on the home stretch.
  *NewEntry = AllocatePool( TotalSize );
  if (*NewEntry == NULL) {
    return EFI_OUT_OF_RESOURCES;
  }

  // If we're still here, we're basically done.
  // Copy the data and GET... OUT....
  EntPtr = *NewEntry;
  PopulateCommonData ( EntPtr,
                       Namespace,
                       MinSize,
                       MaxSize,
                       AttributesMustHave,
                       AttributesCantHave,
                       LockPolicyType );
  EntPtr->Size                = (UINT16)TotalSize;      // This is safe because we've already checked.
  EntPtr->OffsetToName        = sizeof(VARIABLE_POLICY_ENTRY);
  if (Name != NULL) {
    CopyName = (CHAR16*)((UINT8*)EntPtr + EntPtr->OffsetToName);
    CopyMem( CopyName, Name, NameSize );
  }

  return EFI_SUCCESS;
}


/**
  This helper function will allocate and populate a new VariablePolicy
  structure for a policy with a lock type of VARIABLE_POLICY_TYPE_LOCK_ON_VAR_STATE.

  NOTE: Caller will need to free structure once finished.

  @param[in]  Namespace   Pointer to an EFI_GUID for the target variable namespace that this policy will protect.
  @param[in]  Name        [Optional] If provided, a pointer to the CHAR16 array for the target variable name.
                          Otherwise, will create a policy that targets an entire namespace.
  @param[in]  MinSize     MinSize for the VariablePolicy.
  @param[in]  MaxSize     MaxSize for the VariablePolicy.
  @param[in]  AttributesMustHave    AttributesMustHave for the VariablePolicy.
  @param[in]  AttributesCantHave    AttributesCantHave for the VariablePolicy.
  @param[in]  VarStateNamespace     Pointer to the EFI_GUID for the VARIABLE_LOCK_ON_VAR_STATE_POLICY.Namespace.
  @param[in]  VarStateValue         Value for the VARIABLE_LOCK_ON_VAR_STATE_POLICY.Value.
  @param[in]  VarStateName          Pointer to the CHAR16 array for the VARIABLE_LOCK_ON_VAR_STATE_POLICY.Name.
  @param[out] NewEntry    If successful, will be set to a pointer to the allocated buffer containing the
                          new policy.

  @retval     EFI_SUCCESS             Operation completed successfully and structure is populated.
  @retval     EFI_INVALID_PARAMETER   Namespace, VarStateNamespace, VarStateName is NULL.
  @retval     EFI_BUFFER_TOO_SMALL    Finished structure would not fit in UINT16 size.
  @retval     EFI_OUT_OF_RESOURCES    Could not allocate sufficient space for structure.

**/
EFI_STATUS
EFIAPI
CreateVarStateVariablePolicy (
  IN CONST  EFI_GUID          *Namespace,
  IN CONST  CHAR16            *Name OPTIONAL,
  IN        UINT32            MinSize,
  IN        UINT32            MaxSize,
  IN        UINT32            AttributesMustHave,
  IN        UINT32            AttributesCantHave,
  IN CONST  EFI_GUID          *VarStateNamespace,
  IN        UINT8             VarStateValue,
  IN CONST  CHAR16            *VarStateName,
  OUT VARIABLE_POLICY_ENTRY   **NewEntry
  )
{
  UINTN                   TotalSize;
  UINTN                   NameSize;
  UINTN                   VarStateNameSize;
  VARIABLE_POLICY_ENTRY   *EntPtr;
  CHAR16                  *CopyName;
  VARIABLE_LOCK_ON_VAR_STATE_POLICY *CopyPolicy;

  // Check some initial invalid parameters for this function.
  if (Namespace == NULL || VarStateNamespace == NULL ||
      VarStateName == NULL || NewEntry == NULL) {
    return EFI_INVALID_PARAMETER;
  }

  // Now we've gotta determine the total size of the buffer required for
  // the VariablePolicy structure.
  VarStateNameSize = StrnSizeS( VarStateName, MAX_UINT16 );
  TotalSize = sizeof( VARIABLE_POLICY_ENTRY ) +
                sizeof(VARIABLE_LOCK_ON_VAR_STATE_POLICY) +
                VarStateNameSize;
  if (Name != NULL) {
    NameSize = StrnSizeS( Name, MAX_UINT16 );
    TotalSize += NameSize;
  }
  // Make sure the size fits within a VARIABLE_POLICY_ENTRY.Size.
  ASSERT( TotalSize <= MAX_UINT16 );
  if (TotalSize > MAX_UINT16) {
    return EFI_BUFFER_TOO_SMALL;
  }

  // Allocate a buffer to hold all the data. We're on the home stretch.
  *NewEntry = AllocatePool( TotalSize );
  if (*NewEntry == NULL) {
    return EFI_OUT_OF_RESOURCES;
  }

  // If we're still here, we're basically done.
  // Copy the data and GET... OUT....
  EntPtr = *NewEntry;
  PopulateCommonData ( EntPtr,
                       Namespace,
                       MinSize,
                       MaxSize,
                       AttributesMustHave,
                       AttributesCantHave,
                       VARIABLE_POLICY_TYPE_LOCK_ON_VAR_STATE );
  EntPtr->Size                = (UINT16)TotalSize;      // This is safe because we've already checked.
  EntPtr->OffsetToName        = sizeof(VARIABLE_POLICY_ENTRY) +
                                sizeof(VARIABLE_LOCK_ON_VAR_STATE_POLICY) +
                                (UINT16)VarStateNameSize;

  CopyPolicy = (VARIABLE_LOCK_ON_VAR_STATE_POLICY*)((UINT8*)EntPtr + sizeof(VARIABLE_POLICY_ENTRY));
  CopyName = (CHAR16*)((UINT8*)CopyPolicy + sizeof(VARIABLE_LOCK_ON_VAR_STATE_POLICY));
  CopyGuid( &CopyPolicy->Namespace, VarStateNamespace );
  CopyPolicy->Value = VarStateValue;
  CopyMem( CopyName, VarStateName, VarStateNameSize );

  if (Name != NULL) {
    CopyName = (CHAR16*)((UINT8*)EntPtr + EntPtr->OffsetToName);
    CopyMem( CopyName, Name, NameSize );
  }

  return EFI_SUCCESS;
}


/**
  This helper function does everything that CreateBasicVariablePolicy() does, but also
  uses the passed in protocol to register the policy with the infrastructure.
  Does not return a buffer, does not require the caller to free anything.

  @param[in]  VariablePolicy  Pointer to a valid instance of the VariablePolicy protocol.
  @param[in]  Namespace   Pointer to an EFI_GUID for the target variable namespace that this policy will protect.
  @param[in]  Name        [Optional] If provided, a pointer to the CHAR16 array for the target variable name.
                          Otherwise, will create a policy that targets an entire namespace.
  @param[in]  MinSize     MinSize for the VariablePolicy.
  @param[in]  MaxSize     MaxSize for the VariablePolicy.
  @param[in]  AttributesMustHave    AttributesMustHave for the VariablePolicy.
  @param[in]  AttributesCantHave    AttributesCantHave for the VariablePolicy.
  @param[in]  LockPolicyType        LockPolicyType for the VariablePolicy.

  @retval     EFI_INVALID_PARAMETER VariablePolicy pointer is NULL.
  @retval     EFI_STATUS            Status returned by CreateBasicVariablePolicy() or RegisterVariablePolicy().

**/
EFI_STATUS
EFIAPI
RegisterBasicVariablePolicy (
  IN        EDKII_VARIABLE_POLICY_PROTOCOL  *VariablePolicy,
  IN CONST  EFI_GUID                        *Namespace,
  IN CONST  CHAR16                          *Name OPTIONAL,
  IN        UINT32                          MinSize,
  IN        UINT32                          MaxSize,
  IN        UINT32                          AttributesMustHave,
  IN        UINT32                          AttributesCantHave,
  IN        UINT8                           LockPolicyType
  )
{
  VARIABLE_POLICY_ENTRY   *NewEntry;
  EFI_STATUS              Status;

  // Check the simple things.
  if (VariablePolicy == NULL) {
    return EFI_INVALID_PARAMETER;
  }

  // Create the new entry and make sure that everything worked.
  NewEntry = NULL;
  Status = CreateBasicVariablePolicy( Namespace,
                                      Name,
                                      MinSize,
                                      MaxSize,
                                      AttributesMustHave,
                                      AttributesCantHave,
                                      LockPolicyType,
                                      &NewEntry );

  // If that was successful, attempt to register the new policy.
  if (!EFI_ERROR( Status )) {
    Status = VariablePolicy->RegisterVariablePolicy( NewEntry );
  }

  // If we allocated the buffer, free the buffer.
  if (NewEntry != NULL) {
    FreePool( NewEntry );
  }

  return Status;
}


/**
  This helper function does everything that CreateBasicVariablePolicy() does, but also
  uses the passed in protocol to register the policy with the infrastructure.
  Does not return a buffer, does not require the caller to free anything.

  @param[in]  VariablePolicy  Pointer to a valid instance of the VariablePolicy protocol.
  @param[in]  Namespace   Pointer to an EFI_GUID for the target variable namespace that this policy will protect.
  @param[in]  Name        [Optional] If provided, a pointer to the CHAR16 array for the target variable name.
                          Otherwise, will create a policy that targets an entire namespace.
  @param[in]  MinSize     MinSize for the VariablePolicy.
  @param[in]  MaxSize     MaxSize for the VariablePolicy.
  @param[in]  AttributesMustHave    AttributesMustHave for the VariablePolicy.
  @param[in]  AttributesCantHave    AttributesCantHave for the VariablePolicy.
  @param[in]  VarStateNamespace     Pointer to the EFI_GUID for the VARIABLE_LOCK_ON_VAR_STATE_POLICY.Namespace.
  @param[in]  VarStateName          Pointer to the CHAR16 array for the VARIABLE_LOCK_ON_VAR_STATE_POLICY.Name.
  @param[in]  VarStateValue         Value for the VARIABLE_LOCK_ON_VAR_STATE_POLICY.Value.

  @retval     EFI_INVALID_PARAMETER VariablePolicy pointer is NULL.
  @retval     EFI_STATUS    Status returned by CreateBasicVariablePolicy() or RegisterVariablePolicy().

**/
EFI_STATUS
EFIAPI
RegisterVarStateVariablePolicy (
  IN        EDKII_VARIABLE_POLICY_PROTOCOL  *VariablePolicy,
  IN CONST  EFI_GUID                        *Namespace,
  IN CONST  CHAR16                          *Name OPTIONAL,
  IN        UINT32                          MinSize,
  IN        UINT32                          MaxSize,
  IN        UINT32                          AttributesMustHave,
  IN        UINT32                          AttributesCantHave,
  IN CONST  EFI_GUID                        *VarStateNamespace,
  IN CONST  CHAR16                          *VarStateName,
  IN        UINT8                           VarStateValue
  )
{
  VARIABLE_POLICY_ENTRY   *NewEntry;
  EFI_STATUS              Status;

  // Check the simple things.
  if (VariablePolicy == NULL) {
    return EFI_INVALID_PARAMETER;
  }

  // Create the new entry and make sure that everything worked.
  NewEntry = NULL;
  Status = CreateVarStateVariablePolicy( Namespace,
                                         Name,
                                         MinSize,
                                         MaxSize,
                                         AttributesMustHave,
                                         AttributesCantHave,
                                         VarStateNamespace,
                                         VarStateValue,
                                         VarStateName,
                                         &NewEntry );

  // If that was successful, attempt to register the new policy.
  if (!EFI_ERROR( Status )) {
    Status = VariablePolicy->RegisterVariablePolicy( NewEntry );
  }

  // If we allocated the buffer, free the buffer.
  if (NewEntry != NULL) {
    FreePool( NewEntry );
  }

  return Status;
}