#include <Uefi.h>
#include <Library/BaseLib.h>
#include <Library/DebugLib.h>
#include <Library/TcgStorageOpalLib.h>
#include "TcgStorageOpalLibInternal.h"

Macros
#define	OPAL_MSID_LENGTH 128

Functions
TCG_RESULT EFIAPI	OpalUtilPsidRevert (OPAL_SESSION Session, const VOID Psid, UINT32 PsidLength)

TCG_RESULT EFIAPI	OpalUtilSetAdminPasswordAsSid (OPAL_SESSION Session, const VOID GeneratedSid, UINT32 SidLength, const VOID *Password, UINT32 PassLength)

TCG_RESULT EFIAPI	OpalUtilSetOpalLockingRange (OPAL_SESSION Session, const VOID Password, UINT32 PassLength, TCG_UID LockingRangeUid, UINT64 RangeStart, UINT64 RangeLength, BOOLEAN ReadLockEnabled, BOOLEAN WriteLockEnabled, BOOLEAN ReadLocked, BOOLEAN WriteLocked)

TCG_RESULT EFIAPI	OpalUtilSetAdminPassword (OPAL_SESSION Session, const VOID OldPassword, UINT32 OldPasswordLength, const VOID *NewPassword, UINT32 NewPasswordLength)

TCG_RESULT EFIAPI	OpalUtilSetUserPassword (OPAL_SESSION Session, const VOID OldPassword, UINT32 OldPasswordLength, const VOID *NewPassword, UINT32 NewPasswordLength)

TCG_RESULT EFIAPI	OpalUtilVerifyPassword (OPAL_SESSION Session, const VOID Password, UINT32 PasswordLength, TCG_UID HostSigningAuthority)

TCG_RESULT EFIAPI	OpalUtilSecureErase (OPAL_SESSION Session, const VOID Password, UINT32 PasswordLength, BOOLEAN *PasswordFailed)

TCG_RESULT EFIAPI	OpalUtilDisableUser (OPAL_SESSION Session, const VOID Password, UINT32 PasswordLength, BOOLEAN *PasswordFailed)

TCG_RESULT EFIAPI	OpalUtilRevert (OPAL_SESSION Session, BOOLEAN KeepUserData, const VOID Password, UINT32 PasswordLength, BOOLEAN PasswordFailed, UINT8 Msid, UINT32 MsidLength)

TCG_RESULT EFIAPI	OpalUtilSetSIDtoMSID (OPAL_SESSION Session, const VOID Password, UINT32 PasswordLength, UINT8 *Msid, UINT32 MsidLength)

TCG_RESULT EFIAPI	OpalUtilUpdateGlobalLockingRange (OPAL_SESSION Session, const VOID Password, UINT32 PasswordLength, BOOLEAN ReadLocked, BOOLEAN WriteLocked)

TCG_RESULT EFIAPI	OpalUtilGetMsid (OPAL_SESSION Session, UINT8 Msid, UINT32 MsidBufferLength, UINT32 *MsidLength)

OPAL_OWNER_SHIP EFIAPI	OpalUtilDetermineOwnership (OPAL_SESSION Session, UINT8 Msid, UINT32 MsidLength)

BOOLEAN EFIAPI	OpalUtilAdminPasswordExists (IN UINT16 OwnerShip, IN TCG_LOCKING_FEATURE_DESCRIPTOR *LockingFeature)

TCG_RESULT EFIAPI	OpalUtilGetActiveDataRemovalMechanism (OPAL_SESSION Session, const VOID GeneratedSid, UINT32 SidLength, UINT8 *ActiveDataRemovalMechanism)

UINT32	CalculateDataRemovalTime (IN BOOLEAN IsMinute, IN UINT16 Time)

UINT32	GetDataRemovalTime (IN UINT8 Index, IN DATA_REMOVAL_FEATURE_DESCRIPTOR *Descriptor)

TCG_RESULT EFIAPI	OpalUtilGetDataRemovalMechanismLists (IN OPAL_SESSION Session, OUT UINT32 RemovalMechanismLists)

UINT32	GetRevertTimeOut (IN OPAL_SESSION *Session)

Detailed Description

Public API for Opal Core library.

Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file TcgStorageOpalUtil.c.

Macro Definition Documentation

◆ OPAL_MSID_LENGTH

#define OPAL_MSID_LENGTH 128

