#include <IndustryStandard/TcgStorageOpal.h>
#include <Library/TcgStorageCoreLib.h>
#include <Protocol/StorageSecurityCommand.h>

Data Structures
struct	OPAL_DISK_SUPPORT_ATTRIBUTE

struct	OPAL_SESSION

Enumerations
enum	OPAL_OWNER_SHIP { OpalOwnershipUnknown , OpalOwnershipNobody }

Functions
TCG_RESULT EFIAPI	OpalRetrieveSupportedProtocolList (OPAL_SESSION Session, UINTN BufferSize, VOID BuffAddress)

TCG_RESULT EFIAPI	OpalRetrieveLevel0DiscoveryHeader (OPAL_SESSION Session, UINTN BufferSize, VOID BuffAddress)

TCG_RESULT EFIAPI	OpalStartSession (OPAL_SESSION Session, TCG_UID SpId, BOOLEAN Write, UINT32 HostChallengeLength, const VOID HostChallenge, TCG_UID HostSigningAuthority, UINT8 *MethodStatus)

TCG_RESULT EFIAPI	OpalEndSession (OPAL_SESSION *Session)

TCG_RESULT EFIAPI	OpalPsidRevert (OPAL_SESSION *AdminSpSession)

TCG_RESULT EFIAPI	OpalGetMsid (OPAL_SESSION AdminSpSession, UINT32 MsidBufferSize, UINT8 Msid, UINT32 *MsidLength)

TCG_RESULT EFIAPI	OpalActivateLockingSp (OPAL_SESSION AdminSpSession, UINT8 MethodStatus)

TCG_RESULT EFIAPI	OpalSetPassword (OPAL_SESSION Session, TCG_UID CpinRowUid, const VOID NewPin, UINT32 NewPinLength, UINT8 *MethodStatus)

TCG_RESULT EFIAPI	OpalGlobalLockingRangeGenKey (OPAL_SESSION LockingSpSession, UINT8 MethodStatus)

TCG_RESULT EFIAPI	OpalUpdateGlobalLockingRange (OPAL_SESSION LockingSpSession, BOOLEAN ReadLocked, BOOLEAN WriteLocked, UINT8 MethodStatus)

TCG_RESULT EFIAPI	OpalSetLockingRange (OPAL_SESSION LockingSpSession, TCG_UID LockingRangeUid, UINT64 RangeStart, UINT64 RangeLength, BOOLEAN ReadLockEnabled, BOOLEAN WriteLockEnabled, BOOLEAN ReadLocked, BOOLEAN WriteLocked, UINT8 MethodStatus)

TCG_RESULT EFIAPI	OpalSetLockingSpAuthorityEnabledAndPin (OPAL_SESSION LockingSpSession, TCG_UID CpinRowUid, TCG_UID AuthorityUid, const VOID NewPin, UINT32 NewPinLength, UINT8 *MethodStatus)

TCG_RESULT EFIAPI	OpalDisableUser (OPAL_SESSION LockingSpSession, UINT8 MethodStatus)

TCG_RESULT EFIAPI	OpalAdminRevert (OPAL_SESSION LockingSpSession, BOOLEAN KeepUserData, UINT8 MethodStatus)

TCG_RESULT EFIAPI	OpalGetTryLimit (OPAL_SESSION LockingSpSession, TCG_UID RowUid, UINT32 TryLimit)

TCG_RESULT EFIAPI	OpalCreateRetrieveGlobalLockingRangeActiveKey (const OPAL_SESSION Session, TCG_CREATE_STRUCT CreateStruct, UINT32 *Size)

TCG_RESULT EFIAPI	OpalParseRetrieveGlobalLockingRangeActiveKey (TCG_PARSE_STRUCT ParseStruct, TCG_UID ActiveKey)

TCG_RESULT EFIAPI	OpalGetLockingInfo (OPAL_SESSION Session, TCG_LOCKING_FEATURE_DESCRIPTOR LockingFeature)

BOOLEAN EFIAPI	OpalFeatureSupported (OPAL_DISK_SUPPORT_ATTRIBUTE *SupportedAttributes)

BOOLEAN EFIAPI	OpalFeatureEnabled (OPAL_DISK_SUPPORT_ATTRIBUTE SupportedAttributes, TCG_LOCKING_FEATURE_DESCRIPTOR LockingFeature)

