MdeModulePkg/Include/Ppi/StorageSecurityCommand.h

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