Definition at line 14 of file TcgStorageOpalUtil.c.

Function Documentation

◆ CalculateDataRemovalTime()

UINT32 CalculateDataRemovalTime	(	IN BOOLEAN	IsMinute,
		IN UINT16	Time
	)

Calculate the estimated time.

Parameters

[in]	IsMinute	Whether the input time value is minute type or second type.
[in]	Time	The input time value.

Definition at line 1004 of file TcgStorageOpalUtil.c.

◆ GetDataRemovalTime()

UINT32 GetDataRemovalTime	(	IN UINT8	Index,
		IN DATA_REMOVAL_FEATURE_DESCRIPTOR *	Descriptor
	)

Return the estimated time for specific type.

Parameters

[in]	Index	The input data removal type.
[in]	Descriptor	DATA_REMOVAL_FEATURE_DESCRIPTOR

Definition at line 1024 of file TcgStorageOpalUtil.c.

◆ GetRevertTimeOut()

UINT32 GetRevertTimeOut ( IN OPAL_SESSION * Session )

Get revert timeout value.

Parameters

[in] Session The session info for one opal device.

Definition at line 1104 of file TcgStorageOpalUtil.c.

◆ OpalUtilAdminPasswordExists()

BOOLEAN EFIAPI OpalUtilAdminPasswordExists	(	IN UINT16	OwnerShip,
		IN TCG_LOCKING_FEATURE_DESCRIPTOR *	LockingFeature
	)

The function returns if admin password exists.

Parameters

[in]	OwnerShip	The owner ship of the opal device.
[in]	LockingFeature	The locking info of the opal device.

Return values

TRUE	Admin password existed.
FALSE	Admin password not existed.

Definition at line 921 of file TcgStorageOpalUtil.c.

◆ OpalUtilDetermineOwnership()

OPAL_OWNER_SHIP EFIAPI OpalUtilDetermineOwnership	(	OPAL_SESSION *	Session,
		UINT8 *	Msid,
		UINT32	MsidLength
	)

The function determines who owns the device by attempting to start a session with different credentials. If the SID PIN matches the MSID PIN, the no one owns the device. If the SID PIN matches the ourSidPin, then "Us" owns the device. Otherwise it is unknown.

Parameters

[in]	Session	The session info for one opal device.
	Msid,The	Msid info.
	MsidLength,The	data length for Msid.

Definition at line 869 of file TcgStorageOpalUtil.c.

◆ OpalUtilDisableUser()

TCG_RESULT EFIAPI OpalUtilDisableUser	(	OPAL_SESSION *	Session,
		const VOID *	Password,
		UINT32	PasswordLength,
		BOOLEAN *	PasswordFailed
	)

Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY and disables the User1 authority.

Parameters

