2 Public API for Opal Core library.
4 Copyright (c) 2016, 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
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.
18 #include <IndustryStandard/TcgStorageOpal.h>
20 #include <Library/TcgStorageCoreLib.h>
21 #include <Protocol/StorageSecurityCommand.h>
27 // Opal SSC 1 support (0 - not supported, 1 - supported)
32 // Opal SSC 2support (0 - not supported, 1 - supported)
37 // Opal SSC Lite support (0 - not supported, 1 - supported)
39 UINT32 OpalSscLite
: 1;
42 // Pyrite SSC support (0 - not supported, 1 - supported)
47 // Security protocol 1 support (0 - not supported, 1 - supported)
52 // Security protocol 2 support (0 - not supported, 1 - supported)
57 // Security protocol IEEE1667 support (0 - not supported, 1 - supported)
59 UINT32 SpIeee1667
: 1;
62 // Media encryption supported (0 - not supported, 1 - supported)
64 UINT32 MediaEncryption
: 1;
67 // Initial C_PIN_SID PIN Indicator
68 // 0 - The initial C_PIN_SID PIN value is NOT equal to the C_PIN_MSID PIN value
69 // 1 - The initial C_PIN_SID PIN value is equal to the C_PIN_MSID PIN value
71 UINT32 InitCpinIndicator
: 1;
74 // Behavior of C_PIN_SID PIN upon TPer Revert
75 // 0 - The initial C_PIN_SID PIN value is NOT equal to the C_PIN_MSID PIN value
76 // 1 - The initial C_PIN_SID PIN value is equal to the C_PIN_MSID PIN value
78 UINT32 CpinUponRevert
: 1;
81 // Media encryption supported (0 - not supported, 1 - supported)
85 } OPAL_DISK_SUPPORT_ATTRIBUTE
;
88 // Opal device ownership type
89 // The type indicates who was the determined owner of the device.
93 // Represents the device ownership is unknown because starting a session as the SID authority with the ADMIN SP
94 //was unsuccessful with the provided PIN
99 // Represents that the ADMIN SP SID authority contains the same PIN as the MSID PIN
105 // Structure that is used to represent an Opal session.
106 // The structure must be initialized by calling OpalStartSession before being used as a parameter
107 // for any other Opal function.
108 // This structure should NOT be directly modified by the client of this library.
112 UINT32 HostSessionId
;
113 UINT32 TperSessionId
;
114 UINT16 ComIdExtension
;
116 UINT16 OpalBaseComId
;
118 EFI_STORAGE_SECURITY_COMMAND_PROTOCOL
*Sscp
;
125 The function fills in the provided Buffer with the supported protocol list
126 of the device specified.
128 @param[in] Session OPAL_SESSION data.
129 @param[in] BufferSize Size of Buffer provided (in bytes)
130 @param[in] BuffAddress Buffer address to fill with security protocol list
135 OpalRetrieveSupportedProtocolList(
136 OPAL_SESSION
*Session
,
143 The function fills in the provided Buffer with the level 0 discovery Header
144 of the device specified.
146 @param[in] Session OPAL_SESSION data.
147 @param[in] BufferSize Size of Buffer provided (in bytes)
148 @param[in] BuffAddress Buffer address to fill with Level 0 Discovery response
153 OpalRetrieveLevel0DiscoveryHeader(
154 OPAL_SESSION
*Session
,
160 Starts a session with a security provider (SP).
162 If a session is started successfully, the caller must end the session with OpalEndSession when finished
163 performing Opal actions.
165 @param[in/out] Session OPAL_SESSION to initialize.
166 @param[in] SpId Security provider ID to start the session with.
167 @param[in] Write Whether the session should be read-only (FALSE) or read/write (TRUE).
168 @param[in] HostChallengeLength Length of the host challenge. Length should be 0 if hostChallenge is NULL
169 @param[in] HostChallenge Host challenge for Host Signing Authority. If NULL, then no Host Challenge will be sent.
170 @param[in] HostSigningAuthority Host Signing Authority used for start session. If NULL, then no Host Signing Authority will be sent.
171 @param[in/out] MethodStatus Status of the StartSession method; only valid if TcgResultSuccess is returned.
173 @return TcgResultSuccess indicates that the function completed without any internal errors.
174 The caller must inspect the MethodStatus field to determine whether the method completed successfully.
180 OPAL_SESSION
*Session
,
183 UINT32 HostChallengeLength
,
184 const VOID
*HostChallenge
,
185 TCG_UID HostSigningAuthority
,
190 Close a session opened with OpalStartSession.
192 @param[in/out] Session OPAL_SESSION to end.
198 OPAL_SESSION
*Session
203 Reverts device using Admin SP Revert method.
205 @param[in] AdminSpSession OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY to perform PSID revert.
211 OPAL_SESSION
*AdminSpSession
217 The function retrieves the MSID from the device specified
219 @param[in] AdminSpSession OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY to perform PSID revert.
220 @param[in] MsidBufferSize Allocated buffer size (in bytes) for MSID allocated by caller
221 @param[in] Msid Variable length byte sequence representing MSID of device
222 @param[in] MsidLength Actual length of MSID retrieved from device
228 OPAL_SESSION
*AdminSpSession
,
229 UINT32 MsidBufferSize
,
236 The function activates the Locking SP.
237 Once activated, per Opal spec, the ADMIN SP SID PIN is copied over to the ADMIN1 LOCKING SP PIN.
238 If the Locking SP is already enabled, then TcgResultSuccess is returned and no action occurs.
240 @param[in] AdminSpSession OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY to activate Locking SP
241 @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
246 OpalActivateLockingSp(
247 OPAL_SESSION
*AdminSpSession
,
254 The function sets the PIN column of the specified cpinRowUid (authority) with the newPin value.
256 @param[in/out] Session OPAL_SESSION to set password
257 @param[in] CpinRowUid UID of row (authority) to update PIN column
258 @param[in] NewPin New Pin to set for cpinRowUid specified
259 @param[in] NewPinLength Length in bytes of newPin
260 @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
266 OPAL_SESSION
*Session
,
275 The function retrieves the active key of the global locking range
276 and calls the GenKey method on the active key retrieved.
278 @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
279 @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
284 OpalGlobalLockingRangeGenKey(
285 OPAL_SESSION
*LockingSpSession
,
292 The function updates the ReadLocked and WriteLocked columns of the Global Locking Range.
293 This function is required for a user1 authority, since a user1 authority shall only have access to ReadLocked and WriteLocked columns
294 (not ReadLockEnabled and WriteLockEnabled columns).
296 @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
297 @param[in] ReadLocked Value to set ReadLocked column for Global Locking Range
298 @param[in] WriteLocked Value to set WriteLocked column for Global Locking Range
299 @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
304 OpalUpdateGlobalLockingRange(
305 OPAL_SESSION
*LockingSpSession
,
314 The function updates the RangeStart, RangeLength, ReadLockedEnabled, WriteLockedEnabled, ReadLocked and WriteLocked columns
315 of the specified Locking Range. This function requires admin authority of a locking SP session.
317 @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
318 @param[in] LockingRangeUid Locking range UID to set values
319 @param[in] RangeStart Value to set RangeStart column for Locking Range
320 @param[in] RangeLength Value to set RangeLength column for Locking Range
321 @param[in] ReadLockEnabled Value to set readLockEnabled column for Locking Range
322 @param[in] WriteLockEnabled Value to set writeLockEnabled column for Locking Range
323 @param[in] ReadLocked Value to set ReadLocked column for Locking Range
324 @param[in] WriteLocked Value to set WriteLocked column for Locking Range
325 @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
331 OPAL_SESSION
*LockingSpSession
,
332 TCG_UID LockingRangeUid
,
335 BOOLEAN ReadLockEnabled
,
336 BOOLEAN WriteLockEnabled
,
344 The function sets the Enabled column to TRUE for the authorityUid provided and updates the PIN column for the cpinRowUid provided
345 using the newPin provided. AuthorityUid and cpinRowUid should describe the same authority.
347 @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to update
348 @param[in] CpinRowUid Row UID of C_PIN table of Locking SP to update PIN
349 @param[in] AuthorityUid UID of Locking SP authority to update Pin column with
350 @param[in] NewPin New Password used to set Pin column
351 @param[in] NewPinLength Length in bytes of new password
352 @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
357 OpalSetLockingSpAuthorityEnabledAndPin(
358 OPAL_SESSION
*LockingSpSession
,
360 TCG_UID AuthorityUid
,
369 The function sets the Enabled column to FALSE for the USER1 authority.
371 @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to disable User1
372 @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
378 OPAL_SESSION
*LockingSpSession
,
385 The function calls the Admin SP RevertSP method on the Locking SP. If KeepUserData is True, then the optional parameter
386 to keep the user data is set to True, otherwise the optional parameter is not provided.
388 @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to revertSP
389 @param[in] KeepUserData Specifies whether or not to keep user data when performing RevertSP action. True = keeps user data.
390 @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
396 OPAL_SESSION
*LockingSpSession
,
397 BOOLEAN KeepUserData
,
404 The function retrieves the TryLimit column for the specified rowUid (authority).
406 @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve try limit
407 @param[in] RowUid Row UID of the Locking SP C_PIN table to retrieve TryLimit column
408 @param[in/out] TryLimit Value from TryLimit column
414 OPAL_SESSION
*LockingSpSession
,
422 The function populates the CreateStruct with a payload that will retrieve the global locking range active key.
423 It is intended to be called with a session that is already started with a valid credential.
424 The function does not send the payload.
426 @param[in] Session OPAL_SESSION to populate command for, needs comId
427 @param[in/out] CreateStruct Structure to populate with encoded TCG command
428 @param[in/out] Size Size in bytes of the command created.
433 OpalCreateRetrieveGlobalLockingRangeActiveKey(
434 const OPAL_SESSION
*Session
,
435 TCG_CREATE_STRUCT
*CreateStruct
,
442 The function acquires the activeKey specified for the Global Locking Range from the parseStruct.
444 @param[in] ParseStruct Structure that contains the device's response with the activekey
445 @param[in/out] ActiveKey The UID of the active key retrieved
450 OpalParseRetrieveGlobalLockingRangeActiveKey(
451 TCG_PARSE_STRUCT
*ParseStruct
,
457 Get the support attribute info.
459 @param[in] Session OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve info.
460 @param[in/out] LockingFeature Return the Locking info.
466 OPAL_SESSION
*Session
,
467 TCG_LOCKING_FEATURE_DESCRIPTOR
*LockingFeature
472 The function determines whether or not all of the requirements for the Opal Feature (not full specification)
473 are met by the specified device.
475 @param[in] SupportedAttributes Opal device attribute.
480 OpalFeatureSupported(
481 OPAL_DISK_SUPPORT_ATTRIBUTE
*SupportedAttributes
486 The function returns whether or not the device is Opal Enabled.
487 TRUE means that the device is partially or fully locked.
488 This will perform a Level 0 Discovery and parse the locking feature descriptor
490 @param[in] SupportedAttributes Opal device attribute.
491 @param[in] LockingFeature Opal device locking status.
498 OPAL_DISK_SUPPORT_ATTRIBUTE
*SupportedAttributes
,
499 TCG_LOCKING_FEATURE_DESCRIPTOR
*LockingFeature
504 The function returns whether or not the device is Opal Locked.
505 TRUE means that the device is partially or fully locked.
506 This will perform a Level 0 Discovery and parse the locking feature descriptor
508 @param[in] SupportedAttributes Opal device attribute.
509 @param[in] LockingFeature Opal device locking status.
514 OPAL_DISK_SUPPORT_ATTRIBUTE
*SupportedAttributes
,
515 TCG_LOCKING_FEATURE_DESCRIPTOR
*LockingFeature
519 Trig the block sid action.
521 @param[in] Session OPAL_SESSION to populate command for, needs comId
522 @param[in] HardwareReset Whether need to do hardware reset.
528 OPAL_SESSION
*Session
,
529 BOOLEAN HardwareReset
534 Get the support attribute info.
536 @param[in] Session OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve info.
537 @param[in/out] SupportedAttributes Return the support attribute info.
538 @param[out] OpalBaseComId Return the base com id info.
543 OpalGetSupportedAttributesInfo(
544 OPAL_SESSION
*Session
,
545 OPAL_DISK_SUPPORT_ATTRIBUTE
*SupportedAttributes
,
546 UINT16
*OpalBaseComId
550 Creates a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts device using Admin SP Revert method.
552 @param[in] AdminSpSession OPAL_SESSION to populate command for, needs comId
553 @param[in] Psid PSID of device to revert.
554 @param[in] PsidLength Length of PSID in bytes.
560 OPAL_SESSION
*AdminSpSession
,
566 Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY,
567 sets the OPAL_UID_ADMIN_SP_C_PIN_SID column with the new password,
568 and activates the locking SP to copy SID PIN to Admin1 Locking SP PIN.
570 @param[in] AdminSpSession OPAL_SESSION to populate command for, needs comId
571 @param[in] GeneratedSid Generated SID of disk
572 @param[in] SidLength Length of generatedSid in bytes
573 @param[in] Password New admin password to set
574 @param[in] PassLength Length of password in bytes
579 OpalUtilSetAdminPasswordAsSid(
580 OPAL_SESSION
*AdminSpSession
,
581 const VOID
*GeneratedSid
,
583 const VOID
*Password
,
589 Opens a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY,
590 and updates the specified locking range with the provided column values.
592 @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
593 @param[in] Password New admin password to set
594 @param[in] PassLength Length of password in bytes
595 @param[in] LockingRangeUid Locking range UID to set values
596 @param[in] RangeStart Value to set RangeStart column for Locking Range
597 @param[in] RangeLength Value to set RangeLength column for Locking Range
598 @param[in] ReadLockEnabled Value to set readLockEnabled column for Locking Range
599 @param[in] WriteLockEnabled Value to set writeLockEnabled column for Locking Range
600 @param[in] ReadLocked Value to set ReadLocked column for Locking Range
601 @param[in] WriteLocked Value to set WriteLocked column for Locking Range
606 OpalUtilSetOpalLockingRange(
607 OPAL_SESSION
*LockingSpSession
,
608 const VOID
*Password
,
610 TCG_UID LockingRangeUid
,
613 BOOLEAN ReadLockEnabled
,
614 BOOLEAN WriteLockEnabled
,
620 Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY,
621 sets OPAL_UID_ADMIN_SP_C_PIN_SID with the new password,
622 and sets OPAL_LOCKING_SP_C_PIN_ADMIN1 with the new password.
624 @param[in] AdminSpSession OPAL_SESSION to populate command for, needs comId
625 @param[in] OldPassword Current admin password
626 @param[in] OldPasswordLength Length of current admin password in bytes
627 @param[in] NewPassword New admin password to set
628 @param[in] NewPasswordLength Length of new password in bytes
633 OpalUtilSetAdminPassword(
634 OPAL_SESSION
*AdminSpSession
,
635 const VOID
*OldPassword
,
636 UINT32 OldPasswordLength
,
637 const VOID
*NewPassword
,
638 UINT32 NewPasswordLength
642 Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY
643 and sets the User1 SP authority to enabled and sets the User1 password.
645 @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
646 @param[in] OldPassword Current admin password
647 @param[in] OldPasswordLength Length of current admin password in bytes
648 @param[in] NewPassword New admin password to set
649 @param[in] NewPasswordLength Length of new password in bytes
654 OpalUtilSetUserPassword(
655 OPAL_SESSION
*LockingSpSession
,
656 const VOID
*OldPassword
,
657 UINT32 OldPasswordLength
,
658 const VOID
*NewPassword
,
659 UINT32 NewPasswordLength
663 Verify whether user input the correct password.
665 @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
666 @param[in] Password Admin password
667 @param[in] PasswordLength Length of password in bytes
668 @param[in/out] HostSigningAuthority Use the Host signing authority type.
673 OpalUtilVerifyPassword (
674 OPAL_SESSION
*LockingSpSession
,
675 const VOID
*Password
,
676 UINT32 PasswordLength
,
677 TCG_UID HostSigningAuthority
681 Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY
682 and generates a new global locking range key to erase the Data.
684 @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
685 @param[in] Password Admin or user password
686 @param[in] PasswordLength Length of password in bytes
687 @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
693 OPAL_SESSION
*LockingSpSession
,
694 const VOID
*Password
,
695 UINT32 PasswordLength
,
696 BOOLEAN
*PasswordFailed
700 Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY and disables the User1 authority.
702 @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
703 @param[in] Password Admin password
704 @param[in] PasswordLength Length of password in bytes
705 @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
711 OPAL_SESSION
*LockingSpSession
,
712 const VOID
*Password
,
713 UINT32 PasswordLength
,
714 BOOLEAN
*PasswordFailed
718 Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts the device using the RevertSP method.
720 @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
721 @param[in] KeepUserData TRUE to keep existing Data on the disk, or FALSE to erase it
722 @param[in] Password Admin password
723 @param[in] PasswordLength Length of password in bytes
724 @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
725 @param[in] Msid Input Msid info.
726 @param[in] MsidLength Input Msid info length.
732 OPAL_SESSION
*LockingSpSession
,
733 BOOLEAN KeepUserData
,
734 const VOID
*Password
,
735 UINT32 PasswordLength
,
736 BOOLEAN
*PasswordFailed
,
742 After revert success, set SID to MSID.
744 @param[in] AdminSpSession OPAL_SESSION to populate command for, needs comId
745 @param Password, Input password info.
746 @param PasswordLength, Input password length.
747 @param[in] Msid Input Msid info.
748 @param[in] MsidLength Input Msid info length.
753 OpalUtilSetSIDtoMSID (
754 OPAL_SESSION
*AdminSpSession
,
755 const VOID
*Password
,
756 UINT32 PasswordLength
,
762 Update global locking range.
764 @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
765 @param Password, Input password info.
766 @param PasswordLength, Input password length.
767 @param ReadLocked, Read lock info.
768 @param WriteLocked write lock info.
773 OpalUtilUpdateGlobalLockingRange(
774 OPAL_SESSION
*LockingSpSession
,
775 const VOID
*Password
,
776 UINT32 PasswordLength
,
782 Update global locking range.
784 @param Session, The session info for one opal device.
785 @param Msid, The data buffer to save Msid info.
786 @param MsidBufferLength, The data buffer length for Msid.
787 @param MsidLength, The actual data length for Msid.
793 OPAL_SESSION
*Session
,
795 UINT32 MsidBufferLength
,
801 The function determines who owns the device by attempting to start a session with different credentials.
802 If the SID PIN matches the MSID PIN, the no one owns the device.
803 If the SID PIN matches the ourSidPin, then "Us" owns the device. Otherwise it is unknown.
806 @param[in] Session The session info for one opal device.
807 @param Msid, The Msid info.
808 @param MsidLength, The data length for Msid.
813 OpalUtilDetermineOwnership(
814 OPAL_SESSION
*Session
,
821 The function returns if admin password exists.
823 @param[in] OwnerShip The owner ship of the opal device.
824 @param[in] LockingFeature The locking info of the opal device.
826 @retval TRUE Admin password existed.
827 @retval FALSE Admin password not existed.
832 OpalUtilAdminPasswordExists(
834 IN TCG_LOCKING_FEATURE_DESCRIPTOR
*LockingFeature
837 #endif // _OPAL_CORE_H_