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.
15 #include <Library/BaseLib.h>
16 #include <Library/DebugLib.h>
17 #include <Library/TcgStorageOpalLib.h>
21 Creates a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts device using Admin SP Revert method.
23 @param[in] Session, The session info for one opal device.
24 @param[in] Psid PSID of device to revert.
25 @param[in] PsidLength Length of PSID in bytes.
31 OPAL_SESSION
*Session
,
42 Ret
= OpalStartSession(
48 OPAL_ADMIN_SP_PSID_AUTHORITY
,
50 if (Ret
== TcgResultSuccess
&& MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
) {
51 Ret
= OpalPsidRevert(Session
);
52 if (Ret
!= TcgResultSuccess
) {
54 // If revert was successful, session was already ended by TPer, so only end session on failure
56 OpalEndSession(Session
);
60 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
61 Ret
= TcgResultFailure
;
68 Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY,
69 sets the OPAL_UID_ADMIN_SP_C_PIN_SID column with the new password,
70 and activates the locking SP to copy SID PIN to Admin1 Locking SP PIN
72 @param[in] Session, The session info for one opal device.
73 @param[in] GeneratedSid Generated SID of disk
74 @param[in] SidLength Length of generatedSid in bytes
75 @param[in] Password New admin password to set
76 @param[in] PassLength Length of password in bytes
81 OpalUtilSetAdminPasswordAsSid(
82 OPAL_SESSION
*Session
,
83 const VOID
*GeneratedSid
,
93 NULL_CHECK(GeneratedSid
);
96 Ret
= OpalStartSession(
102 OPAL_ADMIN_SP_SID_AUTHORITY
,
105 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
106 DEBUG ((DEBUG_INFO
, "start session with admin SP as SID authority failed: Ret=%d MethodStatus=%u\n", Ret
, MethodStatus
));
111 // 1. Update SID = new Password
113 Ret
= OpalSetPassword(
115 OPAL_UID_ADMIN_SP_C_PIN_SID
,
121 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
122 OpalEndSession(Session
);
123 DEBUG ((DEBUG_INFO
, "set Password failed: Ret=%d MethodStatus=%u\n", Ret
, MethodStatus
));
128 // 2. Activate locking SP
130 Ret
= OpalActivateLockingSp(Session
, &MethodStatus
);
131 OpalEndSession(Session
);
132 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
133 DEBUG ((DEBUG_INFO
, "activate locking SP failed: Ret=%d MethodStatus=%u\n", Ret
, MethodStatus
));
138 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
139 Ret
= TcgResultFailure
;
146 Opens a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY,
147 and updates the specified locking range with the provided column values
149 @param[in] Session, The session info for one opal device.
150 @param[in] Password New admin password to set
151 @param[in] PassLength Length of password in bytes
152 @param[in] LockingRangeUid Locking range UID to set values
153 @param[in] RangeStart Value to set RangeStart column for Locking Range
154 @param[in] RangeLength Value to set RangeLength column for Locking Range
155 @param[in] ReadLockEnabled Value to set readLockEnabled column for Locking Range
156 @param[in] WriteLockEnabled Value to set writeLockEnabled column for Locking Range
157 @param[in] ReadLocked Value to set ReadLocked column for Locking Range
158 @param[in] WriteLocked Value to set WriteLocked column for Locking Range
163 OpalUtilSetOpalLockingRange(
164 OPAL_SESSION
*Session
,
165 const VOID
*Password
,
167 TCG_UID LockingRangeUid
,
170 BOOLEAN ReadLockEnabled
,
171 BOOLEAN WriteLockEnabled
,
180 NULL_CHECK(Password
);
183 // Start session with Locking SP using current admin Password
185 Ret
= OpalStartSession(
191 OPAL_LOCKING_SP_ADMIN1_AUTHORITY
,
193 if ((Ret
!= TcgResultSuccess
) || (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
)) {
194 DEBUG ((DEBUG_INFO
, "start session with locking SP failed: Ret=%d MethodStatus=%u\n", Ret
, MethodStatus
));
199 // Enable locking range
201 Ret
= OpalSetLockingRange(
212 OpalEndSession(Session
);
213 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
214 DEBUG ((DEBUG_INFO
, "set locking range failed: Ret=%d MethodStatus=0x%x\n", Ret
, MethodStatus
));
218 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
219 Ret
= TcgResultFailure
;
225 Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY,
226 sets OPAL_UID_ADMIN_SP_C_PIN_SID with the new password,
227 and sets OPAL_LOCKING_SP_C_PIN_ADMIN1 with the new password.
229 @param[in] Session, The session info for one opal device.
230 @param[in] OldPassword Current admin password
231 @param[in] OldPasswordLength Length of current admin password in bytes
232 @param[in] NewPassword New admin password to set
233 @param[in] NewPasswordLength Length of new password in bytes
238 OpalUtilSetAdminPassword(
239 OPAL_SESSION
*Session
,
240 const VOID
*OldPassword
,
241 UINT32 OldPasswordLength
,
242 const VOID
*NewPassword
,
243 UINT32 NewPasswordLength
250 NULL_CHECK(OldPassword
);
251 NULL_CHECK(NewPassword
);
256 Ret
= OpalStartSession(
262 OPAL_ADMIN_SP_SID_AUTHORITY
,
265 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
266 DEBUG ((DEBUG_INFO
, "start session with admin SP using old Password failed\n"));
271 // Update SID = new pw
273 Ret
= OpalSetPassword(Session
, OPAL_UID_ADMIN_SP_C_PIN_SID
, NewPassword
, NewPasswordLength
, &MethodStatus
);
274 OpalEndSession(Session
);
275 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
276 DEBUG ((DEBUG_INFO
, "set new admin SP Password failed\n"));
280 Ret
= OpalStartSession(
286 OPAL_LOCKING_SP_ADMIN1_AUTHORITY
,
289 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
290 DEBUG ((DEBUG_INFO
, "start session with locking SP using old Password failed\n"));
295 // Update admin locking SP to new pw
297 Ret
= OpalSetPassword(Session
, OPAL_LOCKING_SP_C_PIN_ADMIN1
, NewPassword
, NewPasswordLength
, &MethodStatus
);
298 OpalEndSession(Session
);
299 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
300 DEBUG ((DEBUG_INFO
, "set new locking SP Password failed\n"));
305 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
306 Ret
= TcgResultFailure
;
312 Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY
313 and sets the User1 SP authority to enabled and sets the User1 password.
315 @param[in] Session, The session info for one opal device.
316 @param[in] OldPassword Current admin password
317 @param[in] OldPasswordLength Length of current admin password in bytes
318 @param[in] NewPassword New admin password to set
319 @param[in] NewPasswordLength Length of new password in bytes
324 OpalUtilSetUserPassword(
325 OPAL_SESSION
*Session
,
326 const VOID
*OldPassword
,
327 UINT32 OldPasswordLength
,
328 const VOID
*NewPassword
,
329 UINT32 NewPasswordLength
336 NULL_CHECK(OldPassword
);
337 NULL_CHECK(NewPassword
);
340 // See if updating user1 authority
342 Ret
= OpalStartSession(
348 OPAL_LOCKING_SP_USER1_AUTHORITY
,
351 if (Ret
== TcgResultSuccess
&& MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
) {
352 Ret
= OpalSetPassword(
354 OPAL_LOCKING_SP_C_PIN_USER1
,
359 OpalEndSession(Session
);
360 if (Ret
== TcgResultSuccess
&& MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
) {
366 // Setting Password for first time or setting Password as admin
370 // Start session with Locking SP using current admin Password
372 Ret
= OpalStartSession(
378 OPAL_LOCKING_SP_ADMIN1_AUTHORITY
,
381 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
382 DEBUG ((DEBUG_INFO
, "StartSession with locking SP as admin1 authority failed\n"));
387 // Enable User1 and set its PIN
389 Ret
= OpalSetLockingSpAuthorityEnabledAndPin(
391 OPAL_LOCKING_SP_C_PIN_USER1
,
392 OPAL_LOCKING_SP_USER1_AUTHORITY
,
397 OpalEndSession(Session
);
398 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
399 DEBUG ((DEBUG_INFO
, "OpalSetLockingSpAuthorityEnabledAndPin failed\n"));
404 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
405 Ret
= TcgResultFailure
;
411 Verify whether user input the correct password.
413 @param[in] Session, The session info for one opal device.
414 @param[in] Password Admin password
415 @param[in] PasswordLength Length of password in bytes
416 @param[in/out] HostSigningAuthority Use the Host signing authority type.
421 OpalUtilVerifyPassword (
422 OPAL_SESSION
*Session
,
423 const VOID
*Password
,
424 UINT32 PasswordLength
,
425 TCG_UID HostSigningAuthority
432 NULL_CHECK(Password
);
434 Ret
= OpalStartSession(
440 HostSigningAuthority
,
442 if (Ret
== TcgResultSuccess
&& MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
) {
443 OpalEndSession(Session
);
444 return TcgResultSuccess
;
447 return TcgResultFailure
;
451 Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY
452 and generates a new global locking range key to erase the Data.
454 @param[in] Session, The session info for one opal device.
455 @param[in] Password Admin or user password
456 @param[in] PasswordLength Length of password in bytes
457 @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
463 OPAL_SESSION
*Session
,
464 const VOID
*Password
,
465 UINT32 PasswordLength
,
466 BOOLEAN
*PasswordFailed
473 NULL_CHECK(Password
);
474 NULL_CHECK(PasswordFailed
);
477 // Try to generate a new key with admin1
479 Ret
= OpalStartSession(
485 OPAL_LOCKING_SP_ADMIN1_AUTHORITY
,
489 if (Ret
== TcgResultSuccess
&& MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
) {
490 Ret
= OpalGlobalLockingRangeGenKey(Session
, &MethodStatus
);
491 *PasswordFailed
= FALSE
;
492 OpalEndSession(Session
);
495 // Try to generate a new key with user1
497 Ret
= OpalStartSession(
503 OPAL_LOCKING_SP_USER1_AUTHORITY
,
507 if (Ret
== TcgResultSuccess
&& MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
) {
508 Ret
= OpalGlobalLockingRangeGenKey(Session
, &MethodStatus
);
509 *PasswordFailed
= FALSE
;
510 OpalEndSession(Session
);
512 *PasswordFailed
= TRUE
;
516 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
517 Ret
= TcgResultFailure
;
523 Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY and disables the User1 authority.
525 @param[in] Session, The session info for one opal device.
526 @param[in] Password Admin password
527 @param[in] PasswordLength Length of password in bytes
528 @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
534 OPAL_SESSION
*Session
,
535 const VOID
*Password
,
536 UINT32 PasswordLength
,
537 BOOLEAN
*PasswordFailed
544 NULL_CHECK(Password
);
545 NULL_CHECK(PasswordFailed
);
548 // Start session with Locking SP using current admin Password
550 Ret
= OpalStartSession(
556 OPAL_LOCKING_SP_ADMIN1_AUTHORITY
,
559 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
560 DEBUG ((DEBUG_INFO
, "StartSession with Locking SP as Admin1 failed\n"));
561 *PasswordFailed
= TRUE
;
565 *PasswordFailed
= FALSE
;
566 Ret
= OpalDisableUser(Session
, &MethodStatus
);
567 OpalEndSession(Session
);
570 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
571 Ret
= TcgResultFailure
;
577 Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts the device using the RevertSP method.
579 @param[in] Session, The session info for one opal device.
580 @param[in] KeepUserData TRUE to keep existing Data on the disk, or FALSE to erase it
581 @param[in] Password Admin password
582 @param[in] PasswordLength Length of password in bytes
583 @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
584 @param[in] Msid Msid info.
585 @param[in] MsidLength Msid data length.
591 OPAL_SESSION
*Session
,
592 BOOLEAN KeepUserData
,
593 const VOID
*Password
,
594 UINT32 PasswordLength
,
595 BOOLEAN
*PasswordFailed
,
605 NULL_CHECK(Password
);
606 NULL_CHECK(PasswordFailed
);
608 Ret
= OpalStartSession(
614 OPAL_LOCKING_SP_ADMIN1_AUTHORITY
,
618 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
619 DEBUG ((DEBUG_INFO
, "error starting session: Ret=%d, MethodStatus=%u\n", Ret
, MethodStatus
));
620 *PasswordFailed
= TRUE
;
624 *PasswordFailed
= FALSE
;
626 // Try to revert with admin1
628 Ret
= OpalAdminRevert(Session
, KeepUserData
, &MethodStatus
);
629 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
631 // Device ends the session on successful revert, so only call OpalEndSession when fail.
633 DEBUG ((DEBUG_INFO
, "OpalAdminRevert as admin failed\n"));
634 OpalEndSession(Session
);
637 Ret
= OpalUtilSetSIDtoMSID (Session
, Password
, PasswordLength
, Msid
, MsidLength
);
640 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
641 Ret
= TcgResultFailure
;
647 After revert success, set SID to MSID.
649 @param Session, The session info for one opal device.
650 @param Password, Input password info.
651 @param PasswordLength, Input password length.
652 @param Msid Msid info.
653 @param MsidLength Msid data length.
658 OpalUtilSetSIDtoMSID (
659 OPAL_SESSION
*Session
,
660 const VOID
*Password
,
661 UINT32 PasswordLength
,
671 NULL_CHECK(Password
);
674 // Start session with admin sp to update SID to MSID
676 Ret
= OpalStartSession(
682 OPAL_ADMIN_SP_SID_AUTHORITY
,
685 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
692 Ret
= OpalSetPassword(Session
, OPAL_UID_ADMIN_SP_C_PIN_SID
, Msid
, MsidLength
, &MethodStatus
);
693 OpalEndSession(Session
);
696 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
697 Ret
= TcgResultFailure
;
704 Update global locking range.
706 @param Session, The session info for one opal device.
707 @param Password, Input password info.
708 @param PasswordLength, Input password length.
709 @param ReadLocked, Read lock info.
710 @param WriteLocked write lock info.
715 OpalUtilUpdateGlobalLockingRange(
716 OPAL_SESSION
*Session
,
717 const VOID
*Password
,
718 UINT32 PasswordLength
,
727 NULL_CHECK(Password
);
730 // Try to start session with Locking SP as admin1 authority
732 Ret
= OpalStartSession(
738 OPAL_LOCKING_SP_ADMIN1_AUTHORITY
,
741 if (Ret
== TcgResultSuccess
&& MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
) {
742 Ret
= OpalUpdateGlobalLockingRange(
748 OpalEndSession(Session
);
749 if (Ret
== TcgResultSuccess
&& MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
) {
754 if (MethodStatus
== TCG_METHOD_STATUS_CODE_AUTHORITY_LOCKED_OUT
) {
755 DEBUG ((DEBUG_INFO
, "unlock as admin failed with AUTHORITY_LOCKED_OUT\n"));
760 // Try user1 authority
762 Ret
= OpalStartSession(
768 OPAL_LOCKING_SP_USER1_AUTHORITY
,
771 if (Ret
!= TcgResultSuccess
|| MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
772 DEBUG ((DEBUG_INFO
, "StartSession with Locking SP as User1 failed\n"));
776 Ret
= OpalUpdateGlobalLockingRange(Session
, ReadLocked
, WriteLocked
, &MethodStatus
);
777 OpalEndSession(Session
);
780 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
781 Ret
= TcgResultFailure
;
787 Update global locking range.
789 @param Session, The session info for one opal device.
790 @param Msid, The data buffer to save Msid info.
791 @param MsidBufferLength, The data buffer length for Msid.
792 @param MsidLength, The actual data length for Msid.
798 OPAL_SESSION
*Session
,
800 UINT32 MsidBufferLength
,
809 NULL_CHECK(MsidLength
);
811 Ret
= OpalStartSession(
820 if ((Ret
== TcgResultSuccess
) && (MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
)) {
821 Ret
= OpalGetMsid (Session
, MsidBufferLength
, Msid
, MsidLength
);
822 OpalEndSession (Session
);
825 if (MethodStatus
!= TCG_METHOD_STATUS_CODE_SUCCESS
) {
826 Ret
= TcgResultFailure
;
834 The function determines who owns the device by attempting to start a session with different credentials.
835 If the SID PIN matches the MSID PIN, the no one owns the device.
836 If the SID PIN matches the ourSidPin, then "Us" owns the device. Otherwise it is unknown.
839 @param[in] Session The session info for one opal device.
840 @param Msid, The Msid info.
841 @param MsidLength, The data length for Msid.
846 OpalUtilDetermineOwnership(
847 OPAL_SESSION
*Session
,
854 OPAL_OWNER_SHIP Owner
;
856 if ((Session
== NULL
) || (Msid
== NULL
)) {
857 return OpalOwnershipUnknown
;
860 Owner
= OpalOwnershipUnknown
;
862 // Start Session as SID_UID with ADMIN_SP using MSID PIN
864 Ret
= OpalStartSession(
870 OPAL_ADMIN_SP_SID_AUTHORITY
,
872 if ((Ret
== TcgResultSuccess
) && (MethodStatus
== TCG_METHOD_STATUS_CODE_SUCCESS
)) {
874 // now we know that SID PIN == MSID PIN
876 Owner
= OpalOwnershipNobody
;
878 OpalEndSession(Session
);
886 The function returns if admin password exists.
888 @param[in] OwnerShip The owner ship of the opal device.
889 @param[in] LockingFeature The locking info of the opal device.
891 @retval TRUE Admin password existed.
892 @retval FALSE Admin password not existed.
897 OpalUtilAdminPasswordExists(
899 IN TCG_LOCKING_FEATURE_DESCRIPTOR
*LockingFeature
902 NULL_CHECK(LockingFeature
);
904 // if it is Unknown who owns the device
905 // then someone has set password previously through our UI
906 // because the SID would no longer match the generated SID (ownership us)
907 // or someone has set password using 3rd party software
910 // Locking sp enabled is checked b/c it must be enabled to change the PIN of the Admin1.
912 return (OwnerShip
== OpalOwnershipUnknown
&& LockingFeature
->LockingEnabled
);