[in]	Session,The	session info for one opal device.
[in]	Password	Admin password
[in]	PasswordLength	Length of password in bytes
	[in/out]	PasswordFailed indicates if password failed (start session didn't work)

Definition at line 542 of file TcgStorageOpalUtil.c.

◆ OpalUtilGetActiveDataRemovalMechanism()

TCG_RESULT EFIAPI OpalUtilGetActiveDataRemovalMechanism	(	OPAL_SESSION *	Session,
		const VOID *	GeneratedSid,
		UINT32	SidLength,
		UINT8 *	ActiveDataRemovalMechanism
	)

Get Active Data Removal Mechanism Value.

Parameters

[in]	Session	The session info for one opal device.
[in]	GeneratedSid	Generated SID of disk
[in]	SidLength	Length of generatedSid in bytes
[out]	ActiveDataRemovalMechanism	Return the active data removal mechanism.

Definition at line 950 of file TcgStorageOpalUtil.c.

◆ OpalUtilGetDataRemovalMechanismLists()

TCG_RESULT EFIAPI OpalUtilGetDataRemovalMechanismLists	(	IN OPAL_SESSION *	Session,
		OUT UINT32 *	RemovalMechanismLists
	)

Get the supported Data Removal Mechanism list.

Parameters

[in]	Session	The session info for one opal device.
[out]	RemovalMechanismLists	Return the supported data removal mechanism lists.

Definition at line 1062 of file TcgStorageOpalUtil.c.

◆ OpalUtilGetMsid()

TCG_RESULT EFIAPI OpalUtilGetMsid	(	OPAL_SESSION *	Session,
		UINT8 *	Msid,
		UINT32	MsidBufferLength,
		UINT32 *	MsidLength
	)

Update global locking range.

Parameters

Session,The	session info for one opal device.
Msid,The	data buffer to save Msid info.
MsidBufferLength,The	data buffer length for Msid.
MsidLength,The	actual data length for Msid.

Definition at line 820 of file TcgStorageOpalUtil.c.

◆ OpalUtilPsidRevert()

TCG_RESULT EFIAPI OpalUtilPsidRevert	(	OPAL_SESSION *	Session,
		const VOID *	Psid,
		UINT32	PsidLength
	)

Creates a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts device using Admin SP Revert method.

Parameters

[in]	Session,The	session info for one opal device.
[in]	Psid	PSID of device to revert.
[in]	PsidLength	Length of PSID in bytes.

Definition at line 26 of file TcgStorageOpalUtil.c.

◆ OpalUtilRevert()

TCG_RESULT EFIAPI OpalUtilRevert	(	OPAL_SESSION *	Session,
		BOOLEAN	KeepUserData,
		const VOID *	Password,
		UINT32	PasswordLength,
		BOOLEAN *	PasswordFailed,
		UINT8 *	Msid,
		UINT32	MsidLength
	)

Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts the device using the RevertSP method.

Parameters

[in]	Session,The	session info for one opal device.
[in]	KeepUserData	TRUE to keep existing Data on the disk, or FALSE to erase it
[in]	Password	Admin password
[in]	PasswordLength	Length of password in bytes
	[in/out]	PasswordFailed indicates if password failed (start session didn't work)
[in]	Msid	Msid info.
[in]	MsidLength	Msid data length.

Definition at line 600 of file TcgStorageOpalUtil.c.

◆ OpalUtilSecureErase()

TCG_RESULT EFIAPI OpalUtilSecureErase	(	OPAL_SESSION *	Session,
		const VOID *	Password,
		UINT32	PasswordLength,
		BOOLEAN *	PasswordFailed
	)

Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY and generates a new global locking range key to erase the Data.

Parameters

[in]	Session,The	session info for one opal device.
[in]	Password	Admin or user password
[in]	PasswordLength	Length of password in bytes
	[in/out]	PasswordFailed indicates if password failed (start session didn't work)

Definition at line 470 of file TcgStorageOpalUtil.c.

◆ OpalUtilSetAdminPassword()

TCG_RESULT EFIAPI OpalUtilSetAdminPassword	(	OPAL_SESSION *	Session,
		const VOID *	OldPassword,
		UINT32	OldPasswordLength,
		const VOID *	NewPassword,
		UINT32	NewPasswordLength
	)

Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY, sets OPAL_UID_ADMIN_SP_C_PIN_SID with the new password, and sets OPAL_LOCKING_SP_C_PIN_ADMIN1 with the new password.

Parameters

[in]	Session,The	session info for one opal device.
[in]	OldPassword	Current admin password
[in]	OldPasswordLength	Length of current admin password in bytes
[in]	NewPassword	New admin password to set
[in]	NewPasswordLength	Length of new password in bytes

Definition at line 243 of file TcgStorageOpalUtil.c.

◆ OpalUtilSetAdminPasswordAsSid()

TCG_RESULT EFIAPI OpalUtilSetAdminPasswordAsSid	(	OPAL_SESSION *	Session,
		const VOID *	GeneratedSid,
		UINT32	SidLength,
		const VOID *	Password,
		UINT32	PassLength
	)

Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY, sets the OPAL_UID_ADMIN_SP_C_PIN_SID column with the new password, and activates the locking SP to copy SID PIN to Admin1 Locking SP PIN

Parameters

[in]	Session,The	session info for one opal device.
[in]	GeneratedSid	Generated SID of disk
[in]	SidLength	Length of generatedSid in bytes
[in]	Password	New admin password to set
[in]	PassLength	Length of password in bytes

Definition at line 82 of file TcgStorageOpalUtil.c.

◆ OpalUtilSetOpalLockingRange()

TCG_RESULT EFIAPI OpalUtilSetOpalLockingRange	(	OPAL_SESSION *	Session,
		const VOID *	Password,
		UINT32	PassLength,
		TCG_UID	LockingRangeUid,
		UINT64	RangeStart,
		UINT64	RangeLength,
		BOOLEAN	ReadLockEnabled,
		BOOLEAN	WriteLockEnabled,
		BOOLEAN	ReadLocked,
		BOOLEAN	WriteLocked
	)

Opens a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY, and updates the specified locking range with the provided column values

Parameters

[in]	Session,The	session info for one opal device.
[in]	Password	New admin password to set
[in]	PassLength	Length of password in bytes
[in]	LockingRangeUid	Locking range UID to set values
[in]	RangeStart	Value to set RangeStart column for Locking Range
[in]	RangeLength	Value to set RangeLength column for Locking Range
[in]	ReadLockEnabled	Value to set readLockEnabled column for Locking Range
[in]	WriteLockEnabled	Value to set writeLockEnabled column for Locking Range
[in]	ReadLocked	Value to set ReadLocked column for Locking Range
[in]	WriteLocked	Value to set WriteLocked column for Locking Range

Definition at line 165 of file TcgStorageOpalUtil.c.

◆ OpalUtilSetSIDtoMSID()

TCG_RESULT EFIAPI OpalUtilSetSIDtoMSID	(	OPAL_SESSION *	Session,
		const VOID *	Password,
		UINT32	PasswordLength,
		UINT8 *	Msid,
		UINT32	MsidLength
	)

After revert success, set SID to MSID.

Parameters

Session,The	session info for one opal device.
Password,Input	password info.
PasswordLength,Input	password length.
Msid	Msid info.
MsidLength	Msid data length.

Definition at line 673 of file TcgStorageOpalUtil.c.

◆ OpalUtilSetUserPassword()

TCG_RESULT EFIAPI OpalUtilSetUserPassword	(	OPAL_SESSION *	Session,
		const VOID *	OldPassword,
		UINT32	OldPasswordLength,
		const VOID *	NewPassword,
		UINT32	NewPasswordLength
	)

Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY and sets the User1 SP authority to enabled and sets the User1 password.

Parameters

[in]	Session,The	session info for one opal device.
[in]	OldPassword	Current admin password
[in]	OldPasswordLength	Length of current admin password in bytes
[in]	NewPassword	New admin password to set
[in]	NewPasswordLength	Length of new password in bytes

Definition at line 330 of file TcgStorageOpalUtil.c.

◆ OpalUtilUpdateGlobalLockingRange()

TCG_RESULT EFIAPI OpalUtilUpdateGlobalLockingRange	(	OPAL_SESSION *	Session,
		const VOID *	Password,
		UINT32	PasswordLength,
		BOOLEAN	ReadLocked,
		BOOLEAN	WriteLocked
	)

Update global locking range.

Parameters

Session,The	session info for one opal device.
Password,Input	password info.
PasswordLength,Input	password length.
ReadLocked,Read	lock info.
WriteLocked	write lock info.

Definition at line 730 of file TcgStorageOpalUtil.c.

◆ OpalUtilVerifyPassword()

TCG_RESULT EFIAPI OpalUtilVerifyPassword	(	OPAL_SESSION *	Session,
		const VOID *	Password,
		UINT32	PasswordLength,
		TCG_UID	HostSigningAuthority
	)

Verify whether user input the correct password.

Parameters

[in]	Session,The	session info for one opal device.
[in]	Password	Admin password
[in]	PasswordLength	Length of password in bytes
	[in/out]	HostSigningAuthority Use the Host signing authority type.

Definition at line 428 of file TcgStorageOpalUtil.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ OPAL_MSID_LENGTH

Function Documentation

◆ CalculateDataRemovalTime()

◆ GetDataRemovalTime()

◆ GetRevertTimeOut()

◆ OpalUtilAdminPasswordExists()

◆ OpalUtilDetermineOwnership()

◆ OpalUtilDisableUser()

◆ OpalUtilGetActiveDataRemovalMechanism()

◆ OpalUtilGetDataRemovalMechanismLists()

◆ OpalUtilGetMsid()

◆ OpalUtilPsidRevert()

◆ OpalUtilRevert()

◆ OpalUtilSecureErase()

◆ OpalUtilSetAdminPassword()

◆ OpalUtilSetAdminPasswordAsSid()

◆ OpalUtilSetOpalLockingRange()

◆ OpalUtilSetSIDtoMSID()

◆ OpalUtilSetUserPassword()

◆ OpalUtilUpdateGlobalLockingRange()

◆ OpalUtilVerifyPassword()