2 Opal Password PEI driver which is used to unlock Opal Password for S3.
4 Copyright (c) 2016 - 2019, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #include "OpalPasswordPei.h"
11 EFI_GUID mOpalDeviceLockBoxGuid
= OPAL_DEVICE_LOCKBOX_GUID
;
15 Send a security protocol command to a device that receives data and/or the result
16 of one or more commands sent by SendData.
18 The ReceiveData function sends a security protocol command to the given MediaId.
19 The security protocol command sent is defined by SecurityProtocolId and contains
20 the security protocol specific data SecurityProtocolSpecificData. The function
21 returns the data from the security protocol command in PayloadBuffer.
23 For devices supporting the SCSI command set, the security protocol command is sent
24 using the SECURITY PROTOCOL IN command defined in SPC-4.
26 For devices supporting the ATA command set, the security protocol command is sent
27 using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
30 If the PayloadBufferSize is zero, the security protocol command is sent using the
31 Trusted Non-Data command defined in ATA8-ACS.
33 If PayloadBufferSize is too small to store the available data from the security
34 protocol command, the function shall copy PayloadBufferSize bytes into the
35 PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
37 If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
38 the function shall return EFI_INVALID_PARAMETER.
40 If the given MediaId does not support security protocol commands, the function shall
41 return EFI_UNSUPPORTED. If there is no media in the device, the function returns
42 EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device,
43 the function returns EFI_MEDIA_CHANGED.
45 If the security protocol fails to complete within the Timeout period, the function
46 shall return EFI_TIMEOUT.
48 If the security protocol command completes without an error, the function shall
49 return EFI_SUCCESS. If the security protocol command completes with an error, the
50 function shall return EFI_DEVICE_ERROR.
52 @param This Indicates a pointer to the calling context.
53 @param MediaId ID of the medium to receive data from.
54 @param Timeout The timeout, in 100ns units, to use for the execution
55 of the security protocol command. A Timeout value of 0
56 means that this function will wait indefinitely for the
57 security protocol command to execute. If Timeout is greater
58 than zero, then this function will return EFI_TIMEOUT
59 if the time required to execute the receive data command
60 is greater than Timeout.
61 @param SecurityProtocolId The value of the "Security Protocol" parameter of
62 the security protocol command to be sent.
63 @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
64 of the security protocol command to be sent.
65 @param PayloadBufferSize Size in bytes of the payload data buffer.
66 @param PayloadBuffer A pointer to a destination buffer to store the security
67 protocol command specific payload data for the security
68 protocol command. The caller is responsible for having
69 either implicit or explicit ownership of the buffer.
70 @param PayloadTransferSize A pointer to a buffer to store the size in bytes of the
71 data written to the payload data buffer.
73 @retval EFI_SUCCESS The security protocol command completed successfully.
74 @retval EFI_WARN_BUFFER_TOO_SMALL The PayloadBufferSize was too small to store the available
75 data from the device. The PayloadBuffer contains the truncated data.
76 @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands.
77 @retval EFI_DEVICE_ERROR The security protocol command completed with an error.
78 @retval EFI_NO_MEDIA There is no media in the device.
79 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
80 @retval EFI_INVALID_PARAMETER The PayloadBuffer or PayloadTransferSize is NULL and
81 PayloadBufferSize is non-zero.
82 @retval EFI_TIMEOUT A timeout occurred while waiting for the security
83 protocol command to execute.
89 IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL
*This
,
92 IN UINT8 SecurityProtocolId
,
93 IN UINT16 SecurityProtocolSpecificData
,
94 IN UINTN PayloadBufferSize
,
95 OUT VOID
*PayloadBuffer
,
96 OUT UINTN
*PayloadTransferSize
99 OPAL_PEI_DEVICE
*PeiDev
;
101 PeiDev
= OPAL_PEI_DEVICE_FROM_THIS (This
);
102 if (PeiDev
== NULL
) {
103 return EFI_DEVICE_ERROR
;
106 return PeiDev
->SscPpi
->ReceiveData (
109 SSC_PPI_GENERIC_TIMEOUT
,
111 SecurityProtocolSpecificData
,
119 Send a security protocol command to a device.
121 The SendData function sends a security protocol command containing the payload
122 PayloadBuffer to the given MediaId. The security protocol command sent is
123 defined by SecurityProtocolId and contains the security protocol specific data
124 SecurityProtocolSpecificData. If the underlying protocol command requires a
125 specific padding for the command payload, the SendData function shall add padding
126 bytes to the command payload to satisfy the padding requirements.
128 For devices supporting the SCSI command set, the security protocol command is sent
129 using the SECURITY PROTOCOL OUT command defined in SPC-4.
131 For devices supporting the ATA command set, the security protocol command is sent
132 using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
133 is non-zero. If the PayloadBufferSize is zero, the security protocol command is
134 sent using the Trusted Non-Data command defined in ATA8-ACS.
136 If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
137 return EFI_INVALID_PARAMETER.
139 If the given MediaId does not support security protocol commands, the function
140 shall return EFI_UNSUPPORTED. If there is no media in the device, the function
141 returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the
142 device, the function returns EFI_MEDIA_CHANGED.
144 If the security protocol fails to complete within the Timeout period, the function
145 shall return EFI_TIMEOUT.
147 If the security protocol command completes without an error, the function shall return
148 EFI_SUCCESS. If the security protocol command completes with an error, the function
149 shall return EFI_DEVICE_ERROR.
151 @param This Indicates a pointer to the calling context.
152 @param MediaId ID of the medium to receive data from.
153 @param Timeout The timeout, in 100ns units, to use for the execution
154 of the security protocol command. A Timeout value of 0
155 means that this function will wait indefinitely for the
156 security protocol command to execute. If Timeout is greater
157 than zero, then this function will return EFI_TIMEOUT
158 if the time required to execute the send data command
159 is greater than Timeout.
160 @param SecurityProtocolId The value of the "Security Protocol" parameter of
161 the security protocol command to be sent.
162 @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
163 of the security protocol command to be sent.
164 @param PayloadBufferSize Size in bytes of the payload data buffer.
165 @param PayloadBuffer A pointer to a destination buffer to store the security
166 protocol command specific payload data for the security
169 @retval EFI_SUCCESS The security protocol command completed successfully.
170 @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands.
171 @retval EFI_DEVICE_ERROR The security protocol command completed with an error.
172 @retval EFI_NO_MEDIA There is no media in the device.
173 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
174 @retval EFI_INVALID_PARAMETER The PayloadBuffer is NULL and PayloadBufferSize is non-zero.
175 @retval EFI_TIMEOUT A timeout occurred while waiting for the security
176 protocol command to execute.
182 IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL
*This
,
185 IN UINT8 SecurityProtocolId
,
186 IN UINT16 SecurityProtocolSpecificData
,
187 IN UINTN PayloadBufferSize
,
188 IN VOID
*PayloadBuffer
191 OPAL_PEI_DEVICE
*PeiDev
;
193 PeiDev
= OPAL_PEI_DEVICE_FROM_THIS (This
);
194 if (PeiDev
== NULL
) {
195 return EFI_DEVICE_ERROR
;
198 return PeiDev
->SscPpi
->SendData (
201 SSC_PPI_GENERIC_TIMEOUT
,
203 SecurityProtocolSpecificData
,
211 The function returns whether or not the device is Opal Locked.
212 TRUE means that the device is partially or fully locked.
213 This will perform a Level 0 Discovery and parse the locking feature descriptor
215 @param[in] OpalDev Opal object to determine if locked.
216 @param[out] BlockSidSupported Whether device support BlockSid feature.
221 OPAL_PEI_DEVICE
*OpalDev
,
222 BOOLEAN
*BlockSidSupported
225 OPAL_SESSION Session
;
226 OPAL_DISK_SUPPORT_ATTRIBUTE SupportedAttributes
;
227 TCG_LOCKING_FEATURE_DESCRIPTOR LockingFeature
;
228 UINT16 OpalBaseComId
;
231 Session
.Sscp
= &OpalDev
->Sscp
;
234 Ret
= OpalGetSupportedAttributesInfo (&Session
, &SupportedAttributes
, &OpalBaseComId
);
235 if (Ret
!= TcgResultSuccess
) {
239 Session
.OpalBaseComId
= OpalBaseComId
;
240 *BlockSidSupported
= SupportedAttributes
.BlockSid
== 1 ? TRUE
: FALSE
;
242 Ret
= OpalGetLockingInfo(&Session
, &LockingFeature
);
243 if (Ret
!= TcgResultSuccess
) {
247 return OpalDeviceLocked (&SupportedAttributes
, &LockingFeature
);
251 Unlock OPAL password for S3.
253 @param[in] OpalDev Opal object to unlock.
258 IN OPAL_PEI_DEVICE
*OpalDev
262 OPAL_SESSION Session
;
263 BOOLEAN BlockSidSupport
;
264 UINT32 PpStorageFlags
;
265 BOOLEAN BlockSIDEnabled
;
267 BlockSidSupport
= FALSE
;
268 if (IsOpalDeviceLocked (OpalDev
, &BlockSidSupport
)) {
269 ZeroMem(&Session
, sizeof (Session
));
270 Session
.Sscp
= &OpalDev
->Sscp
;
272 Session
.OpalBaseComId
= OpalDev
->Device
->OpalBaseComId
;
274 Result
= OpalUtilUpdateGlobalLockingRange (
276 OpalDev
->Device
->Password
,
277 OpalDev
->Device
->PasswordLength
,
283 "%a() OpalUtilUpdateGlobalLockingRange() Result = 0x%x\n",
289 PpStorageFlags
= Tcg2PhysicalPresenceLibGetManagementFlags ();
290 if ((PpStorageFlags
& TCG2_BIOS_STORAGE_MANAGEMENT_FLAG_ENABLE_BLOCK_SID
) != 0) {
291 BlockSIDEnabled
= TRUE
;
293 BlockSIDEnabled
= FALSE
;
295 if (BlockSIDEnabled
&& BlockSidSupport
) {
296 DEBUG ((DEBUG_INFO
, "OpalPassword: S3 phase send BlockSid command to device!\n"));
297 ZeroMem(&Session
, sizeof (Session
));
298 Session
.Sscp
= &OpalDev
->Sscp
;
300 Session
.OpalBaseComId
= OpalDev
->Device
->OpalBaseComId
;
301 Result
= OpalBlockSid (&Session
, TRUE
);
304 "%a() OpalBlockSid() Result = 0x%x\n",
312 Unlock the OPAL NVM Express and ATA devices for S3.
314 @param[in] SscPpi Pointer to the EDKII_PEI_STORAGE_SECURITY_CMD_PPI instance.
318 UnlockOpalPasswordDevices (
319 IN EDKII_PEI_STORAGE_SECURITY_CMD_PPI
*SscPpi
323 UINT8
*DevInfoBuffer
;
325 OPAL_DEVICE_LOCKBOX_DATA
*DevInfo
;
327 EFI_DEVICE_PATH_PROTOCOL
*SscDevicePath
;
328 UINTN SscDevicePathLength
;
330 UINTN SscDeviceIndex
;
331 OPAL_PEI_DEVICE OpalDev
;
334 // Get OPAL devices info from LockBox.
336 DevInfoBuffer
= &DummyData
;
337 DevInfoLength
= sizeof (DummyData
);
338 Status
= RestoreLockBox (&mOpalDeviceLockBoxGuid
, DevInfoBuffer
, &DevInfoLength
);
339 if (Status
== EFI_BUFFER_TOO_SMALL
) {
340 DevInfoBuffer
= AllocatePages (EFI_SIZE_TO_PAGES (DevInfoLength
));
341 if (DevInfoBuffer
!= NULL
) {
342 Status
= RestoreLockBox (&mOpalDeviceLockBoxGuid
, DevInfoBuffer
, &DevInfoLength
);
345 if (DevInfoBuffer
== NULL
|| DevInfoBuffer
== &DummyData
) {
347 } else if (EFI_ERROR (Status
)) {
348 FreePages (DevInfoBuffer
, EFI_SIZE_TO_PAGES (DevInfoLength
));
353 // Go through all the devices managed by the SSC PPI instance.
355 Status
= SscPpi
->GetNumberofDevices (SscPpi
, &SscDeviceNum
);
356 if (EFI_ERROR (Status
)) {
359 for (SscDeviceIndex
= 1; SscDeviceIndex
<= SscDeviceNum
; SscDeviceIndex
++) {
360 Status
= SscPpi
->GetDevicePath (
363 &SscDevicePathLength
,
366 if (SscDevicePathLength
<= sizeof (EFI_DEVICE_PATH_PROTOCOL
)) {
368 // Device path validity check.
374 // Search the device in the restored LockBox.
376 for (DevInfo
= (OPAL_DEVICE_LOCKBOX_DATA
*) DevInfoBuffer
;
377 (UINTN
) DevInfo
< ((UINTN
) DevInfoBuffer
+ DevInfoLength
);
378 DevInfo
= (OPAL_DEVICE_LOCKBOX_DATA
*) ((UINTN
) DevInfo
+ DevInfo
->Length
)) {
380 // Find the matching device.
382 if ((DevInfo
->DevicePathLength
>= SscDevicePathLength
) &&
386 SscDevicePathLength
- sizeof (EFI_DEVICE_PATH_PROTOCOL
)) == 0)) {
387 OpalDev
.Signature
= OPAL_PEI_DEVICE_SIGNATURE
;
388 OpalDev
.Sscp
.ReceiveData
= SecurityReceiveData
;
389 OpalDev
.Sscp
.SendData
= SecuritySendData
;
390 OpalDev
.Device
= DevInfo
;
391 OpalDev
.Context
= NULL
;
392 OpalDev
.SscPpi
= SscPpi
;
393 OpalDev
.DeviceIndex
= SscDeviceIndex
;
394 UnlockOpalPassword (&OpalDev
);
401 ZeroMem (DevInfoBuffer
, DevInfoLength
);
402 FreePages (DevInfoBuffer
, EFI_SIZE_TO_PAGES (DevInfoLength
));
407 One notified function at the installation of EDKII_PEI_STORAGE_SECURITY_CMD_PPI.
408 It is to unlock OPAL password for S3.
410 @param[in] PeiServices Indirect reference to the PEI Services Table.
411 @param[in] NotifyDescriptor Address of the notification descriptor data structure.
412 @param[in] Ppi Address of the PPI that was installed.
414 @return Status of the notification.
415 The status code returned from this function is ignored.
420 OpalPasswordStorageSecurityPpiNotify (
421 IN EFI_PEI_SERVICES
**PeiServices
,
422 IN EFI_PEI_NOTIFY_DESCRIPTOR
*NotifyDesc
,
426 DEBUG ((DEBUG_INFO
, "%a entered at S3 resume!\n", __FUNCTION__
));
428 UnlockOpalPasswordDevices ((EDKII_PEI_STORAGE_SECURITY_CMD_PPI
*) Ppi
);
430 DEBUG ((DEBUG_INFO
, "%a exit at S3 resume!\n", __FUNCTION__
));
436 EFI_PEI_NOTIFY_DESCRIPTOR mOpalPasswordStorageSecurityPpiNotifyDesc
= {
437 (EFI_PEI_PPI_DESCRIPTOR_NOTIFY_CALLBACK
| EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST
),
438 &gEdkiiPeiStorageSecurityCommandPpiGuid
,
439 OpalPasswordStorageSecurityPpiNotify
444 Main entry for this module.
446 @param FileHandle Handle of the file being invoked.
447 @param PeiServices Pointer to PEI Services table.
449 @return Status from PeiServicesNotifyPpi.
454 OpalPasswordPeiInit (
455 IN EFI_PEI_FILE_HANDLE FileHandle
,
456 IN CONST EFI_PEI_SERVICES
**PeiServices
460 EFI_BOOT_MODE BootMode
;
462 Status
= PeiServicesGetBootMode (&BootMode
);
463 if ((EFI_ERROR (Status
)) || (BootMode
!= BOOT_ON_S3_RESUME
)) {
464 return EFI_UNSUPPORTED
;
467 DEBUG ((DEBUG_INFO
, "%a: Enters in S3 path.\n", __FUNCTION__
));
469 Status
= PeiServicesNotifyPpi (&mOpalPasswordStorageSecurityPpiNotifyDesc
);
470 ASSERT_EFI_ERROR (Status
);