SecurityPkg/Tcg/Opal/OpalPassword/OpalPasswordPei.c

   1 /** @file
   2   Opal Password PEI driver which is used to unlock Opal Password for S3.
   3
   4 Copyright (c) 2016 - 2019, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #include "OpalPasswordPei.h"
  16
  17 EFI_GUID mOpalDeviceLockBoxGuid = OPAL_DEVICE_LOCKBOX_GUID;
  18
  19
  20 /**
  21   Send a security protocol command to a device that receives data and/or the result
  22   of one or more commands sent by SendData.
  23
  24   The ReceiveData function sends a security protocol command to the given MediaId.
  25   The security protocol command sent is defined by SecurityProtocolId and contains
  26   the security protocol specific data SecurityProtocolSpecificData. The function
  27   returns the data from the security protocol command in PayloadBuffer.
  28
  29   For devices supporting the SCSI command set, the security protocol command is sent
  30   using the SECURITY PROTOCOL IN command defined in SPC-4.
  31
  32   For devices supporting the ATA command set, the security protocol command is sent
  33   using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
  34   is non-zero.
  35
  36   If the PayloadBufferSize is zero, the security protocol command is sent using the
  37   Trusted Non-Data command defined in ATA8-ACS.
  38
  39   If PayloadBufferSize is too small to store the available data from the security
  40   protocol command, the function shall copy PayloadBufferSize bytes into the
  41   PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
  42
  43   If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
  44   the function shall return EFI_INVALID_PARAMETER.
  45
  46   If the given MediaId does not support security protocol commands, the function shall
  47   return EFI_UNSUPPORTED. If there is no media in the device, the function returns
  48   EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device,
  49   the function returns EFI_MEDIA_CHANGED.
  50
  51   If the security protocol fails to complete within the Timeout period, the function
  52   shall return EFI_TIMEOUT.
  53
  54   If the security protocol command completes without an error, the function shall
  55   return EFI_SUCCESS. If the security protocol command completes with an error, the
  56   function shall return EFI_DEVICE_ERROR.
  57
  58   @param  This                         Indicates a pointer to the calling context.
  59   @param  MediaId                      ID of the medium to receive data from.
  60   @param  Timeout                      The timeout, in 100ns units, to use for the execution
  61                                        of the security protocol command. A Timeout value of 0
  62                                        means that this function will wait indefinitely for the
  63                                        security protocol command to execute. If Timeout is greater
  64                                        than zero, then this function will return EFI_TIMEOUT
  65                                        if the time required to execute the receive data command
  66                                        is greater than Timeout.
  67   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
  68                                        the security protocol command to be sent.
  69   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
  70                                        of the security protocol command to be sent.
  71   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
  72   @param  PayloadBuffer                A pointer to a destination buffer to store the security
  73                                        protocol command specific payload data for the security
  74                                        protocol command. The caller is responsible for having
  75                                        either implicit or explicit ownership of the buffer.
  76   @param  PayloadTransferSize          A pointer to a buffer to store the size in bytes of the
  77                                        data written to the payload data buffer.
  78
  79   @retval EFI_SUCCESS                  The security protocol command completed successfully.
  80   @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to store the available
  81                                        data from the device. The PayloadBuffer contains the truncated data.
  82   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
  83   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
  84   @retval EFI_NO_MEDIA                 There is no media in the device.
  85   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
  86   @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize is NULL and
  87                                        PayloadBufferSize is non-zero.
  88   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
  89                                        protocol command to execute.
  90
  91 **/
  92 EFI_STATUS
  93 EFIAPI
  94 SecurityReceiveData (
  95   IN  EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
  96   IN  UINT32                                   MediaId,
  97   IN  UINT64                                   Timeout,
  98   IN  UINT8                                    SecurityProtocolId,
  99   IN  UINT16                                   SecurityProtocolSpecificData,
 100   IN  UINTN                                    PayloadBufferSize,
 101   OUT VOID                                     *PayloadBuffer,
 102   OUT UINTN                                    *PayloadTransferSize
 103   )
 104 {
 105   OPAL_PEI_DEVICE               *PeiDev;
 106
 107   PeiDev = OPAL_PEI_DEVICE_FROM_THIS (This);
 108   if (PeiDev == NULL) {
 109     return EFI_DEVICE_ERROR;
 110   }
 111
 112   return PeiDev->SscPpi->ReceiveData (
 113                            PeiDev->SscPpi,
 114                            PeiDev->DeviceIndex,
 115                            SSC_PPI_GENERIC_TIMEOUT,
 116                            SecurityProtocolId,
 117                            SecurityProtocolSpecificData,
 118                            PayloadBufferSize,
 119                            PayloadBuffer,
 120                            PayloadTransferSize
 121                            );
 122 }
 123
 124 /**
 125   Send a security protocol command to a device.
 126
 127   The SendData function sends a security protocol command containing the payload
 128   PayloadBuffer to the given MediaId. The security protocol command sent is
 129   defined by SecurityProtocolId and contains the security protocol specific data
 130   SecurityProtocolSpecificData. If the underlying protocol command requires a
 131   specific padding for the command payload, the SendData function shall add padding
 132   bytes to the command payload to satisfy the padding requirements.
 133
 134   For devices supporting the SCSI command set, the security protocol command is sent
 135   using the SECURITY PROTOCOL OUT command defined in SPC-4.
 136
 137   For devices supporting the ATA command set, the security protocol command is sent
 138   using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
 139   is non-zero. If the PayloadBufferSize is zero, the security protocol command is
 140   sent using the Trusted Non-Data command defined in ATA8-ACS.
 141
 142   If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
 143   return EFI_INVALID_PARAMETER.
 144
 145   If the given MediaId does not support security protocol commands, the function
 146   shall return EFI_UNSUPPORTED. If there is no media in the device, the function
 147   returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the
 148   device, the function returns EFI_MEDIA_CHANGED.
 149
 150   If the security protocol fails to complete within the Timeout period, the function
 151   shall return EFI_TIMEOUT.
 152
 153   If the security protocol command completes without an error, the function shall return
 154   EFI_SUCCESS. If the security protocol command completes with an error, the function
 155   shall return EFI_DEVICE_ERROR.
 156
 157   @param  This                         Indicates a pointer to the calling context.
 158   @param  MediaId                      ID of the medium to receive data from.
 159   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 160                                        of the security protocol command. A Timeout value of 0
 161                                        means that this function will wait indefinitely for the
 162                                        security protocol command to execute. If Timeout is greater
 163                                        than zero, then this function will return EFI_TIMEOUT
 164                                        if the time required to execute the send data command
 165                                        is greater than Timeout.
 166   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 167                                        the security protocol command to be sent.
 168   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 169                                        of the security protocol command to be sent.
 170   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 171   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 172                                        protocol command specific payload data for the security
 173                                        protocol command.
 174
 175   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 176   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 177   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 178   @retval EFI_NO_MEDIA                 There is no media in the device.
 179   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 180   @retval EFI_INVALID_PARAMETER        The PayloadBuffer is NULL and PayloadBufferSize is non-zero.
 181   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 182                                        protocol command to execute.
 183
 184 **/
 185 EFI_STATUS
 186 EFIAPI
 187 SecuritySendData (
 188   IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
 189   IN UINT32                                   MediaId,
 190   IN UINT64                                   Timeout,
 191   IN UINT8                                    SecurityProtocolId,
 192   IN UINT16                                   SecurityProtocolSpecificData,
 193   IN UINTN                                    PayloadBufferSize,
 194   IN VOID                                     *PayloadBuffer
 195   )
 196 {
 197   OPAL_PEI_DEVICE               *PeiDev;
 198
 199   PeiDev = OPAL_PEI_DEVICE_FROM_THIS (This);
 200   if (PeiDev == NULL) {
 201     return EFI_DEVICE_ERROR;
 202   }
 203
 204   return PeiDev->SscPpi->SendData (
 205                            PeiDev->SscPpi,
 206                            PeiDev->DeviceIndex,
 207                            SSC_PPI_GENERIC_TIMEOUT,
 208                            SecurityProtocolId,
 209                            SecurityProtocolSpecificData,
 210                            PayloadBufferSize,
 211                            PayloadBuffer
 212                            );
 213 }
 214
 215 /**
 216
 217   The function returns whether or not the device is Opal Locked.
 218   TRUE means that the device is partially or fully locked.
 219   This will perform a Level 0 Discovery and parse the locking feature descriptor
 220
 221   @param[in]      OpalDev             Opal object to determine if locked.
 222   @param[out]     BlockSidSupported   Whether device support BlockSid feature.
 223
 224 **/
 225 BOOLEAN
 226 IsOpalDeviceLocked(
 227   OPAL_PEI_DEVICE    *OpalDev,
 228   BOOLEAN            *BlockSidSupported
 229   )
 230 {
 231   OPAL_SESSION                   Session;
 232   OPAL_DISK_SUPPORT_ATTRIBUTE    SupportedAttributes;
 233   TCG_LOCKING_FEATURE_DESCRIPTOR LockingFeature;
 234   UINT16                         OpalBaseComId;
 235   TCG_RESULT                     Ret;
 236
 237   Session.Sscp = &OpalDev->Sscp;
 238   Session.MediaId = 0;
 239
 240   Ret = OpalGetSupportedAttributesInfo (&Session, &SupportedAttributes, &OpalBaseComId);
 241   if (Ret != TcgResultSuccess) {
 242     return FALSE;
 243   }
 244
 245   Session.OpalBaseComId  = OpalBaseComId;
 246   *BlockSidSupported     = SupportedAttributes.BlockSid == 1 ? TRUE : FALSE;
 247
 248   Ret = OpalGetLockingInfo(&Session, &LockingFeature);
 249   if (Ret != TcgResultSuccess) {
 250     return FALSE;
 251   }
 252
 253   return OpalDeviceLocked (&SupportedAttributes, &LockingFeature);
 254 }
 255
 256 /**
 257   Unlock OPAL password for S3.
 258
 259   @param[in] OpalDev            Opal object to unlock.
 260
 261 **/
 262 VOID
 263 UnlockOpalPassword (
 264   IN OPAL_PEI_DEVICE            *OpalDev
 265   )
 266 {
 267   TCG_RESULT                    Result;
 268   OPAL_SESSION                  Session;
 269   BOOLEAN                       BlockSidSupport;
 270   UINT32                        PpStorageFlags;
 271   BOOLEAN                       BlockSIDEnabled;
 272
 273   BlockSidSupport = FALSE;
 274   if (IsOpalDeviceLocked (OpalDev, &BlockSidSupport)) {
 275     ZeroMem(&Session, sizeof (Session));
 276     Session.Sscp = &OpalDev->Sscp;
 277     Session.MediaId = 0;
 278     Session.OpalBaseComId = OpalDev->Device->OpalBaseComId;
 279
 280     Result = OpalUtilUpdateGlobalLockingRange (
 281                &Session,
 282                OpalDev->Device->Password,
 283                OpalDev->Device->PasswordLength,
 284                FALSE,
 285                FALSE
 286                );
 287     DEBUG ((
 288       DEBUG_INFO,
 289       "%a() OpalUtilUpdateGlobalLockingRange() Result = 0x%x\n",
 290       __FUNCTION__,
 291       Result
 292       ));
 293   }
 294
 295   PpStorageFlags = Tcg2PhysicalPresenceLibGetManagementFlags ();
 296   if ((PpStorageFlags & TCG2_BIOS_STORAGE_MANAGEMENT_FLAG_ENABLE_BLOCK_SID) != 0) {
 297     BlockSIDEnabled = TRUE;
 298   } else {
 299     BlockSIDEnabled = FALSE;
 300   }
 301   if (BlockSIDEnabled && BlockSidSupport) {
 302     DEBUG ((DEBUG_INFO, "OpalPassword: S3 phase send BlockSid command to device!\n"));
 303     ZeroMem(&Session, sizeof (Session));
 304     Session.Sscp = &OpalDev->Sscp;
 305     Session.MediaId = 0;
 306     Session.OpalBaseComId = OpalDev->Device->OpalBaseComId;
 307     Result = OpalBlockSid (&Session, TRUE);
 308     DEBUG ((
 309       DEBUG_INFO,
 310       "%a() OpalBlockSid() Result = 0x%x\n",
 311       __FUNCTION__,
 312       Result
 313       ));
 314   }
 315 }
 316
 317 /**
 318   Unlock the OPAL NVM Express and ATA devices for S3.
 319
 320   @param[in] SscPpi    Pointer to the EDKII_PEI_STORAGE_SECURITY_CMD_PPI instance.
 321
 322 **/
 323 VOID
 324 UnlockOpalPasswordDevices (
 325   IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI    *SscPpi
 326   )
 327 {
 328   EFI_STATUS                            Status;
 329   UINT8                                 *DevInfoBuffer;
 330   UINT8                                 DummyData;
 331   OPAL_DEVICE_LOCKBOX_DATA              *DevInfo;
 332   UINTN                                 DevInfoLength;
 333   EFI_DEVICE_PATH_PROTOCOL              *SscDevicePath;
 334   UINTN                                 SscDevicePathLength;
 335   UINTN                                 SscDeviceNum;
 336   UINTN                                 SscDeviceIndex;
 337   OPAL_PEI_DEVICE                       OpalDev;
 338
 339   //
 340   // Get OPAL devices info from LockBox.
 341   //
 342   DevInfoBuffer = &DummyData;
 343   DevInfoLength = sizeof (DummyData);
 344   Status = RestoreLockBox (&mOpalDeviceLockBoxGuid, DevInfoBuffer, &DevInfoLength);
 345   if (Status == EFI_BUFFER_TOO_SMALL) {
 346     DevInfoBuffer = AllocatePages (EFI_SIZE_TO_PAGES (DevInfoLength));
 347     if (DevInfoBuffer != NULL) {
 348       Status = RestoreLockBox (&mOpalDeviceLockBoxGuid, DevInfoBuffer, &DevInfoLength);
 349     }
 350   }
 351   if (DevInfoBuffer == NULL || DevInfoBuffer == &DummyData) {
 352     return;
 353   } else if (EFI_ERROR (Status)) {
 354     FreePages (DevInfoBuffer, EFI_SIZE_TO_PAGES (DevInfoLength));
 355     return;
 356   }
 357
 358   //
 359   // Go through all the devices managed by the SSC PPI instance.
 360   //
 361   Status = SscPpi->GetNumberofDevices (SscPpi, &SscDeviceNum);
 362   if (EFI_ERROR (Status)) {
 363     goto Exit;
 364   }
 365   for (SscDeviceIndex = 1; SscDeviceIndex <= SscDeviceNum; SscDeviceIndex++) {
 366     Status = SscPpi->GetDevicePath (
 367                        SscPpi,
 368                        SscDeviceIndex,
 369                        &SscDevicePathLength,
 370                        &SscDevicePath
 371                        );
 372     if (SscDevicePathLength <= sizeof (EFI_DEVICE_PATH_PROTOCOL)) {
 373       //
 374       // Device path validity check.
 375       //
 376       continue;
 377     }
 378
 379     //
 380     // Search the device in the restored LockBox.
 381     //
 382     for (DevInfo = (OPAL_DEVICE_LOCKBOX_DATA *) DevInfoBuffer;
 383          (UINTN) DevInfo < ((UINTN) DevInfoBuffer + DevInfoLength);
 384          DevInfo = (OPAL_DEVICE_LOCKBOX_DATA *) ((UINTN) DevInfo + DevInfo->Length)) {
 385       //
 386       // Find the matching device.
 387       //
 388       if ((DevInfo->DevicePathLength >= SscDevicePathLength) &&
 389           (CompareMem (
 390              DevInfo->DevicePath,
 391              SscDevicePath,
 392              SscDevicePathLength - sizeof (EFI_DEVICE_PATH_PROTOCOL)) == 0)) {
 393         OpalDev.Signature        = OPAL_PEI_DEVICE_SIGNATURE;
 394         OpalDev.Sscp.ReceiveData = SecurityReceiveData;
 395         OpalDev.Sscp.SendData    = SecuritySendData;
 396         OpalDev.Device           = DevInfo;
 397         OpalDev.Context          = NULL;
 398         OpalDev.SscPpi           = SscPpi;
 399         OpalDev.DeviceIndex      = SscDeviceIndex;
 400         UnlockOpalPassword (&OpalDev);
 401         break;
 402       }
 403     }
 404   }
 405
 406 Exit:
 407   ZeroMem (DevInfoBuffer, DevInfoLength);
 408   FreePages (DevInfoBuffer, EFI_SIZE_TO_PAGES (DevInfoLength));
 409
 410 }
 411
 412 /**
 413   One notified function at the installation of EDKII_PEI_STORAGE_SECURITY_CMD_PPI.
 414   It is to unlock OPAL password for S3.
 415
 416   @param[in] PeiServices         Indirect reference to the PEI Services Table.
 417   @param[in] NotifyDescriptor    Address of the notification descriptor data structure.
 418   @param[in] Ppi                 Address of the PPI that was installed.
 419
 420   @return Status of the notification.
 421           The status code returned from this function is ignored.
 422
 423 **/
 424 EFI_STATUS
 425 EFIAPI
 426 OpalPasswordStorageSecurityPpiNotify (
 427   IN EFI_PEI_SERVICES             **PeiServices,
 428   IN EFI_PEI_NOTIFY_DESCRIPTOR    *NotifyDesc,
 429   IN VOID                         *Ppi
 430   )
 431 {
 432   DEBUG ((DEBUG_INFO, "%a entered at S3 resume!\n", __FUNCTION__));
 433
 434   UnlockOpalPasswordDevices ((EDKII_PEI_STORAGE_SECURITY_CMD_PPI *) Ppi);
 435
 436   DEBUG ((DEBUG_INFO, "%a exit at S3 resume!\n", __FUNCTION__));
 437
 438   return EFI_SUCCESS;
 439 }
 440
 441
 442 EFI_PEI_NOTIFY_DESCRIPTOR mOpalPasswordStorageSecurityPpiNotifyDesc = {
 443   (EFI_PEI_PPI_DESCRIPTOR_NOTIFY_CALLBACK | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
 444   &gEdkiiPeiStorageSecurityCommandPpiGuid,
 445   OpalPasswordStorageSecurityPpiNotify
 446 };
 447
 448
 449 /**
 450   Main entry for this module.
 451
 452   @param FileHandle             Handle of the file being invoked.
 453   @param PeiServices            Pointer to PEI Services table.
 454
 455   @return Status from PeiServicesNotifyPpi.
 456
 457 **/
 458 EFI_STATUS
 459 EFIAPI
 460 OpalPasswordPeiInit (
 461   IN EFI_PEI_FILE_HANDLE        FileHandle,
 462   IN CONST EFI_PEI_SERVICES     **PeiServices
 463   )
 464 {
 465   EFI_STATUS       Status;
 466   EFI_BOOT_MODE    BootMode;
 467
 468   Status = PeiServicesGetBootMode (&BootMode);
 469   if ((EFI_ERROR (Status)) || (BootMode != BOOT_ON_S3_RESUME)) {
 470     return EFI_UNSUPPORTED;
 471   }
 472
 473   DEBUG ((DEBUG_INFO, "%a: Enters in S3 path.\n", __FUNCTION__));
 474
 475   Status = PeiServicesNotifyPpi (&mOpalPasswordStorageSecurityPpiNotifyDesc);
 476   ASSERT_EFI_ERROR (Status);
 477   return Status;
 478 }