public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
From: "Ni, Ray" <ray.ni@intel.com>
To: "Wu, Hao A" <hao.a.wu@intel.com>,
	"edk2-devel@lists.01.org" <edk2-devel@lists.01.org>
Cc: "Wang, Jian J" <jian.j.wang@intel.com>,
	"Dong, Eric" <eric.dong@intel.com>
Subject: Re: [PATCH v2 03/12] MdeModulePkg: Add definitions for Storage Security Command PPI
Date: Thu, 31 Jan 2019 03:26:25 +0000	[thread overview]
Message-ID: <734D49CCEBEEF84792F5B80ED585239D5BFFFF2C@SHSMSX104.ccr.corp.intel.com> (raw)
In-Reply-To: <20190131024854.4880-4-hao.a.wu@intel.com>

Reviewed-by: Ray Ni <ray.ni@intel.com>

> -----Original Message-----
> From: Wu, Hao A <hao.a.wu@intel.com>
> Sent: Thursday, January 31, 2019 10:49 AM
> To: edk2-devel@lists.01.org
> Cc: Wu, Hao A <hao.a.wu@intel.com>; Wang, Jian J <jian.j.wang@intel.com>;
> Ni, Ray <ray.ni@intel.com>; Dong, Eric <eric.dong@intel.com>
> Subject: [PATCH v2 03/12] MdeModulePkg: Add definitions for Storage
> Security Command PPI
> 
> REF:https://bugzilla.tianocore.org/show_bug.cgi?id=1409
> 
> This commit will add the definitions for Storage Security Command (SSC) PPI.
> This PPI will be be used to abstract mass storage devices to allow code
> running in the PEI phase to send security protocol commands to mass storage
> devices without specific knowledge of the type of device or controller that
> manages the device.
> 
> More specifically, the PPI will provide services to:
> 
> * Get the number of mass storage devices managed by a instance of the SSC
>   PPI (by service 'GetNumberofDevices');
> * Get the identification information (DevicePath) of a managing mass
>   storage devices (by service 'GetDevicePath');
> * Send security protocol commands to mass storage devices (by services
>   'ReceiveData' and 'SendData').
> 
> Cc: Jian J Wang <jian.j.wang@intel.com>
> Cc: Ray Ni <ray.ni@intel.com>
> Cc: Eric Dong <eric.dong@intel.com>
> Contributed-under: TianoCore Contribution Agreement 1.1
> Signed-off-by: Hao Wu <hao.a.wu@intel.com>
> ---
>  MdeModulePkg/MdeModulePkg.dec                     |   3 +
>  MdeModulePkg/Include/Ppi/StorageSecurityCommand.h | 283
> ++++++++++++++++++++
>  2 files changed, 286 insertions(+)
> 
> diff --git a/MdeModulePkg/MdeModulePkg.dec
> b/MdeModulePkg/MdeModulePkg.dec index 8efb19e626..7f646d7702
> 100644
> --- a/MdeModulePkg/MdeModulePkg.dec
> +++ b/MdeModulePkg/MdeModulePkg.dec
> @@ -483,6 +483,9 @@
>    ## Include/Ppi/AtaAhciController.h
>    gEdkiiPeiAtaAhciHostControllerPpiGuid     = { 0x61dd33ea, 0x421f, 0x4cc0,
> { 0x89, 0x29, 0xff, 0xee, 0xa9, 0xa1, 0xa2, 0x61 } }
> 
> +  ## Include/Ppi/StorageSecurityCommand.h
> +  gEdkiiPeiStorageSecurityCommandPpiGuid    = { 0x35de0b4e, 0x30fb,
> 0x46c3, { 0xbd, 0x84, 0x1f, 0xdb, 0xa1, 0x58, 0xbb, 0x56 } }
> +
>    ## Include/Ppi/AtaPassThru.h
>    gEdkiiPeiAtaPassThruPpiGuid               = { 0xa16473fd, 0xd474, 0x4c89, { 0xae,
> 0xc7, 0x90, 0xb8, 0x3c, 0x73, 0x86, 0x9  } }
> 
> diff --git a/MdeModulePkg/Include/Ppi/StorageSecurityCommand.h
> b/MdeModulePkg/Include/Ppi/StorageSecurityCommand.h
> new file mode 100644
> index 0000000000..cc1688dabb
> --- /dev/null
> +++ b/MdeModulePkg/Include/Ppi/StorageSecurityCommand.h
> @@ -0,0 +1,283 @@
> +/** @file
> +
> +  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>  This
> + program and the accompanying materials  are licensed and made
> + available under the terms and conditions of the BSD License  which
> + accompanies this distribution.  The full text of the license may be
> + found at  http://opensource.org/licenses/bsd-license.php
> +
> +  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS"
> BASIS,
> + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER
> EXPRESS OR IMPLIED.
> +
> +**/
> +
> +#ifndef _EDKII_STORAGE_SECURITY_COMMAND_PPI_H_
> +#define _EDKII_STORAGE_SECURITY_COMMAND_PPI_H_
> +
> +#include <Protocol/DevicePath.h>
> +
> +///
> +/// Global ID for the EDKII_PEI_STORAGE_SECURITY_CMD_PPI.
> +///
> +#define EDKII_PEI_STORAGE_SECURITY_CMD_PPI_GUID \
> +  { \
> +    0x35de0b4e, 0x30fb, 0x46c3, { 0xbd, 0x84, 0x1f, 0xdb, 0xa1, 0x58,
> +0xbb, 0x56 } \
> +  }
> +
> +//
> +// Forward declaration for the EDKII_PEI_STORAGE_SECURITY_CMD_PPI.
> +//
> +typedef struct _EDKII_PEI_STORAGE_SECURITY_CMD_PPI
> +EDKII_PEI_STORAGE_SECURITY_CMD_PPI;
> +
> +//
> +// Revision The revision to which the Storage Security Command interface
> adheres.
> +//          All future revisions must be backwards compatible.
> +//          If a future version is not back wards compatible it is not the same
> GUID.
> +//
> +#define EDKII_STORAGE_SECURITY_PPI_REVISION  0x00010000
> +
> +
> +/**
> +  Gets the count of storage security devices that one specific driver detects.
> +
> +  @param[in]  This               The PPI instance pointer.
> +  @param[out] NumberofDevices    The number of storage security devices
> discovered.
> +
> +  @retval EFI_SUCCESS              The operation performed successfully.
> +  @retval EFI_INVALID_PARAMETER    The parameters are invalid.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_PEI_STORAGE_SECURITY_GET_NUMBER_DEVICES) (
> +  IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
> +  OUT UINTN                                 *NumberofDevices
> +  );
> +
> +/**
> +  Gets the device path of a specific storage security device.
> +
> +  @param[in]  This                 The PPI instance pointer.
> +  @param[in]  DeviceIndex          Specifies the storage security device to
> which
> +                                   the function wants to talk. Because the driver
> +                                   that implements Storage Security Command PPIs
> +                                   will manage multiple storage devices, the PPIs
> +                                   that want to talk to a single device must specify
> +                                   the device index that was assigned during the
> +                                   enumeration process. This index is a number from
> +                                   one to NumberofDevices.
> +  @param[out] DevicePathLength     The length of the device path in bytes
> specified
> +                                   by DevicePath.
> +  @param[out] DevicePath           The device path of storage security device.
> +                                   This field re-uses EFI Device Path Protocol as
> +                                   defined by Section 10.2 EFI Device Path Protocol
> +                                   of UEFI 2.7 Specification.
> +
> +  @retval EFI_SUCCESS              The operation succeeds.
> +  @retval EFI_INVALID_PARAMETER    DevicePathLength or DevicePath is
> NULL.
> +  @retval EFI_NOT_FOUND            The specified storage security device not
> found.
> +  @retval EFI_OUT_OF_RESOURCES     The operation fails due to lack of
> resources.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_PEI_STORAGE_SECURITY_GET_DEVICE_PATH) (
> +  IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
> +  IN  UINTN                                 DeviceIndex,
> +  OUT UINTN                                 *DevicePathLength,
> +  OUT EFI_DEVICE_PATH_PROTOCOL              **DevicePath
> +  );
> +
> +/**
> +  Send a security protocol command to a device that receives data
> +and/or the result
> +  of one or more commands sent by SendData.
> +
> +  The ReceiveData function sends a security protocol command to the given
> DeviceIndex.
> +  The security protocol command sent is defined by SecurityProtocolId
> + and contains  the security protocol specific data
> + SecurityProtocolSpecificData. The function  returns the data from the
> security protocol command in PayloadBuffer.
> +
> +  For devices supporting the SCSI command set, the security protocol
> + command is sent  using the SECURITY PROTOCOL IN command defined in
> SPC-4.
> +
> +  For devices supporting the ATA command set, the security protocol
> + command is sent  using one of the TRUSTED RECEIVE commands defined in
> + ATA8-ACS if PayloadBufferSize  is non-zero.
> +
> +  If the PayloadBufferSize is zero, the security protocol command is
> + sent using the  Trusted Non-Data command defined in ATA8-ACS.
> +
> +  If PayloadBufferSize is too small to store the available data from
> + the security  protocol command, the function shall copy
> + PayloadBufferSize bytes into the  PayloadBuffer and return
> EFI_WARN_BUFFER_TOO_SMALL.
> +
> +  If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize
> + is non-zero,  the function shall return EFI_INVALID_PARAMETER.
> +
> +  If the given DeviceIndex does not support security protocol commands,
> + the function  shall return EFI_UNSUPPORTED.
> +
> +  If the security protocol fails to complete within the Timeout period,
> + the function  shall return EFI_TIMEOUT.
> +
> +  If the security protocol command completes without an error, the
> + function shall  return EFI_SUCCESS. If the security protocol command
> + completes with an error, the  function shall return EFI_DEVICE_ERROR.
> +
> +  @param[in]  This             The PPI instance pointer.
> +  @param[in]  DeviceIndex      Specifies the storage security device to which
> the
> +                               function wants to talk. Because the driver that
> +                               implements Storage Security Command PPIs will manage
> +                               multiple storage devices, the PPIs that want to talk
> +                               to a single device must specify the device index
> +                               that was assigned during the enumeration process.
> +                               This index is a number from one to NumberofDevices.
> +  @param[in]  Timeout          The timeout, in 100ns units, to use for the
> execution
> +                               of the security protocol command. A Timeout value
> +                               of 0 means that this function will wait indefinitely
> +                               for the security protocol command to execute. If
> +                               Timeout is greater than zero, then this function
> +                               will return EFI_TIMEOUT if the time required to
> +                               execute the receive data command is greater than
> +                               Timeout.
> +  @param[in]  SecurityProtocolId
> +                               The value of the "Security Protocol" parameter of
> +                               the security protocol command to be sent.
> +  @param[in]  SecurityProtocolSpecificData
> +                               The value of the "Security Protocol Specific"
> +                               parameter of the security protocol command to be
> +                               sent.
> +  @param[in]  PayloadBufferSize
> +                               Size in bytes of the payload data buffer.
> +  @param[out] PayloadBuffer    A pointer to a destination buffer to store
> the
> +                               security protocol command specific payload data
> +                               for the security protocol command. The caller is
> +                               responsible for having either implicit or explicit
> +                               ownership of the buffer.
> +  @param[out] PayloadTransferSize
> +                               A pointer to a buffer to store the size in bytes
> +                               of the data written to the payload data buffer.
> +
> +  @retval EFI_SUCCESS                  The security protocol command completed
> +                                       successfully.
> +  @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too
> small to
> +                                       store the available data from the device.
> +                                       The PayloadBuffer contains the truncated
> +                                       data.
> +  @retval EFI_UNSUPPORTED              The given DeviceIndex does not
> support
> +                                       security protocol commands.
> +  @retval EFI_DEVICE_ERROR             The security protocol command
> completed
> +                                       with an error.
> +  @retval EFI_INVALID_PARAMETER        The PayloadBuffer or
> PayloadTransferSize
> +                                       is NULL and PayloadBufferSize is non-zero.
> +  @retval EFI_TIMEOUT                  A timeout occurred while waiting for the
> +                                       security protocol command to execute.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_PEI_STORAGE_SECURITY_RECEIVE_DATA) (
> +  IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
> +  IN  UINTN                                 DeviceIndex,
> +  IN  UINT64                                Timeout,
> +  IN  UINT8                                 SecurityProtocolId,
> +  IN  UINT16                                SecurityProtocolSpecificData,
> +  IN  UINTN                                 PayloadBufferSize,
> +  OUT VOID                                  *PayloadBuffer,
> +  OUT UINTN                                 *PayloadTransferSize
> +  );
> +
> +/**
> +  Send a security protocol command to a device.
> +
> +  The SendData function sends a security protocol command containing
> + the payload  PayloadBuffer to the given DeviceIndex. The security
> + protocol command sent is  defined by SecurityProtocolId and contains
> + the security protocol specific data  SecurityProtocolSpecificData. If
> + the underlying protocol command requires a  specific padding for the
> + command payload, the SendData function shall add padding  bytes to the
> command payload to satisfy the padding requirements.
> +
> +  For devices supporting the SCSI command set, the security protocol
> + command is  sent using the SECURITY PROTOCOL OUT command defined in
> SPC-4.
> +
> +  For devices supporting the ATA command set, the security protocol
> + command is  sent using one of the TRUSTED SEND commands defined in
> + ATA8-ACS if PayloadBufferSize  is non-zero. If the PayloadBufferSize
> + is zero, the security protocol command  is sent using the Trusted Non-Data
> command defined in ATA8-ACS.
> +
> +  If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the
> + function shall  return EFI_INVALID_PARAMETER.
> +
> +  If the given DeviceIndex does not support security protocol commands,
> + the function  shall return EFI_UNSUPPORTED.
> +
> +  If the security protocol fails to complete within the Timeout period,
> + the function  shall return EFI_TIMEOUT.
> +
> +  If the security protocol command completes without an error, the
> + function shall  return EFI_SUCCESS. If the security protocol command
> + completes with an error,  the functio shall return EFI_DEVICE_ERROR.
> +
> +  @param[in] This              The PPI instance pointer.
> +  @param[in] DeviceIndex       The ID of the device.
> +  @param[in] Timeout           The timeout, in 100ns units, to use for the
> execution
> +                               of the security protocol command. A Timeout value
> +                               of 0 means that this function will wait indefinitely
> +                               for the security protocol command to execute. If
> +                               Timeout is greater than zero, then this function
> +                               will return EFI_TIMEOUT if the time required to
> +                               execute the receive data command is greater than
> +                               Timeout.
> +  @param[in] SecurityProtocolId
> +                               The value of the "Security Protocol" parameter of
> +                               the security protocol command to be sent.
> +  @param[in] SecurityProtocolSpecificData
> +                               The value of the "Security Protocol Specific"
> +                               parameter of the security protocol command to be
> +                               sent.
> +  @param[in] PayloadBufferSize Size in bytes of the payload data buffer.
> +  @param[in] PayloadBuffer     A pointer to a destination buffer to store the
> +                               security protocol command specific payload data
> +                               for the security protocol command.
> +
> +  @retval EFI_SUCCESS              The security protocol command completed
> successfully.
> +  @retval EFI_UNSUPPORTED          The given DeviceIndex does not support
> security
> +                                   protocol commands.
> +  @retval EFI_DEVICE_ERROR         The security protocol command
> completed with
> +                                   an error.
> +  @retval EFI_INVALID_PARAMETER    The PayloadBuffer is NULL and
> PayloadBufferSize
> +                                   is non-zero.
> +  @retval EFI_TIMEOUT              A timeout occurred while waiting for the
> security
> +                                   protocol command to execute.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_PEI_STORAGE_SECURITY_SEND_DATA) (
> +  IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
> +  IN UINTN                                 DeviceIndex,
> +  IN UINT64                                Timeout,
> +  IN UINT8                                 SecurityProtocolId,
> +  IN UINT16                                SecurityProtocolSpecificData,
> +  IN UINTN                                 PayloadBufferSize,
> +  IN VOID                                  *PayloadBuffer
> +  );
> +
> +//
> +// EDKII_PEI_STORAGE_SECURITY_CMD_PPI contains a set of services to
> +send security // protocol commands to a mass storage device. Two types
> +of security protocol // commands are supported. SendData sends a
> command with data to a device.
> +// ReceiveData sends a command that receives data and/or the result of
> +one or // more commands sent by SendData.
> +//
> +struct _EDKII_PEI_STORAGE_SECURITY_CMD_PPI {
> +  UINT64                                           Revision;
> +  EDKII_PEI_STORAGE_SECURITY_GET_NUMBER_DEVICES
> GetNumberofDevices;
> +  EDKII_PEI_STORAGE_SECURITY_GET_DEVICE_PATH       GetDevicePath;
> +  EDKII_PEI_STORAGE_SECURITY_RECEIVE_DATA          ReceiveData;
> +  EDKII_PEI_STORAGE_SECURITY_SEND_DATA             SendData;
> +};
> +
> +extern EFI_GUID gEdkiiPeiStorageSecurityCommandPpiGuid;
> +
> +#endif
> --
> 2.12.0.windows.1



  reply	other threads:[~2019-01-31  3:29 UTC|newest]

Thread overview: 29+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-01-31  2:48 [PATCH v2 00/12] Split the S3 PEI phase HW init codes from Opal driver Hao Wu
2019-01-31  2:48 ` [PATCH v2 01/12] MdeModulePkg: Add definitions for ATA AHCI host controller PPI Hao Wu
2019-01-31  3:25   ` Ni, Ray
2019-01-31  2:48 ` [PATCH v2 02/12] MdeModulePkg: Add definitions for EDKII PEI ATA PassThru PPI Hao Wu
2019-01-31  3:22   ` Ni, Ray
2019-01-31  5:28     ` Wu, Hao A
2019-01-31  2:48 ` [PATCH v2 03/12] MdeModulePkg: Add definitions for Storage Security Command PPI Hao Wu
2019-01-31  3:26   ` Ni, Ray [this message]
2019-01-31  2:48 ` [PATCH v2 04/12] MdeModulePkg: Add GUID for LockBox to save storage dev to init in S3 Hao Wu
2019-01-31  3:27   ` Ni, Ray
2019-01-31  5:30     ` Wu, Hao A
2019-01-31  2:48 ` [PATCH v2 05/12] MdeModulePkg/NvmExpressPei: Avoid updating the module-level variable Hao Wu
2019-01-31  3:28   ` Ni, Ray
2019-01-31  2:48 ` [PATCH v2 06/12] MdeModulePkg/NvmExpressPei: Add logic to produce SSC PPI Hao Wu
2019-01-31  3:35   ` Ni, Ray
2019-01-31  5:40     ` Wu, Hao A
2019-01-31  2:48 ` [PATCH v2 07/12] MdeModulePkg/NvmExpressPei: Consume S3StorageDeviceInitList LockBox Hao Wu
2019-01-31  3:45   ` Ni, Ray
2019-01-31  5:45     ` Wu, Hao A
2019-01-31  2:48 ` [PATCH v2 08/12] MdeModulePkg/AhciPei: Add AHCI mode ATA device support in PEI Hao Wu
2019-01-31  5:49   ` Ni, Ruiyu
2019-01-31  2:48 ` [PATCH v2 09/12] MdeModulePkg/SmmLockBoxLib: Use 'DEBUG_' prefix instead of 'EFI_D_' Hao Wu
2019-01-31  5:49   ` Ni, Ruiyu
2019-01-31  2:48 ` [PATCH v2 10/12] MdeModulePkg/SmmLockBox(PEI): Remove an ASSERT in RestoreLockBox() Hao Wu
2019-01-31  5:50   ` Ni, Ruiyu
2019-01-31  5:53     ` Wu, Hao A
2019-01-31  2:48 ` [PATCH v2 11/12] MdeModulePkg/SmmLockBoxLib: Support LockBox enlarge in UpdateLockBox() Hao Wu
2019-01-31  6:00   ` Ni, Ruiyu
2019-01-31  2:48 ` [PATCH v2 12/12] SecurityPkg/OpalPassword: Remove HW init codes and consume SSC PPI Hao Wu

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-list from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=734D49CCEBEEF84792F5B80ED585239D5BFFFF2C@SHSMSX104.ccr.corp.intel.com \
    --to=devel@edk2.groups.io \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox