MdeModulePkg/Bus/Pci/NvmExpressPei/NvmExpressPeiStorageSecurity.c

   1 /** @file
   2   The NvmExpressPei driver is used to manage non-volatile memory subsystem
   3   which follows NVM Express specification at PEI phase.
   4
   5   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #include "NvmExpressPei.h"
  12
  13 /**
  14   Trust transfer data from/to NVM Express device.
  15
  16   This function performs one NVMe transaction to do a trust transfer from/to NVM
  17   Express device.
  18
  19   @param[in]     Private           The pointer to the PEI_NVME_CONTROLLER_PRIVATE_DATA
  20                                    data structure.
  21   @param[in,out] Buffer            The pointer to the current transaction buffer.
  22   @param[in]     SecurityProtocolId
  23                                    The value of the "Security Protocol" parameter
  24                                    of the security protocol command to be sent.
  25   @param[in]     SecurityProtocolSpecificData
  26                                    The value of the "Security Protocol Specific"
  27                                    parameter of the security protocol command to
  28                                    be sent.
  29   @param[in]     TransferLength    The block number or sector count of the transfer.
  30   @param[in]     IsTrustSend       Indicates whether it is a trust send operation
  31                                    or not.
  32   @param[in]     Timeout           The timeout, in 100ns units, to use for the
  33                                    execution of the security protocol command.
  34                                    A Timeout value of 0 means that this function
  35                                    will wait indefinitely for the security protocol
  36                                    command to execute. If Timeout is greater than
  37                                    zero, then this function will return EFI_TIMEOUT
  38                                    if the time required to execute the receive
  39                                    data command is greater than Timeout.
  40   @param[out]    TransferLengthOut A pointer to a buffer to store the size in bytes
  41                                    of the data written to the buffer. Ignore it
  42                                    when IsTrustSend is TRUE.
  43
  44   @retval EFI_SUCCESS    The data transfer is complete successfully.
  45   @return others         Some error occurs when transferring data.
  46
  47 **/
  48 EFI_STATUS
  49 TrustTransferNvmeDevice (
  50   IN     PEI_NVME_CONTROLLER_PRIVATE_DATA    *Private,
  51   IN OUT VOID                                *Buffer,
  52   IN     UINT8                               SecurityProtocolId,
  53   IN     UINT16                              SecurityProtocolSpecificData,
  54   IN     UINTN                               TransferLength,
  55   IN     BOOLEAN                             IsTrustSend,
  56   IN     UINT64                              Timeout,
  57      OUT UINTN                               *TransferLengthOut
  58   )
  59 {
  60   EDKII_PEI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET    CommandPacket;
  61   EDKII_PEI_NVM_EXPRESS_COMMAND                     Command;
  62   EDKII_PEI_NVM_EXPRESS_COMPLETION                  Completion;
  63   EFI_STATUS                                        Status;
  64   UINT16                                            SpecificData;
  65
  66   ZeroMem (&CommandPacket, sizeof(EDKII_PEI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET));
  67   ZeroMem (&Command, sizeof(EDKII_PEI_NVM_EXPRESS_COMMAND));
  68   ZeroMem (&Completion, sizeof(EDKII_PEI_NVM_EXPRESS_COMPLETION));
  69
  70   CommandPacket.NvmeCmd        = &Command;
  71   CommandPacket.NvmeCompletion = &Completion;
  72
  73   //
  74   // Change Endianness of SecurityProtocolSpecificData
  75   //
  76   SpecificData = (((SecurityProtocolSpecificData << 8) & 0xFF00) | (SecurityProtocolSpecificData >> 8));
  77
  78   if (IsTrustSend) {
  79     Command.Cdw0.Opcode          = NVME_ADMIN_SECURITY_SEND_CMD;
  80     CommandPacket.TransferBuffer = Buffer;
  81     CommandPacket.TransferLength = (UINT32)TransferLength;
  82     CommandPacket.NvmeCmd->Cdw10 = (UINT32)((SecurityProtocolId << 24) | (SpecificData << 8));
  83     CommandPacket.NvmeCmd->Cdw11 = (UINT32)TransferLength;
  84   } else {
  85     Command.Cdw0.Opcode          = NVME_ADMIN_SECURITY_RECEIVE_CMD;
  86     CommandPacket.TransferBuffer = Buffer;
  87     CommandPacket.TransferLength = (UINT32)TransferLength;
  88     CommandPacket.NvmeCmd->Cdw10 = (UINT32)((SecurityProtocolId << 24) | (SpecificData << 8));
  89     CommandPacket.NvmeCmd->Cdw11 = (UINT32)TransferLength;
  90   }
  91
  92   CommandPacket.NvmeCmd->Flags = CDW10_VALID | CDW11_VALID;
  93   CommandPacket.NvmeCmd->Nsid  = NVME_CONTROLLER_NSID;
  94   CommandPacket.CommandTimeout = Timeout;
  95   CommandPacket.QueueType      = NVME_ADMIN_QUEUE;
  96
  97   Status = NvmePassThru (
  98              Private,
  99              NVME_CONTROLLER_NSID,
 100              &CommandPacket
 101              );
 102
 103   if (!IsTrustSend) {
 104     if (EFI_ERROR (Status))  {
 105       *TransferLengthOut = 0;
 106     } else {
 107       *TransferLengthOut = (UINTN) TransferLength;
 108     }
 109   }
 110
 111   return Status;
 112 }
 113
 114 /**
 115   Gets the count of storage security devices that one specific driver detects.
 116
 117   @param[in]  This               The PPI instance pointer.
 118   @param[out] NumberofDevices    The number of storage security devices discovered.
 119
 120   @retval EFI_SUCCESS              The operation performed successfully.
 121   @retval EFI_INVALID_PARAMETER    The parameters are invalid.
 122
 123 **/
 124 EFI_STATUS
 125 EFIAPI
 126 NvmeStorageSecurityGetDeviceNo (
 127   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *This,
 128   OUT UINTN                                 *NumberofDevices
 129   )
 130 {
 131   PEI_NVME_CONTROLLER_PRIVATE_DATA    *Private;
 132
 133   if (This == NULL || NumberofDevices == NULL) {
 134     return EFI_INVALID_PARAMETER;
 135   }
 136
 137   Private = GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY (This);
 138   *NumberofDevices = Private->ActiveNamespaceNum;
 139
 140   return EFI_SUCCESS;
 141 }
 142
 143 /**
 144   Gets the device path of a specific storage security device.
 145
 146   @param[in]  This                 The PPI instance pointer.
 147   @param[in]  DeviceIndex          Specifies the storage security device to which
 148                                    the function wants to talk. Because the driver
 149                                    that implements Storage Security Command PPIs
 150                                    will manage multiple storage devices, the PPIs
 151                                    that want to talk to a single device must specify
 152                                    the device index that was assigned during the
 153                                    enumeration process. This index is a number from
 154                                    one to NumberofDevices.
 155   @param[out] DevicePathLength     The length of the device path in bytes specified
 156                                    by DevicePath.
 157   @param[out] DevicePath           The device path of storage security device.
 158                                    This field re-uses EFI Device Path Protocol as
 159                                    defined by Section 10.2 EFI Device Path Protocol
 160                                    of UEFI 2.7 Specification.
 161
 162   @retval EFI_SUCCESS              The operation succeeds.
 163   @retval EFI_INVALID_PARAMETER    DevicePathLength or DevicePath is NULL.
 164   @retval EFI_NOT_FOUND            The specified storage security device not found.
 165   @retval EFI_OUT_OF_RESOURCES     The operation fails due to lack of resources.
 166
 167 **/
 168 EFI_STATUS
 169 EFIAPI
 170 NvmeStorageSecurityGetDevicePath (
 171   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI  *This,
 172   IN  UINTN                               DeviceIndex,
 173   OUT UINTN                               *DevicePathLength,
 174   OUT EFI_DEVICE_PATH_PROTOCOL            **DevicePath
 175   )
 176 {
 177   PEI_NVME_CONTROLLER_PRIVATE_DATA         *Private;
 178
 179   if (This == NULL || DevicePathLength == NULL || DevicePath == NULL) {
 180     return EFI_INVALID_PARAMETER;
 181   }
 182
 183   Private = GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY (This);
 184   if ((DeviceIndex == 0) || (DeviceIndex > Private->ActiveNamespaceNum)) {
 185     return EFI_INVALID_PARAMETER;
 186   }
 187
 188   return NvmeBuildDevicePath (
 189            Private,
 190            Private->NamespaceInfo[DeviceIndex-1].NamespaceId,
 191            Private->NamespaceInfo[DeviceIndex-1].NamespaceUuid,
 192            DevicePathLength,
 193            DevicePath
 194            );
 195 }
 196
 197 /**
 198   Send a security protocol command to a device that receives data and/or the result
 199   of one or more commands sent by SendData.
 200
 201   The ReceiveData function sends a security protocol command to the given DeviceIndex.
 202   The security protocol command sent is defined by SecurityProtocolId and contains
 203   the security protocol specific data SecurityProtocolSpecificData. The function
 204   returns the data from the security protocol command in PayloadBuffer.
 205
 206   For devices supporting the SCSI command set, the security protocol command is sent
 207   using the SECURITY PROTOCOL IN command defined in SPC-4.
 208
 209   For devices supporting the ATA command set, the security protocol command is sent
 210   using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
 211   is non-zero.
 212
 213   If the PayloadBufferSize is zero, the security protocol command is sent using the
 214   Trusted Non-Data command defined in ATA8-ACS.
 215
 216   If PayloadBufferSize is too small to store the available data from the security
 217   protocol command, the function shall copy PayloadBufferSize bytes into the
 218   PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
 219
 220   If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
 221   the function shall return EFI_INVALID_PARAMETER.
 222
 223   If the given DeviceIndex does not support security protocol commands, the function
 224   shall return EFI_UNSUPPORTED.
 225
 226   If the security protocol fails to complete within the Timeout period, the function
 227   shall return EFI_TIMEOUT.
 228
 229   If the security protocol command completes without an error, the function shall
 230   return EFI_SUCCESS. If the security protocol command completes with an error, the
 231   function shall return EFI_DEVICE_ERROR.
 232
 233   @param[in]  This             The PPI instance pointer.
 234   @param[in]  DeviceIndex      Specifies the storage security device to which the
 235                                function wants to talk. Because the driver that
 236                                implements Storage Security Command PPIs will manage
 237                                multiple storage devices, the PPIs that want to talk
 238                                to a single device must specify the device index
 239                                that was assigned during the enumeration process.
 240                                This index is a number from one to NumberofDevices.
 241   @param[in]  Timeout          The timeout, in 100ns units, to use for the execution
 242                                of the security protocol command. A Timeout value
 243                                of 0 means that this function will wait indefinitely
 244                                for the security protocol command to execute. If
 245                                Timeout is greater than zero, then this function
 246                                will return EFI_TIMEOUT if the time required to
 247                                execute the receive data command is greater than
 248                                Timeout.
 249   @param[in]  SecurityProtocolId
 250                                The value of the "Security Protocol" parameter of
 251                                the security protocol command to be sent.
 252   @param[in]  SecurityProtocolSpecificData
 253                                The value of the "Security Protocol Specific"
 254                                parameter of the security protocol command to be
 255                                sent.
 256   @param[in]  PayloadBufferSize
 257                                Size in bytes of the payload data buffer.
 258   @param[out] PayloadBuffer    A pointer to a destination buffer to store the
 259                                security protocol command specific payload data
 260                                for the security protocol command. The caller is
 261                                responsible for having either implicit or explicit
 262                                ownership of the buffer.
 263   @param[out] PayloadTransferSize
 264                                A pointer to a buffer to store the size in bytes
 265                                of the data written to the payload data buffer.
 266
 267   @retval EFI_SUCCESS                  The security protocol command completed
 268                                        successfully.
 269   @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to
 270                                        store the available data from the device.
 271                                        The PayloadBuffer contains the truncated
 272                                        data.
 273   @retval EFI_UNSUPPORTED              The given DeviceIndex does not support
 274                                        security protocol commands.
 275   @retval EFI_DEVICE_ERROR             The security protocol command completed
 276                                        with an error.
 277   @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize
 278                                        is NULL and PayloadBufferSize is non-zero.
 279   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the
 280                                        security protocol command to execute.
 281
 282 **/
 283 EFI_STATUS
 284 EFIAPI
 285 NvmeStorageSecurityReceiveData (
 286   IN  EDKII_PEI_STORAGE_SECURITY_CMD_PPI  *This,
 287   IN  UINTN                               DeviceIndex,
 288   IN  UINT64                              Timeout,
 289   IN  UINT8                               SecurityProtocolId,
 290   IN  UINT16                              SecurityProtocolSpecificData,
 291   IN  UINTN                               PayloadBufferSize,
 292   OUT VOID                                *PayloadBuffer,
 293   OUT UINTN                               *PayloadTransferSize
 294   )
 295 {
 296   PEI_NVME_CONTROLLER_PRIVATE_DATA    *Private;
 297   EFI_STATUS                          Status;
 298
 299   if ((PayloadBuffer == NULL) || (PayloadTransferSize == NULL) || (PayloadBufferSize == 0)) {
 300     return EFI_INVALID_PARAMETER;
 301   }
 302
 303   Private = GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY (This);
 304
 305   Status = TrustTransferNvmeDevice (
 306              Private,
 307              PayloadBuffer,
 308              SecurityProtocolId,
 309              SecurityProtocolSpecificData,
 310              PayloadBufferSize,
 311              FALSE,
 312              Timeout,
 313              PayloadTransferSize
 314              );
 315
 316   return Status;
 317 }
 318
 319 /**
 320   Send a security protocol command to a device.
 321
 322   The SendData function sends a security protocol command containing the payload
 323   PayloadBuffer to the given DeviceIndex. The security protocol command sent is
 324   defined by SecurityProtocolId and contains the security protocol specific data
 325   SecurityProtocolSpecificData. If the underlying protocol command requires a
 326   specific padding for the command payload, the SendData function shall add padding
 327   bytes to the command payload to satisfy the padding requirements.
 328
 329   For devices supporting the SCSI command set, the security protocol command is
 330   sent using the SECURITY PROTOCOL OUT command defined in SPC-4.
 331
 332   For devices supporting the ATA command set, the security protocol command is
 333   sent using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
 334   is non-zero. If the PayloadBufferSize is zero, the security protocol command
 335   is sent using the Trusted Non-Data command defined in ATA8-ACS.
 336
 337   If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
 338   return EFI_INVALID_PARAMETER.
 339
 340   If the given DeviceIndex does not support security protocol commands, the function
 341   shall return EFI_UNSUPPORTED.
 342
 343   If the security protocol fails to complete within the Timeout period, the function
 344   shall return EFI_TIMEOUT.
 345
 346   If the security protocol command completes without an error, the function shall
 347   return EFI_SUCCESS. If the security protocol command completes with an error,
 348   the functio shall return EFI_DEVICE_ERROR.
 349
 350   @param[in] This              The PPI instance pointer.
 351   @param[in] DeviceIndex       The ID of the device.
 352   @param[in] Timeout           The timeout, in 100ns units, to use for the execution
 353                                of the security protocol command. A Timeout value
 354                                of 0 means that this function will wait indefinitely
 355                                for the security protocol command to execute. If
 356                                Timeout is greater than zero, then this function
 357                                will return EFI_TIMEOUT if the time required to
 358                                execute the receive data command is greater than
 359                                Timeout.
 360   @param[in] SecurityProtocolId
 361                                The value of the "Security Protocol" parameter of
 362                                the security protocol command to be sent.
 363   @param[in] SecurityProtocolSpecificData
 364                                The value of the "Security Protocol Specific"
 365                                parameter of the security protocol command to be
 366                                sent.
 367   @param[in] PayloadBufferSize Size in bytes of the payload data buffer.
 368   @param[in] PayloadBuffer     A pointer to a destination buffer to store the
 369                                security protocol command specific payload data
 370                                for the security protocol command.
 371
 372   @retval EFI_SUCCESS              The security protocol command completed successfully.
 373   @retval EFI_UNSUPPORTED          The given DeviceIndex does not support security
 374                                    protocol commands.
 375   @retval EFI_DEVICE_ERROR         The security protocol command completed with
 376                                    an error.
 377   @retval EFI_INVALID_PARAMETER    The PayloadBuffer is NULL and PayloadBufferSize
 378                                    is non-zero.
 379   @retval EFI_TIMEOUT              A timeout occurred while waiting for the security
 380                                    protocol command to execute.
 381
 382 **/
 383 EFI_STATUS
 384 EFIAPI
 385 NvmeStorageSecuritySendData (
 386   IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI  *This,
 387   IN UINTN                               DeviceIndex,
 388   IN UINT64                              Timeout,
 389   IN UINT8                               SecurityProtocolId,
 390   IN UINT16                              SecurityProtocolSpecificData,
 391   IN UINTN                               PayloadBufferSize,
 392   IN VOID                                *PayloadBuffer
 393   )
 394 {
 395   PEI_NVME_CONTROLLER_PRIVATE_DATA    *Private;
 396   EFI_STATUS                          Status;
 397
 398   if ((PayloadBuffer == NULL) && (PayloadBufferSize != 0)) {
 399     return EFI_INVALID_PARAMETER;
 400   }
 401
 402   Private = GET_NVME_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY (This);
 403
 404   Status = TrustTransferNvmeDevice (
 405              Private,
 406              PayloadBuffer,
 407              SecurityProtocolId,
 408              SecurityProtocolSpecificData,
 409              PayloadBufferSize,
 410              TRUE,
 411              Timeout,
 412              NULL
 413              );
 414
 415   return Status;
 416 }