MdeModulePkg/Include/Ppi/StorageSecurityCommand.h

   1 /** @file
   2
   3   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   4   This program and the accompanying materials
   5   are licensed and made available under the terms and conditions of the BSD License
   6   which accompanies this distribution.  The full text of the license may be found at
   7   http://opensource.org/licenses/bsd-license.php
   8
   9   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 **/
  13
  14 #ifndef _EDKII_STORAGE_SECURITY_COMMAND_PPI_H_
  15 #define _EDKII_STORAGE_SECURITY_COMMAND_PPI_H_
  16
  17 #include <Protocol/DevicePath.h>
  18
  19 ///
  20 /// Global ID for the EDKII_PEI_STORAGE_SECURITY_CMD_PPI.
  21 ///
  22 #define EDKII_PEI_STORAGE_SECURITY_CMD_PPI_GUID \
  23   { \
  24     0x35de0b4e, 0x30fb, 0x46c3, { 0xbd, 0x84, 0x1f, 0xdb, 0xa1, 0x58, 0xbb, 0x56 } \
  25   }
  26
  27 //
  28 // Forward declaration for the EDKII_PEI_STORAGE_SECURITY_CMD_PPI.
  29 //
  30 typedef struct _EDKII_PEI_STORAGE_SECURITY_CMD_PPI  EDKII_PEI_STORAGE_SECURITY_CMD_PPI;
  31
  32 //
  33 // Revision The revision to which the Storage Security Command interface adheres.
  34 //          All future revisions must be backwards compatible.
  35 //          If a future version is not back wards compatible it is not the same GUID.
  36 //
  37 #define EDKII_STORAGE_SECURITY_PPI_REVISION  0x00010000
  38
  39
  40 /**
  41   Gets the count of storage security devices that one specific driver detects.
  42
  43   @param[in]  This               The PPI instance pointer.
  44   @param[out] NumberofDevices    The number of storage security devices discovered.
  45
  46   @retval EFI_SUCCESS              The operation performed successfully.
  47   @retval EFI_INVALID_PARAMETER    The parameters are invalid.
  48
  49 **/
  50 typedef
  51 EFI_STATUS
  52 (EFIAPI *EDKII_PEI_STORAGE_SECURITY_GET_NUMBER_DEVICES) (
  53   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
  54   OUT UINTN                                 *NumberofDevices
  55   );
  56
  57 /**
  58   Gets the device path of a specific storage security device.
  59
  60   @param[in]  This                 The PPI instance pointer.
  61   @param[in]  DeviceIndex          Specifies the storage security device to which
  62                                    the function wants to talk. Because the driver
  63                                    that implements Storage Security Command PPIs
  64                                    will manage multiple storage devices, the PPIs
  65                                    that want to talk to a single device must specify
  66                                    the device index that was assigned during the
  67                                    enumeration process. This index is a number from
  68                                    one to NumberofDevices.
  69   @param[out] DevicePathLength     The length of the device path in bytes specified
  70                                    by DevicePath.
  71   @param[out] DevicePath           The device path of storage security device.
  72                                    This field re-uses EFI Device Path Protocol as
  73                                    defined by Section 10.2 EFI Device Path Protocol
  74                                    of UEFI 2.7 Specification.
  75
  76   @retval EFI_SUCCESS              The operation succeeds.
  77   @retval EFI_INVALID_PARAMETER    DevicePathLength or DevicePath is NULL.
  78   @retval EFI_NOT_FOUND            The specified storage security device not found.
  79   @retval EFI_OUT_OF_RESOURCES     The operation fails due to lack of resources.
  80
  81 **/
  82 typedef
  83 EFI_STATUS
  84 (EFIAPI *EDKII_PEI_STORAGE_SECURITY_GET_DEVICE_PATH) (
  85   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
  86   IN  UINTN                                 DeviceIndex,
  87   OUT UINTN                                 *DevicePathLength,
  88   OUT EFI_DEVICE_PATH_PROTOCOL              **DevicePath
  89   );
  90
  91 /**
  92   Send a security protocol command to a device that receives data and/or the result
  93   of one or more commands sent by SendData.
  94
  95   The ReceiveData function sends a security protocol command to the given DeviceIndex.
  96   The security protocol command sent is defined by SecurityProtocolId and contains
  97   the security protocol specific data SecurityProtocolSpecificData. The function
  98   returns the data from the security protocol command in PayloadBuffer.
  99
 100   For devices supporting the SCSI command set, the security protocol command is sent
 101   using the SECURITY PROTOCOL IN command defined in SPC-4.
 102
 103   For devices supporting the ATA command set, the security protocol command is sent
 104   using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
 105   is non-zero.
 106
 107   If the PayloadBufferSize is zero, the security protocol command is sent using the
 108   Trusted Non-Data command defined in ATA8-ACS.
 109
 110   If PayloadBufferSize is too small to store the available data from the security
 111   protocol command, the function shall copy PayloadBufferSize bytes into the
 112   PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
 113
 114   If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
 115   the function shall return EFI_INVALID_PARAMETER.
 116
 117   If the given DeviceIndex does not support security protocol commands, the function
 118   shall return EFI_UNSUPPORTED.
 119
 120   If the security protocol fails to complete within the Timeout period, the function
 121   shall return EFI_TIMEOUT.
 122
 123   If the security protocol command completes without an error, the function shall
 124   return EFI_SUCCESS. If the security protocol command completes with an error, the
 125   function shall return EFI_DEVICE_ERROR.
 126
 127   @param[in]  This             The PPI instance pointer.
 128   @param[in]  DeviceIndex      Specifies the storage security device to which the
 129                                function wants to talk. Because the driver that
 130                                implements Storage Security Command PPIs will manage
 131                                multiple storage devices, the PPIs that want to talk
 132                                to a single device must specify the device index
 133                                that was assigned during the enumeration process.
 134                                This index is a number from one to NumberofDevices.
 135   @param[in]  Timeout          The timeout, in 100ns units, to use for the execution
 136                                of the security protocol command. A Timeout value
 137                                of 0 means that this function will wait indefinitely
 138                                for the security protocol command to execute. If
 139                                Timeout is greater than zero, then this function
 140                                will return EFI_TIMEOUT if the time required to
 141                                execute the receive data command is greater than
 142                                Timeout.
 143   @param[in]  SecurityProtocolId
 144                                The value of the "Security Protocol" parameter of
 145                                the security protocol command to be sent.
 146   @param[in]  SecurityProtocolSpecificData
 147                                The value of the "Security Protocol Specific"
 148                                parameter of the security protocol command to be
 149                                sent.
 150   @param[in]  PayloadBufferSize
 151                                Size in bytes of the payload data buffer.
 152   @param[out] PayloadBuffer    A pointer to a destination buffer to store the
 153                                security protocol command specific payload data
 154                                for the security protocol command. The caller is
 155                                responsible for having either implicit or explicit
 156                                ownership of the buffer.
 157   @param[out] PayloadTransferSize
 158                                A pointer to a buffer to store the size in bytes
 159                                of the data written to the payload data buffer.
 160
 161   @retval EFI_SUCCESS                  The security protocol command completed
 162                                        successfully.
 163   @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to
 164                                        store the available data from the device.
 165                                        The PayloadBuffer contains the truncated
 166                                        data.
 167   @retval EFI_UNSUPPORTED              The given DeviceIndex does not support
 168                                        security protocol commands.
 169   @retval EFI_DEVICE_ERROR             The security protocol command completed
 170                                        with an error.
 171   @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize
 172                                        is NULL and PayloadBufferSize is non-zero.
 173   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the
 174                                        security protocol command to execute.
 175
 176 **/
 177 typedef
 178 EFI_STATUS
 179 (EFIAPI *EDKII_PEI_STORAGE_SECURITY_RECEIVE_DATA) (
 180   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
 181   IN  UINTN                                 DeviceIndex,
 182   IN  UINT64                                Timeout,
 183   IN  UINT8                                 SecurityProtocolId,
 184   IN  UINT16                                SecurityProtocolSpecificData,
 185   IN  UINTN                                 PayloadBufferSize,
 186   OUT VOID                                  *PayloadBuffer,
 187   OUT UINTN                                 *PayloadTransferSize
 188   );
 189
 190 /**
 191   Send a security protocol command to a device.
 192
 193   The SendData function sends a security protocol command containing the payload
 194   PayloadBuffer to the given DeviceIndex. The security protocol command sent is
 195   defined by SecurityProtocolId and contains the security protocol specific data
 196   SecurityProtocolSpecificData. If the underlying protocol command requires a
 197   specific padding for the command payload, the SendData function shall add padding
 198   bytes to the command payload to satisfy the padding requirements.
 199
 200   For devices supporting the SCSI command set, the security protocol command is
 201   sent using the SECURITY PROTOCOL OUT command defined in SPC-4.
 202
 203   For devices supporting the ATA command set, the security protocol command is
 204   sent using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
 205   is non-zero. If the PayloadBufferSize is zero, the security protocol command
 206   is sent using the Trusted Non-Data command defined in ATA8-ACS.
 207
 208   If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
 209   return EFI_INVALID_PARAMETER.
 210
 211   If the given DeviceIndex does not support security protocol commands, the function
 212   shall return EFI_UNSUPPORTED.
 213
 214   If the security protocol fails to complete within the Timeout period, the function
 215   shall return EFI_TIMEOUT.
 216
 217   If the security protocol command completes without an error, the function shall
 218   return EFI_SUCCESS. If the security protocol command completes with an error,
 219   the functio shall return EFI_DEVICE_ERROR.
 220
 221   @param[in] This              The PPI instance pointer.
 222   @param[in] DeviceIndex       The ID of the device.
 223   @param[in] Timeout           The timeout, in 100ns units, to use for the execution
 224                                of the security protocol command. A Timeout value
 225                                of 0 means that this function will wait indefinitely
 226                                for the security protocol command to execute. If
 227                                Timeout is greater than zero, then this function
 228                                will return EFI_TIMEOUT if the time required to
 229                                execute the receive data command is greater than
 230                                Timeout.
 231   @param[in] SecurityProtocolId
 232                                The value of the "Security Protocol" parameter of
 233                                the security protocol command to be sent.
 234   @param[in] SecurityProtocolSpecificData
 235                                The value of the "Security Protocol Specific"
 236                                parameter of the security protocol command to be
 237                                sent.
 238   @param[in] PayloadBufferSize Size in bytes of the payload data buffer.
 239   @param[in] PayloadBuffer     A pointer to a destination buffer to store the
 240                                security protocol command specific payload data
 241                                for the security protocol command.
 242
 243   @retval EFI_SUCCESS              The security protocol command completed successfully.
 244   @retval EFI_UNSUPPORTED          The given DeviceIndex does not support security
 245                                    protocol commands.
 246   @retval EFI_DEVICE_ERROR         The security protocol command completed with
 247                                    an error.
 248   @retval EFI_INVALID_PARAMETER    The PayloadBuffer is NULL and PayloadBufferSize
 249                                    is non-zero.
 250   @retval EFI_TIMEOUT              A timeout occurred while waiting for the security
 251                                    protocol command to execute.
 252
 253 **/
 254 typedef
 255 EFI_STATUS
 256 (EFIAPI *EDKII_PEI_STORAGE_SECURITY_SEND_DATA) (
 257   IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
 258   IN UINTN                                 DeviceIndex,
 259   IN UINT64                                Timeout,
 260   IN UINT8                                 SecurityProtocolId,
 261   IN UINT16                                SecurityProtocolSpecificData,
 262   IN UINTN                                 PayloadBufferSize,
 263   IN VOID                                  *PayloadBuffer
 264   );
 265
 266 //
 267 // EDKII_PEI_STORAGE_SECURITY_CMD_PPI contains a set of services to send security
 268 // protocol commands to a mass storage device. Two types of security protocol
 269 // commands are supported. SendData sends a command with data to a device.
 270 // ReceiveData sends a command that receives data and/or the result of one or
 271 // more commands sent by SendData.
 272 //
 273 struct _EDKII_PEI_STORAGE_SECURITY_CMD_PPI {
 274   UINT64                                           Revision;
 275   EDKII_PEI_STORAGE_SECURITY_GET_NUMBER_DEVICES    GetNumberofDevices;
 276   EDKII_PEI_STORAGE_SECURITY_GET_DEVICE_PATH       GetDevicePath;
 277   EDKII_PEI_STORAGE_SECURITY_RECEIVE_DATA          ReceiveData;
 278   EDKII_PEI_STORAGE_SECURITY_SEND_DATA             SendData;
 279 };
 280
 281 extern EFI_GUID gEdkiiPeiStorageSecurityCommandPpiGuid;
 282
 283 #endif