BOOLEAN	OpalDeviceLocked (OPAL_DISK_SUPPORT_ATTRIBUTE SupportedAttributes, TCG_LOCKING_FEATURE_DESCRIPTOR LockingFeature)

TCG_RESULT EFIAPI	OpalBlockSid (OPAL_SESSION *Session, BOOLEAN HardwareReset)

TCG_RESULT EFIAPI	OpalGetSupportedAttributesInfo (OPAL_SESSION Session, OPAL_DISK_SUPPORT_ATTRIBUTE SupportedAttributes, UINT16 *OpalBaseComId)

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

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

TCG_RESULT EFIAPI	OpalUtilSetOpalLockingRange (OPAL_SESSION LockingSpSession, 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 AdminSpSession, const VOID OldPassword, UINT32 OldPasswordLength, const VOID *NewPassword, UINT32 NewPasswordLength)

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

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

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

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

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

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

TCG_RESULT EFIAPI	OpalUtilUpdateGlobalLockingRange (OPAL_SESSION LockingSpSession, 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)

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

Detailed Description

Public API for Opal Core library.

(TCG Storage Architecture Core Specification, Version 2.01, Revision 1.00, https://trustedcomputinggroup.org/tcg-storage-architecture-core-specification/

Storage Work Group Storage Security Subsystem Class: Pyrite, Specification Version 2.00, Revision 1.00, https://trustedcomputinggroup.org/resource/tcg-storage-security-subsystem-class-pyrite/

Storage Work Group Storage Security Subsystem Class: Opal, Version 2.01 Final, Revision 1.00, https://trustedcomputinggroup.org/storage-work-group-storage-security-subsystem-class-opal/

TCG Storage Security Subsystem Class: Opalite Version 1.00 Revision 1.00, https://trustedcomputinggroup.org/tcg-storage-security-subsystem-class-opalite/

TCG Storage Feature Set: Block SID Authentication, Version 1.00 Final, Revision 1.00, https://trustedcomputinggroup.org/tcg-storage-feature-set-block-sid-authentication-specification/

TCG Storage Opal SSC Feature Set: PSID Version 1.00, Revision 1.00, https://trustedcomputinggroup.org/tcg-storage-opal-feature-set-psid/)

Check http://trustedcomputinggroup.org for latest specification updates.

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

Definition in file TcgStorageOpalLib.h.

Enumeration Type Documentation

◆ OPAL_OWNER_SHIP

enum OPAL_OWNER_SHIP

Definition at line 114 of file TcgStorageOpalLib.h.

Function Documentation

◆ OpalActivateLockingSp()

TCG_RESULT EFIAPI OpalActivateLockingSp	(	OPAL_SESSION *	AdminSpSession,
		UINT8 *	MethodStatus
	)

The function activates the Locking SP. Once activated, per Opal spec, the ADMIN SP SID PIN is copied over to the ADMIN1 LOCKING SP PIN. If the Locking SP is already enabled, then TcgResultSuccess is returned and no action occurs.

Parameters

[in]	AdminSpSession	OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY to activate Locking SP
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

Definition at line 948 of file TcgStorageOpalCore.c.

◆ OpalAdminRevert()

TCG_RESULT EFIAPI OpalAdminRevert	(	OPAL_SESSION *	LockingSpSession,
		BOOLEAN	KeepUserData,
		UINT8 *	MethodStatus
	)

The function calls the Admin SP RevertSP method on the Locking SP. If KeepUserData is True, then the optional parameter to keep the user data is set to True, otherwise the optional parameter is not provided.

Parameters

[in]	LockingSpSession	OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to revertSP
[in]	KeepUserData	Specifies whether or not to keep user data when performing RevertSP action. True = keeps user data.
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

The function calls the Admin SP RevertSP method on the Locking SP. If KeepUserData is True, then the optional parameter to keep the user Data is set to True, otherwise the optional parameter is not provided.

Parameters

[in]	LockingSpSession	OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to revertSP
[in]	KeepUserData	Specifies whether or not to keep user Data when performing RevertSP action. True = keeps user Data.
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

Definition at line 757 of file TcgStorageOpalCore.c.

◆ OpalBlockSid()

TCG_RESULT EFIAPI OpalBlockSid	(	OPAL_SESSION *	Session,
		BOOLEAN	HardwareReset
	)

Trig the block sid action.

Parameters

[in]	Session	OPAL_SESSION to populate command for, needs comId
[in]	HardwareReset	Whether need to do hardware reset.

Trig the block sid action.

Parameters

[in]	Session	OPAL_SESSION related to this method..
[in]	HardwareReset	Whether need to do hardware reset.

Definition at line 248 of file TcgStorageOpalCore.c.

◆ OpalCreateRetrieveGlobalLockingRangeActiveKey()

TCG_RESULT EFIAPI OpalCreateRetrieveGlobalLockingRangeActiveKey	(	const OPAL_SESSION *	Session,
		TCG_CREATE_STRUCT *	CreateStruct,
		UINT32 *	Size
	)

The function populates the CreateStruct with a payload that will retrieve the global locking range active key. It is intended to be called with a session that is already started with a valid credential. The function does not send the payload.

Parameters

[in]	Session	OPAL_SESSION to populate command for, needs comId
	[in/out]	CreateStruct Structure to populate with encoded TCG command
	[in/out]	Size Size in bytes of the command created.

The function populates the CreateStruct with a payload that will retrieve the global locking range active key. It is intended to be called with a session that is already started with a valid credential. The function does not send the payload.

Parameters

[in]	Session	OPAL_SESSION to populate command for, needs ComId
	[in/out]	CreateStruct Structure to populate with encoded TCG command
	[in/out]	Size Size in bytes of the command created.

Definition at line 1503 of file TcgStorageOpalCore.c.

◆ OpalDeviceLocked()

BOOLEAN OpalDeviceLocked	(	OPAL_DISK_SUPPORT_ATTRIBUTE *	SupportedAttributes,
		TCG_LOCKING_FEATURE_DESCRIPTOR *	LockingFeature
	)

The function returns whether or not the device is Opal Locked. TRUE means that the device is partially or fully locked. This will perform a Level 0 Discovery and parse the locking feature descriptor

Parameters

[in]	SupportedAttributes	Opal device attribute.
[in]	LockingFeature	Opal device locking status.

Definition at line 2021 of file TcgStorageOpalCore.c.

◆ OpalDisableUser()

TCG_RESULT EFIAPI OpalDisableUser	(	OPAL_SESSION *	LockingSpSession,
		UINT8 *	MethodStatus
	)

The function sets the Enabled column to FALSE for the USER1 authority.

Parameters

[in]	LockingSpSession	OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to disable User1
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

Definition at line 1233 of file TcgStorageOpalCore.c.

◆ OpalEndSession()

TCG_RESULT EFIAPI OpalEndSession ( OPAL_SESSION * Session )

Close a session opened with OpalStartSession.

Parameters

[in/out] Session OPAL_SESSION to end.

Definition at line 518 of file TcgStorageOpalCore.c.

◆ OpalFeatureEnabled()

BOOLEAN EFIAPI OpalFeatureEnabled	(	OPAL_DISK_SUPPORT_ATTRIBUTE *	SupportedAttributes,
		TCG_LOCKING_FEATURE_DESCRIPTOR *	LockingFeature
	)

The function returns whether or not the device is Opal Enabled. TRUE means that the device is partially or fully locked. This will perform a Level 0 Discovery and parse the locking feature descriptor

Parameters

[in]	SupportedAttributes	Opal device attribute.
[in]	LockingFeature	Opal device locking status.

Definition at line 1991 of file TcgStorageOpalCore.c.

◆ OpalFeatureSupported()

BOOLEAN EFIAPI OpalFeatureSupported ( OPAL_DISK_SUPPORT_ATTRIBUTE * SupportedAttributes )

The function determines whether or not all of the requirements for the Opal Feature (not full specification) are met by the specified device.

Parameters

[in] SupportedAttributes Opal device attribute.

Definition at line 1955 of file TcgStorageOpalCore.c.

◆ OpalGetLockingInfo()

TCG_RESULT EFIAPI OpalGetLockingInfo	(	OPAL_SESSION *	Session,
		TCG_LOCKING_FEATURE_DESCRIPTOR *	LockingFeature
	)

Get the support attribute info.

Parameters

[in]	Session	OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve info.
	[in/out]	LockingFeature Return the Locking info.

Definition at line 1861 of file TcgStorageOpalCore.c.

◆ OpalGetMsid()

TCG_RESULT EFIAPI OpalGetMsid	(	OPAL_SESSION *	AdminSpSession,
		UINT32	MsidBufferSize,
		UINT8 *	Msid,
		UINT32 *	MsidLength
	)

The function retrieves the MSID from the device specified

Parameters

[in]	AdminSpSession	OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY to perform PSID revert.
[in]	MsidBufferSize	Allocated buffer size (in bytes) for MSID allocated by caller
[in]	Msid	Variable length byte sequence representing MSID of device
[in]	MsidLength	Actual length of MSID retrieved from device

The function retrieves the MSID from the device specified

Parameters

[in]	AdminSpSession	OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY to perform PSID revert.
[in]	MsidBufferSize	Allocated Buffer Size (in bytes) for MSID allocated by caller
[in]	Msid	Variable Length byte sequence representing MSID of device
[in]	MsidLength	Actual Length of MSID retrieved from device

Definition at line 583 of file TcgStorageOpalCore.c.

◆ OpalGetSupportedAttributesInfo()

TCG_RESULT EFIAPI OpalGetSupportedAttributesInfo	(	OPAL_SESSION *	Session,
		OPAL_DISK_SUPPORT_ATTRIBUTE *	SupportedAttributes,
		UINT16 *	OpalBaseComId
	)

Get the support attribute info.

Parameters

[in]	Session	OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve info.
	[in/out]	SupportedAttributes Return the support attribute info.
[out]	OpalBaseComId	Return the base com id info.

◆ OpalGetTryLimit()

TCG_RESULT EFIAPI OpalGetTryLimit	(	OPAL_SESSION *	LockingSpSession,
		TCG_UID	RowUid,
		UINT32 *	TryLimit
	)

The function retrieves the TryLimit column for the specified rowUid (authority).

Parameters

[in]	LockingSpSession	OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve try limit
[in]	RowUid	Row UID of the Locking SP C_PIN table to retrieve TryLimit column
	[in/out]	TryLimit Value from TryLimit column

Definition at line 1593 of file TcgStorageOpalCore.c.

◆ OpalGlobalLockingRangeGenKey()

TCG_RESULT EFIAPI OpalGlobalLockingRangeGenKey	(	OPAL_SESSION *	LockingSpSession,
		UINT8 *	MethodStatus
	)

The function retrieves the active key of the global locking range and calls the GenKey method on the active key retrieved.

Parameters

[in]	LockingSpSession	OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

Definition at line 1276 of file TcgStorageOpalCore.c.

◆ OpalParseRetrieveGlobalLockingRangeActiveKey()

TCG_RESULT EFIAPI OpalParseRetrieveGlobalLockingRangeActiveKey	(	TCG_PARSE_STRUCT *	ParseStruct,
		TCG_UID *	ActiveKey
	)

The function acquires the activeKey specified for the Global Locking Range from the parseStruct.

Parameters

[in]	ParseStruct	Structure that contains the device's response with the activekey
	[in/out]	ActiveKey The UID of the active key retrieved

The function acquires the activeKey specified for the Global Locking Range from the ParseStruct.

Parameters

[in]	ParseStruct	Structure that contains the device's response with the activekey
	[in/out]	ActiveKey The UID of the active key retrieved

Definition at line 1548 of file TcgStorageOpalCore.c.

◆ OpalPsidRevert()

TCG_RESULT EFIAPI OpalPsidRevert ( OPAL_SESSION * AdminSpSession )

Reverts device using Admin SP Revert method.

Parameters

[in] AdminSpSession OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY to perform PSID revert.

Definition at line 286 of file TcgStorageOpalCore.c.

◆ OpalRetrieveLevel0DiscoveryHeader()

TCG_RESULT EFIAPI OpalRetrieveLevel0DiscoveryHeader	(	OPAL_SESSION *	Session,
		UINTN	BufferSize,
		VOID *	BuffAddress
	)

The function fills in the provided Buffer with the level 0 discovery Header of the device specified.

Parameters

[in]	Session	OPAL_SESSION data.
[in]	BufferSize	Size of Buffer provided (in bytes)
[in]	BuffAddress	Buffer address to fill with Level 0 Discovery response

Definition at line 390 of file TcgStorageOpalCore.c.

◆ OpalRetrieveSupportedProtocolList()

TCG_RESULT EFIAPI OpalRetrieveSupportedProtocolList	(	OPAL_SESSION *	Session,
		UINTN	BufferSize,
		VOID *	BuffAddress
	)

The function fills in the provided Buffer with the supported protocol list of the device specified.

Parameters

[in]	Session	OPAL_SESSION data.
[in]	BufferSize	Size of Buffer provided (in bytes)
[in]	BuffAddress	Buffer address to fill with security protocol list

Definition at line 419 of file TcgStorageOpalCore.c.

◆ OpalSetLockingRange()

TCG_RESULT EFIAPI OpalSetLockingRange	(	OPAL_SESSION *	LockingSpSession,
		TCG_UID	LockingRangeUid,
		UINT64	RangeStart,
		UINT64	RangeLength,
		BOOLEAN	ReadLockEnabled,
		BOOLEAN	WriteLockEnabled,
		BOOLEAN	ReadLocked,
		BOOLEAN	WriteLocked,
		UINT8 *	MethodStatus
	)

The function updates the RangeStart, RangeLength, ReadLockedEnabled, WriteLockedEnabled, ReadLocked and WriteLocked columns of the specified Locking Range. This function requires admin authority of a locking SP session.

Parameters

[in]	LockingSpSession	OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
[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
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

Definition at line 1406 of file TcgStorageOpalCore.c.

◆ OpalSetLockingSpAuthorityEnabledAndPin()

TCG_RESULT EFIAPI OpalSetLockingSpAuthorityEnabledAndPin	(	OPAL_SESSION *	LockingSpSession,
		TCG_UID	CpinRowUid,
		TCG_UID	AuthorityUid,
		const VOID *	NewPin,
		UINT32	NewPinLength,
		UINT8 *	MethodStatus
	)

The function sets the Enabled column to TRUE for the authorityUid provided and updates the PIN column for the cpinRowUid provided using the newPin provided. AuthorityUid and cpinRowUid should describe the same authority.

Parameters

[in]	LockingSpSession	OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to update
[in]	CpinRowUid	Row UID of C_PIN table of Locking SP to update PIN
[in]	AuthorityUid	UID of Locking SP authority to update Pin column with
[in]	NewPin	New Password used to set Pin column
[in]	NewPinLength	Length in bytes of new password
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

Definition at line 1052 of file TcgStorageOpalCore.c.

◆ OpalSetPassword()

TCG_RESULT EFIAPI OpalSetPassword	(	OPAL_SESSION *	Session,
		TCG_UID	CpinRowUid,
		const VOID *	NewPin,
		UINT32	NewPinLength,
		UINT8 *	MethodStatus
	)

The function sets the PIN column of the specified cpinRowUid (authority) with the newPin value.

Parameters

	[in/out]	Session OPAL_SESSION to set password
[in]	CpinRowUid	UID of row (authority) to update PIN column
[in]	NewPin	New Pin to set for cpinRowUid specified
[in]	NewPinLength	Length in bytes of newPin
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

The function sets the PIN column of the specified cpinRowUid (authority) with the newPin Value.

Parameters

	[in/out]	Session OPAL_SESSION to set password
[in]	CpinRowUid	UID of row (authority) to update PIN column
[in]	NewPin	New Pin to set for cpinRowUid specified
[in]	NewPinLength	Length in bytes of newPin
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

Definition at line 998 of file TcgStorageOpalCore.c.

◆ OpalStartSession()

TCG_RESULT EFIAPI OpalStartSession	(	OPAL_SESSION *	Session,
		TCG_UID	SpId,
		BOOLEAN	Write,
		UINT32	HostChallengeLength,
		const VOID *	HostChallenge,
		TCG_UID	HostSigningAuthority,
		UINT8 *	MethodStatus
	)

Starts a session with a security provider (SP).

If a session is started successfully, the caller must end the session with OpalEndSession when finished performing Opal actions.

Parameters

	[in/out]	Session OPAL_SESSION to initialize.
[in]	SpId	Security provider ID to start the session with.
[in]	Write	Whether the session should be read-only (FALSE) or read/write (TRUE).
[in]	HostChallengeLength	Length of the host challenge. Length should be 0 if hostChallenge is NULL
[in]	HostChallenge	Host challenge for Host Signing Authority. If NULL, then no Host Challenge will be sent.
[in]	HostSigningAuthority	Host Signing Authority used for start session. If NULL, then no Host Signing Authority will be sent.
	[in/out]	MethodStatus Status of the StartSession method; only valid if TcgResultSuccess is returned.

Returns: TcgResultSuccess indicates that the function completed without any internal errors. The caller must inspect the MethodStatus field to determine whether the method completed successfully.

Definition at line 456 of file TcgStorageOpalCore.c.

◆ OpalUpdateGlobalLockingRange()

TCG_RESULT EFIAPI OpalUpdateGlobalLockingRange	(	OPAL_SESSION *	LockingSpSession,
		BOOLEAN	ReadLocked,
		BOOLEAN	WriteLocked,
		UINT8 *	MethodStatus
	)

The function updates the ReadLocked and WriteLocked columns of the Global Locking Range. This function is required for a user1 authority, since a user1 authority shall only have access to ReadLocked and WriteLocked columns (not ReadLockEnabled and WriteLockEnabled columns).

Parameters

[in]	LockingSpSession	OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
[in]	ReadLocked	Value to set ReadLocked column for Global Locking Range
[in]	WriteLocked	Value to set WriteLocked column for Global Locking Range
	[in/out]	MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.

Definition at line 1335 of file TcgStorageOpalCore.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]	LockingSpSession	OPAL_SESSION to populate command for, needs comId
[in]	Password	Admin password
[in]	PasswordLength	Length of password in bytes
	[in/out]	PasswordFailed indicates if password failed (start session didn't work)

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.

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.

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]	AdminSpSession	OPAL_SESSION to populate command for, needs comId
[in]	Psid	PSID of device to revert.
[in]	PsidLength	Length of PSID in bytes.

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]	LockingSpSession	OPAL_SESSION to populate command for, needs comId
[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	Input Msid info.
[in]	MsidLength	Input Msid info length.

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]	LockingSpSession	OPAL_SESSION to populate command for, needs comId
[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)

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]	AdminSpSession	OPAL_SESSION to populate command for, needs comId
[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

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]	AdminSpSession	OPAL_SESSION to populate command for, needs comId
[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

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]	LockingSpSession	OPAL_SESSION to populate command for, needs comId
[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

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

[in]	AdminSpSession	OPAL_SESSION to populate command for, needs comId
	Password,Input	password info.
	PasswordLength,Input	password length.
[in]	Msid	Input Msid info.
[in]	MsidLength	Input Msid info length.

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]	LockingSpSession	OPAL_SESSION to populate command for, needs comId
[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

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

[in]	LockingSpSession	OPAL_SESSION to populate command for, needs comId
	Password,Input	password info.
	PasswordLength,Input	password length.
	ReadLocked,Read	lock info.
	WriteLocked	write lock info.

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]	LockingSpSession	OPAL_SESSION to populate command for, needs comId
[in]	Password	Admin password
[in]	PasswordLength	Length of password in bytes
	[in/out]	HostSigningAuthority Use the Host signing authority type.

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.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ OPAL_OWNER_SHIP

