Add comment for modules which have external input.

[mirror_edk2.git] / SecurityPkg / VariableAuthenticated / RuntimeDxe / Variable.h

diff --git a/SecurityPkg/VariableAuthenticated/RuntimeDxe/Variable.h b/SecurityPkg/VariableAuthenticated/RuntimeDxe/Variable.h
index 6865f0dc719bd10649c423966fad5e114a45ed1e..14a0744a57ed39cdc174c253f5ef0839b0bf225e 100644 (file)
--- a/SecurityPkg/VariableAuthenticated/RuntimeDxe/Variable.h
+++ b/SecurityPkg/VariableAuthenticated/RuntimeDxe/Variable.h
@@ -2,7 +2,7 @@
   The internal header file includes the common header files, defines\r
   internal structure and functions used by Variable modules.\r
 \r
-Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>\r
+Copyright (c) 2009 - 2012, Intel Corporation. All rights reserved.<BR>\r
 This program and the accompanying materials \r
 are licensed and made available under the terms and conditions of the BSD License \r
 which accompanies this distribution.  The full text of the license may be found at \r
@@ -22,6 +22,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Protocol/FirmwareVolumeBlock.h>\r
 #include <Protocol/Variable.h>\r
 #include <Library/PcdLib.h>\r
+#include <Library/HobLib.h>\r
 #include <Library/UefiDriverEntryPoint.h>\r
 #include <Library/DxeServicesTableLib.h>\r
 #include <Library/UefiRuntimeLib.h>\r
@@ -38,6 +39,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Guid/EventGroup.h>\r
 #include <Guid/AuthenticatedVariableFormat.h>\r
 #include <Guid/ImageAuthentication.h>\r
+#include <Guid/SystemNvDataGuid.h>\r
+#include <Guid/HardwareErrorVariable.h>\r
 \r
 #define VARIABLE_RECLAIM_THRESHOLD (1024)\r
 \r
@@ -46,6 +49,13 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 ///\r
 #define ISO_639_2_ENTRY_SIZE    3\r
 \r
+typedef enum {\r
+  VariableStoreTypeVolatile,\r
+  VariableStoreTypeHob,\r
+  VariableStoreTypeNv,\r
+  VariableStoreTypeMax\r
+} VARIABLE_STORE_TYPE;\r
+\r
 typedef struct {\r
   VARIABLE_HEADER *CurrPtr;\r
   VARIABLE_HEADER *EndPtr;\r
@@ -54,6 +64,7 @@ typedef struct {
 } VARIABLE_POINTER_TRACK;\r
 \r
 typedef struct {\r
+  EFI_PHYSICAL_ADDRESS  HobVariableBase;\r
   EFI_PHYSICAL_ADDRESS  VolatileVariableBase;\r
   EFI_PHYSICAL_ADDRESS  NonVolatileVariableBase;\r
   EFI_LOCK              VariableServicesLock;\r
@@ -110,20 +121,24 @@ FtwVariableSpace (
   This code finds variable in storage blocks of volatile and non-volatile storage areas.\r
   If VariableName is an empty string, then we just return the first\r
   qualified variable without comparing VariableName and VendorGuid.\r
-  Otherwise, VariableName and VendorGuid are compared.\r
+  If IgnoreRtCheck is TRUE, then we ignore the EFI_VARIABLE_RUNTIME_ACCESS attribute check\r
+  at runtime when searching existing variable, only VariableName and VendorGuid are compared.\r
+  Otherwise, variables without EFI_VARIABLE_RUNTIME_ACCESS are not visible at runtime.\r
 \r
-  @param  VariableName                Name of the variable to be found.\r
-  @param  VendorGuid                  Vendor GUID to be found.\r
-  @param  PtrTrack                    VARIABLE_POINTER_TRACK structure for output,\r
+  @param[in]   VariableName           Name of the variable to be found.\r
+  @param[in]   VendorGuid             Vendor GUID to be found.\r
+  @param[out]  PtrTrack               VARIABLE_POINTER_TRACK structure for output,\r
                                       including the range searched and the target position.\r
-  @param  Global                      Pointer to VARIABLE_GLOBAL structure, including\r
+  @param[in]   Global                 Pointer to VARIABLE_GLOBAL structure, including\r
                                       base of volatile variable storage area, base of\r
                                       NV variable storage area, and a lock.\r
+  @param[in]   IgnoreRtCheck          Ignore EFI_VARIABLE_RUNTIME_ACCESS attribute\r
+                                      check at runtime when searching variable.\r
 \r
   @retval EFI_INVALID_PARAMETER       If VariableName is not an empty string, while\r
                                       VendorGuid is NULL.\r
   @retval EFI_SUCCESS                 Variable successfully found.\r
-  @retval EFI_INVALID_PARAMETER       Variable not found.\r
+  @retval EFI_NOT_FOUND               Variable not found\r
 \r
 **/\r
 EFI_STATUS\r
@@ -131,7 +146,8 @@ FindVariable (
   IN  CHAR16                  *VariableName,\r
   IN  EFI_GUID                *VendorGuid,\r
   OUT VARIABLE_POINTER_TRACK  *PtrTrack,\r
-  IN  VARIABLE_GLOBAL         *Global\r
+  IN  VARIABLE_GLOBAL         *Global,\r
+  IN  BOOLEAN                 IgnoreRtCheck\r
   );\r
 \r
 /**\r
@@ -386,6 +402,10 @@ GetFvbInfoByAddress (
 \r
   This code finds variable in storage blocks (Volatile or Non-Volatile).\r
 \r
+  Caution: This function may receive untrusted input.\r
+  This function may be invoked in SMM mode, and datasize and data are external input.\r
+  This function will do basic validation, before parse the data.\r
+\r
   @param VariableName               Name of Variable to be found.\r
   @param VendorGuid                 Variable vendor GUID.\r
   @param Attributes                 Attribute value of the variable found.\r
@@ -413,6 +433,9 @@ VariableServiceGetVariable (
 \r
   This code Finds the Next available variable.\r
 \r
+  Caution: This function may receive untrusted input.\r
+  This function may be invoked in SMM mode. This function will do basic validation, before parse the data.\r
+\r
   @param VariableNameSize           Size of the variable name.\r
   @param VariableName               Pointer to variable name.\r
   @param VendorGuid                 Variable Vendor Guid.\r
@@ -435,6 +458,13 @@ VariableServiceGetNextVariableName (
 \r
   This code sets variable in storage blocks (Volatile or Non-Volatile).\r
 \r
+  Caution: This function may receive untrusted input.\r
+  This function may be invoked in SMM mode, and datasize and data are external input.\r
+  This function will do basic validation, before parse the data.\r
+  This function will parse the authentication carefully to avoid security issues, like\r
+  buffer overflow, integer overflow.\r
+  This function will check attribute carefully to avoid authentication bypass.\r
+\r
   @param VariableName                     Name of Variable to be found.\r
   @param VendorGuid                       Variable vendor GUID.\r
   @param Attributes                       Attribute value of the variable found\r
@@ -463,6 +493,9 @@ VariableServiceSetVariable (
 \r
   This code returns information about the EFI variables.\r
 \r
+  Caution: This function may receive untrusted input.\r
+  This function may be invoked in SMM mode. This function will do basic validation, before parse the data.\r
+\r
   @param Attributes                     Attributes bitmask to specify the type of variables\r
                                         on which to return information.\r
   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available\r