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
next prev parent 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