Function Documentation

◆ OpalActivateLockingSp()

◆ OpalAdminRevert()

◆ OpalBlockSid()

◆ OpalCreateRetrieveGlobalLockingRangeActiveKey()

◆ OpalDeviceLocked()

◆ OpalDisableUser()

◆ OpalEndSession()

◆ OpalFeatureEnabled()

◆ OpalFeatureSupported()

◆ OpalGetLockingInfo()

◆ OpalGetMsid()

◆ OpalGetSupportedAttributesInfo()

◆ OpalGetTryLimit()

◆ OpalGlobalLockingRangeGenKey()

◆ OpalParseRetrieveGlobalLockingRangeActiveKey()

◆ OpalPsidRevert()

◆ OpalRetrieveLevel0DiscoveryHeader()

◆ OpalRetrieveSupportedProtocolList()

◆ OpalSetLockingRange()

◆ OpalSetLockingSpAuthorityEnabledAndPin()

◆ OpalSetPassword()

◆ OpalStartSession()

◆ OpalUpdateGlobalLockingRange()

◆ OpalUtilAdminPasswordExists()

◆ OpalUtilDetermineOwnership()

◆ OpalUtilDisableUser()

◆ OpalUtilGetActiveDataRemovalMechanism()

◆ OpalUtilGetDataRemovalMechanismLists()

◆ OpalUtilGetMsid()

◆ OpalUtilPsidRevert()

◆ OpalUtilRevert()

◆ OpalUtilSecureErase()

◆ OpalUtilSetAdminPassword()

◆ OpalUtilSetAdminPasswordAsSid()

◆ OpalUtilSetOpalLockingRange()

◆ OpalUtilSetSIDtoMSID()

◆ OpalUtilSetUserPassword()

◆ OpalUtilUpdateGlobalLockingRange()

◆ OpalUtilVerifyPassword()