Refine code for MdePkg/Include/Ppi according to code review comments.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5951 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 36 insertions, 74 deletions

diff --git a/MdePkg/Include/Ppi/Security2.h b/MdePkg/Include/Ppi/Security2.h
index 5dbcd1a123..c18da3fd5e 100644
--- a/MdePkg/Include/Ppi/Security2.h
+++ b/MdePkg/Include/Ppi/Security2.h
@@ -41,56 +41,23 @@ typedef struct _EFI_PEI_SECURITY2_PPI  EFI_PEI_SECURITY2_PPI;
   priori policy in the PEI Foundation. Specifically, this

   situation leads to the question whether PEIMs that are either

   not in GUIDed sections or are in sections whose authentication

-  fails should still be executed. In fact, it is the

-  responsibility of the platform builder to make this decision.

-  This platform-scoped policy is a result that a desktop system

-  might not be able to skip or not execute PEIMs because the

-  skipped PEIM could be the agent that initializes main memory.

-  Alternately, a system may require that unsigned PEIMs not be

-  executed under any circumstances. In either case, the PEI

-  Foundation simply multiplexes access to the Section Extraction

-  PPI and the Security PPI. The Section Extraction PPI determines

-  the contents of a section, and the Security PPI tells the PEI

-  Foundation whether or not to invoke the PEIM. The PEIM that

-  publishes the AuthenticationState() service uses its parameters

-  in the following ways: ?? AuthenticationStatus conveys the

-  source information upon which the PEIM acts. 1) The

-  DeferExecution value tells the PEI Foundation whether or not to

-  dispatch the PEIM. In addition, between receiving the

-  AuthenticationState() from the PEI Foundation and returning with

-  the DeferExecution value, the PEIM that publishes

-  AuthenticationState() can do the following: 2) Log the file

-  state. 3) Lock the firmware hubs in response to an unsigned

-  PEIM being discovered. These latter behaviors are platform-

-  and market-specific and thus outside the scope of the PEI CIS.

-

-  @param PeiServices   An indirect pointer to the PEI Services Table published by the PEI Foundation.

-

-  @param This   Interface pointer that implements the particular

-                EFI_PEI_SECURITY2_PPI instance.

-

-

-  @param AuthenticationStatus   Authentication status of the

-                                file.

-

-  @param FvHandle   Handle of the volume in which the file

-                    resides. Type EFI_PEI_FV_HANDLE is defined

-                    in FfsFindNextVolume. This allows different

-                    policies depending on different firmware

-                    volumes.

-

-  @param FileHandle   Handle of the file under review. Type

-                      EFI_PEI FILE HANDLE is defined in

-                      FfsFindNextFile.

-

-  @param DeferExecution   Pointer to a variable that alerts the

-                          PEI Foundation to defer execution of a

-                          PEIM.

-

-  @retval EFI_SUCCESS   The service performed its action

-                        successfully.

-

-  @retval EFI_SECURITY_VIOLATION  The object cannot be trusted.

+  fails should still be executed.

+

+  @param PeiServices             An indirect pointer to the PEI Services

+                                 Table published by the PEI Foundation.

+  @param This                    Interface pointer that implements the

+                                 particular EFI_PEI_SECURITY2_PPI instance.

+  @param AuthenticationStatus    Authentication status of the file.

+  @param FvHandle                Handle of the volume in which the file

+                                 resides. This allows different policies

+                                 depending on different firmware volumes.

+  @param FileHandle              Handle of the file under review.

+  @param DeferExecution          Pointer to a variable that alerts the

+                                 PEI Foundation to defer execution of a

+                                 PEIM.

+

+  @retval EFI_SUCCESS            The service performed its action successfully.

+  @retval EFI_SECURITY_VIOLATION The object cannot be trusted.

 

 **/

 typedef

@@ -98,34 +65,29 @@ EFI_STATUS
 (EFIAPI *EFI_PEI_SECURITY_AUTHENTICATION_STATE)(

   IN CONST  EFI_PEI_SERVICES      **PeiServices,

   IN CONST  EFI_PEI_SECURITY2_PPI *This,

-  IN CONST  UINT32                AuthenticationStatus,

-  IN CONST  EFI_PEI_FV_HANDLE     FvHandle,

-  IN CONST  EFI_PEI_FV_HANDLE     FileHandle,

+  IN UINT32                       AuthenticationStatus,

+  IN EFI_PEI_FV_HANDLE            FvHandle,

+  IN EFI_PEI_FV_HANDLE            FileHandle,

   IN OUT    BOOLEAN               *DeferExecution

 );

 

-/**

-  @par Ppi Description: 

-  This PPI is a means by which the platform builder can indicate

-  a response to a PEIM's authentication state. This can be in

-  the form of a requirement for the PEI Foundation to skip a

-  module using the DeferExecution Boolean output in the

-  AuthenticationState() member function. Alternately, the

-  Security PPI can invoke something like a cryptographic PPI

-  that hashes the PEIM contents to log attestations, for which

-  the FileHandle parameter in AuthenticationState() will be

-  useful. If this PPI does not exist, PEIMs will be considered

-  trusted.

-

-  @param AuthenticationState  Allows the platform builder to

-                              implement a security policy in

-                              response to varying file

-                              authentication states. See the

-                              AuthenticationState() function

-                              description.

-

-**/

+///

+/// This PPI is a means by which the platform builder can indicate

+/// a response to a PEIM's authentication state. This can be in

+/// the form of a requirement for the PEI Foundation to skip a

+/// module using the DeferExecution Boolean output in the

+/// AuthenticationState() member function. Alternately, the

+/// Security PPI can invoke something like a cryptographic PPI

+/// that hashes the PEIM contents to log attestations, for which

+/// the FileHandle parameter in AuthenticationState() will be

+/// useful. If this PPI does not exist, PEIMs will be considered

+/// trusted.

+///

 struct _EFI_PEI_SECURITY2_PPI {

+  ///

+  /// Allows the platform builder to implement a security policy

+  /// in response to varying file authentication states.

+  ///

   EFI_PEI_SECURITY_AUTHENTICATION_STATE   AuthenticationState;

 };