TcgStorageOpalLib.h 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892
  1. /** @file
  2. Public API for Opal Core library.
  3. (TCG Storage Architecture Core Specification, Version 2.01, Revision 1.00,
  4. https://trustedcomputinggroup.org/tcg-storage-architecture-core-specification/
  5. Storage Work Group Storage Security Subsystem Class: Pyrite, Specification Version 2.00, Revision 1.00,
  6. https://trustedcomputinggroup.org/resource/tcg-storage-security-subsystem-class-pyrite/
  7. Storage Work Group Storage Security Subsystem Class: Opal, Version 2.01 Final, Revision 1.00,
  8. https://trustedcomputinggroup.org/storage-work-group-storage-security-subsystem-class-opal/
  9. TCG Storage Security Subsystem Class: Opalite Version 1.00 Revision 1.00,
  10. https://trustedcomputinggroup.org/tcg-storage-security-subsystem-class-opalite/
  11. TCG Storage Feature Set: Block SID Authentication, Version 1.00 Final, Revision 1.00,
  12. https://trustedcomputinggroup.org/tcg-storage-feature-set-block-sid-authentication-specification/
  13. TCG Storage Opal SSC Feature Set: PSID Version 1.00, Revision 1.00,
  14. https://trustedcomputinggroup.org/tcg-storage-opal-feature-set-psid/)
  15. Check http://trustedcomputinggroup.org for latest specification updates.
  16. Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR>
  17. SPDX-License-Identifier: BSD-2-Clause-Patent
  18. **/
  19. #ifndef _OPAL_CORE_H_
  20. #define _OPAL_CORE_H_
  21. #include <IndustryStandard/TcgStorageOpal.h>
  22. #include <Library/TcgStorageCoreLib.h>
  23. #include <Protocol/StorageSecurityCommand.h>
  24. #pragma pack(1)
  25. typedef struct {
  26. //
  27. // Opal SSC 1 support (0 - not supported, 1 - supported)
  28. //
  29. UINT32 OpalSsc1 : 1;
  30. //
  31. // Opal SSC 2support (0 - not supported, 1 - supported)
  32. //
  33. UINT32 OpalSsc2 : 1;
  34. //
  35. // Opal SSC Lite support (0 - not supported, 1 - supported)
  36. //
  37. UINT32 OpalSscLite : 1;
  38. //
  39. // Pyrite SSC support (0 - not supported, 1 - supported)
  40. //
  41. UINT32 PyriteSsc : 1;
  42. //
  43. // Security protocol 1 support (0 - not supported, 1 - supported)
  44. //
  45. UINT32 Sp1 : 1;
  46. //
  47. // Security protocol 2 support (0 - not supported, 1 - supported)
  48. //
  49. UINT32 Sp2 : 1;
  50. //
  51. // Security protocol IEEE1667 support (0 - not supported, 1 - supported)
  52. //
  53. UINT32 SpIeee1667 : 1;
  54. //
  55. // Media encryption supported (0 - not supported, 1 - supported)
  56. //
  57. UINT32 MediaEncryption : 1;
  58. //
  59. // Initial C_PIN_SID PIN Indicator
  60. // 0 - The initial C_PIN_SID PIN value is NOT equal to the C_PIN_MSID PIN value
  61. // 1 - The initial C_PIN_SID PIN value is equal to the C_PIN_MSID PIN value
  62. //
  63. UINT32 InitCpinIndicator : 1;
  64. //
  65. // Behavior of C_PIN_SID PIN upon TPer Revert
  66. // 0 - The initial C_PIN_SID PIN value is NOT equal to the C_PIN_MSID PIN value
  67. // 1 - The initial C_PIN_SID PIN value is equal to the C_PIN_MSID PIN value
  68. //
  69. UINT32 CpinUponRevert : 1;
  70. //
  71. // Media encryption supported (0 - not supported, 1 - supported)
  72. //
  73. UINT32 BlockSid : 1;
  74. //
  75. // Pyrite SSC V2 support (0 - not supported, 1 - supported)
  76. //
  77. UINT32 PyriteSscV2 : 1;
  78. //
  79. // Supported Data Removal Mechanism support (0 - not supported, 1 - supported)
  80. //
  81. UINT32 DataRemoval : 1;
  82. } OPAL_DISK_SUPPORT_ATTRIBUTE;
  83. //
  84. // Opal device ownership type
  85. // The type indicates who was the determined owner of the device.
  86. //
  87. typedef enum {
  88. //
  89. // Represents the device ownership is unknown because starting a session as the SID authority with the ADMIN SP
  90. //was unsuccessful with the provided PIN
  91. //
  92. OpalOwnershipUnknown,
  93. //
  94. // Represents that the ADMIN SP SID authority contains the same PIN as the MSID PIN
  95. //
  96. OpalOwnershipNobody,
  97. } OPAL_OWNER_SHIP;
  98. //
  99. // Structure that is used to represent an Opal session.
  100. // The structure must be initialized by calling OpalStartSession before being used as a parameter
  101. // for any other Opal function.
  102. // This structure should NOT be directly modified by the client of this library.
  103. //
  104. //
  105. typedef struct {
  106. UINT32 HostSessionId;
  107. UINT32 TperSessionId;
  108. UINT16 ComIdExtension;
  109. UINT16 OpalBaseComId;
  110. EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *Sscp;
  111. UINT32 MediaId;
  112. } OPAL_SESSION;
  113. #pragma pack()
  114. /**
  115. The function fills in the provided Buffer with the supported protocol list
  116. of the device specified.
  117. @param[in] Session OPAL_SESSION data.
  118. @param[in] BufferSize Size of Buffer provided (in bytes)
  119. @param[in] BuffAddress Buffer address to fill with security protocol list
  120. **/
  121. TCG_RESULT
  122. EFIAPI
  123. OpalRetrieveSupportedProtocolList(
  124. OPAL_SESSION *Session,
  125. UINTN BufferSize,
  126. VOID *BuffAddress
  127. );
  128. /**
  129. The function fills in the provided Buffer with the level 0 discovery Header
  130. of the device specified.
  131. @param[in] Session OPAL_SESSION data.
  132. @param[in] BufferSize Size of Buffer provided (in bytes)
  133. @param[in] BuffAddress Buffer address to fill with Level 0 Discovery response
  134. **/
  135. TCG_RESULT
  136. EFIAPI
  137. OpalRetrieveLevel0DiscoveryHeader(
  138. OPAL_SESSION *Session,
  139. UINTN BufferSize,
  140. VOID *BuffAddress
  141. );
  142. /**
  143. Starts a session with a security provider (SP).
  144. If a session is started successfully, the caller must end the session with OpalEndSession when finished
  145. performing Opal actions.
  146. @param[in/out] Session OPAL_SESSION to initialize.
  147. @param[in] SpId Security provider ID to start the session with.
  148. @param[in] Write Whether the session should be read-only (FALSE) or read/write (TRUE).
  149. @param[in] HostChallengeLength Length of the host challenge. Length should be 0 if hostChallenge is NULL
  150. @param[in] HostChallenge Host challenge for Host Signing Authority. If NULL, then no Host Challenge will be sent.
  151. @param[in] HostSigningAuthority Host Signing Authority used for start session. If NULL, then no Host Signing Authority will be sent.
  152. @param[in/out] MethodStatus Status of the StartSession method; only valid if TcgResultSuccess is returned.
  153. @return TcgResultSuccess indicates that the function completed without any internal errors.
  154. The caller must inspect the MethodStatus field to determine whether the method completed successfully.
  155. **/
  156. TCG_RESULT
  157. EFIAPI
  158. OpalStartSession(
  159. OPAL_SESSION *Session,
  160. TCG_UID SpId,
  161. BOOLEAN Write,
  162. UINT32 HostChallengeLength,
  163. const VOID *HostChallenge,
  164. TCG_UID HostSigningAuthority,
  165. UINT8 *MethodStatus
  166. );
  167. /**
  168. Close a session opened with OpalStartSession.
  169. @param[in/out] Session OPAL_SESSION to end.
  170. **/
  171. TCG_RESULT
  172. EFIAPI
  173. OpalEndSession(
  174. OPAL_SESSION *Session
  175. );
  176. /**
  177. Reverts device using Admin SP Revert method.
  178. @param[in] AdminSpSession OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY to perform PSID revert.
  179. **/
  180. TCG_RESULT
  181. EFIAPI
  182. OpalPsidRevert(
  183. OPAL_SESSION *AdminSpSession
  184. );
  185. /**
  186. The function retrieves the MSID from the device specified
  187. @param[in] AdminSpSession OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY to perform PSID revert.
  188. @param[in] MsidBufferSize Allocated buffer size (in bytes) for MSID allocated by caller
  189. @param[in] Msid Variable length byte sequence representing MSID of device
  190. @param[in] MsidLength Actual length of MSID retrieved from device
  191. **/
  192. TCG_RESULT
  193. EFIAPI
  194. OpalGetMsid(
  195. OPAL_SESSION *AdminSpSession,
  196. UINT32 MsidBufferSize,
  197. UINT8 *Msid,
  198. UINT32 *MsidLength
  199. );
  200. /**
  201. The function activates the Locking SP.
  202. Once activated, per Opal spec, the ADMIN SP SID PIN is copied over to the ADMIN1 LOCKING SP PIN.
  203. If the Locking SP is already enabled, then TcgResultSuccess is returned and no action occurs.
  204. @param[in] AdminSpSession OPAL_SESSION with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY to activate Locking SP
  205. @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
  206. **/
  207. TCG_RESULT
  208. EFIAPI
  209. OpalActivateLockingSp(
  210. OPAL_SESSION *AdminSpSession,
  211. UINT8 *MethodStatus
  212. );
  213. /**
  214. The function sets the PIN column of the specified cpinRowUid (authority) with the newPin value.
  215. @param[in/out] Session OPAL_SESSION to set password
  216. @param[in] CpinRowUid UID of row (authority) to update PIN column
  217. @param[in] NewPin New Pin to set for cpinRowUid specified
  218. @param[in] NewPinLength Length in bytes of newPin
  219. @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
  220. **/
  221. TCG_RESULT
  222. EFIAPI
  223. OpalSetPassword(
  224. OPAL_SESSION *Session,
  225. TCG_UID CpinRowUid,
  226. const VOID *NewPin,
  227. UINT32 NewPinLength,
  228. UINT8 *MethodStatus
  229. );
  230. /**
  231. The function retrieves the active key of the global locking range
  232. and calls the GenKey method on the active key retrieved.
  233. @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
  234. @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
  235. **/
  236. TCG_RESULT
  237. EFIAPI
  238. OpalGlobalLockingRangeGenKey(
  239. OPAL_SESSION *LockingSpSession,
  240. UINT8 *MethodStatus
  241. );
  242. /**
  243. The function updates the ReadLocked and WriteLocked columns of the Global Locking Range.
  244. This function is required for a user1 authority, since a user1 authority shall only have access to ReadLocked and WriteLocked columns
  245. (not ReadLockEnabled and WriteLockEnabled columns).
  246. @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
  247. @param[in] ReadLocked Value to set ReadLocked column for Global Locking Range
  248. @param[in] WriteLocked Value to set WriteLocked column for Global Locking Range
  249. @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
  250. **/
  251. TCG_RESULT
  252. EFIAPI
  253. OpalUpdateGlobalLockingRange(
  254. OPAL_SESSION *LockingSpSession,
  255. BOOLEAN ReadLocked,
  256. BOOLEAN WriteLocked,
  257. UINT8 *MethodStatus
  258. );
  259. /**
  260. The function updates the RangeStart, RangeLength, ReadLockedEnabled, WriteLockedEnabled, ReadLocked and WriteLocked columns
  261. of the specified Locking Range. This function requires admin authority of a locking SP session.
  262. @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP to generate key
  263. @param[in] LockingRangeUid Locking range UID to set values
  264. @param[in] RangeStart Value to set RangeStart column for Locking Range
  265. @param[in] RangeLength Value to set RangeLength column for Locking Range
  266. @param[in] ReadLockEnabled Value to set readLockEnabled column for Locking Range
  267. @param[in] WriteLockEnabled Value to set writeLockEnabled column for Locking Range
  268. @param[in] ReadLocked Value to set ReadLocked column for Locking Range
  269. @param[in] WriteLocked Value to set WriteLocked column for Locking Range
  270. @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
  271. **/
  272. TCG_RESULT
  273. EFIAPI
  274. OpalSetLockingRange(
  275. OPAL_SESSION *LockingSpSession,
  276. TCG_UID LockingRangeUid,
  277. UINT64 RangeStart,
  278. UINT64 RangeLength,
  279. BOOLEAN ReadLockEnabled,
  280. BOOLEAN WriteLockEnabled,
  281. BOOLEAN ReadLocked,
  282. BOOLEAN WriteLocked,
  283. UINT8 *MethodStatus
  284. );
  285. /**
  286. The function sets the Enabled column to TRUE for the authorityUid provided and updates the PIN column for the cpinRowUid provided
  287. using the newPin provided. AuthorityUid and cpinRowUid should describe the same authority.
  288. @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to update
  289. @param[in] CpinRowUid Row UID of C_PIN table of Locking SP to update PIN
  290. @param[in] AuthorityUid UID of Locking SP authority to update Pin column with
  291. @param[in] NewPin New Password used to set Pin column
  292. @param[in] NewPinLength Length in bytes of new password
  293. @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
  294. **/
  295. TCG_RESULT
  296. EFIAPI
  297. OpalSetLockingSpAuthorityEnabledAndPin(
  298. OPAL_SESSION *LockingSpSession,
  299. TCG_UID CpinRowUid,
  300. TCG_UID AuthorityUid,
  301. const VOID *NewPin,
  302. UINT32 NewPinLength,
  303. UINT8 *MethodStatus
  304. );
  305. /**
  306. The function sets the Enabled column to FALSE for the USER1 authority.
  307. @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to disable User1
  308. @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
  309. **/
  310. TCG_RESULT
  311. EFIAPI
  312. OpalDisableUser(
  313. OPAL_SESSION *LockingSpSession,
  314. UINT8 *MethodStatus
  315. );
  316. /**
  317. The function calls the Admin SP RevertSP method on the Locking SP. If KeepUserData is True, then the optional parameter
  318. to keep the user data is set to True, otherwise the optional parameter is not provided.
  319. @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY to revertSP
  320. @param[in] KeepUserData Specifies whether or not to keep user data when performing RevertSP action. True = keeps user data.
  321. @param[in/out] MethodStatus Method status of last action performed. If action succeeded, it should be TCG_METHOD_STATUS_CODE_SUCCESS.
  322. **/
  323. TCG_RESULT
  324. EFIAPI
  325. OpalAdminRevert(
  326. OPAL_SESSION *LockingSpSession,
  327. BOOLEAN KeepUserData,
  328. UINT8 *MethodStatus
  329. );
  330. /**
  331. The function retrieves the TryLimit column for the specified rowUid (authority).
  332. @param[in] LockingSpSession OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve try limit
  333. @param[in] RowUid Row UID of the Locking SP C_PIN table to retrieve TryLimit column
  334. @param[in/out] TryLimit Value from TryLimit column
  335. **/
  336. TCG_RESULT
  337. EFIAPI
  338. OpalGetTryLimit(
  339. OPAL_SESSION *LockingSpSession,
  340. TCG_UID RowUid,
  341. UINT32 *TryLimit
  342. );
  343. /**
  344. The function populates the CreateStruct with a payload that will retrieve the global locking range active key.
  345. It is intended to be called with a session that is already started with a valid credential.
  346. The function does not send the payload.
  347. @param[in] Session OPAL_SESSION to populate command for, needs comId
  348. @param[in/out] CreateStruct Structure to populate with encoded TCG command
  349. @param[in/out] Size Size in bytes of the command created.
  350. **/
  351. TCG_RESULT
  352. EFIAPI
  353. OpalCreateRetrieveGlobalLockingRangeActiveKey(
  354. const OPAL_SESSION *Session,
  355. TCG_CREATE_STRUCT *CreateStruct,
  356. UINT32 *Size
  357. );
  358. /**
  359. The function acquires the activeKey specified for the Global Locking Range from the parseStruct.
  360. @param[in] ParseStruct Structure that contains the device's response with the activekey
  361. @param[in/out] ActiveKey The UID of the active key retrieved
  362. **/
  363. TCG_RESULT
  364. EFIAPI
  365. OpalParseRetrieveGlobalLockingRangeActiveKey(
  366. TCG_PARSE_STRUCT *ParseStruct,
  367. TCG_UID *ActiveKey
  368. );
  369. /**
  370. Get the support attribute info.
  371. @param[in] Session OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve info.
  372. @param[in/out] LockingFeature Return the Locking info.
  373. **/
  374. TCG_RESULT
  375. EFIAPI
  376. OpalGetLockingInfo(
  377. OPAL_SESSION *Session,
  378. TCG_LOCKING_FEATURE_DESCRIPTOR *LockingFeature
  379. );
  380. /**
  381. The function determines whether or not all of the requirements for the Opal Feature (not full specification)
  382. are met by the specified device.
  383. @param[in] SupportedAttributes Opal device attribute.
  384. **/
  385. BOOLEAN
  386. EFIAPI
  387. OpalFeatureSupported(
  388. OPAL_DISK_SUPPORT_ATTRIBUTE *SupportedAttributes
  389. );
  390. /**
  391. The function returns whether or not the device is Opal Enabled.
  392. TRUE means that the device is partially or fully locked.
  393. This will perform a Level 0 Discovery and parse the locking feature descriptor
  394. @param[in] SupportedAttributes Opal device attribute.
  395. @param[in] LockingFeature Opal device locking status.
  396. **/
  397. BOOLEAN
  398. EFIAPI
  399. OpalFeatureEnabled(
  400. OPAL_DISK_SUPPORT_ATTRIBUTE *SupportedAttributes,
  401. TCG_LOCKING_FEATURE_DESCRIPTOR *LockingFeature
  402. );
  403. /**
  404. The function returns whether or not the device is Opal Locked.
  405. TRUE means that the device is partially or fully locked.
  406. This will perform a Level 0 Discovery and parse the locking feature descriptor
  407. @param[in] SupportedAttributes Opal device attribute.
  408. @param[in] LockingFeature Opal device locking status.
  409. **/
  410. BOOLEAN
  411. OpalDeviceLocked(
  412. OPAL_DISK_SUPPORT_ATTRIBUTE *SupportedAttributes,
  413. TCG_LOCKING_FEATURE_DESCRIPTOR *LockingFeature
  414. );
  415. /**
  416. Trig the block sid action.
  417. @param[in] Session OPAL_SESSION to populate command for, needs comId
  418. @param[in] HardwareReset Whether need to do hardware reset.
  419. **/
  420. TCG_RESULT
  421. EFIAPI
  422. OpalBlockSid(
  423. OPAL_SESSION *Session,
  424. BOOLEAN HardwareReset
  425. );
  426. /**
  427. Get the support attribute info.
  428. @param[in] Session OPAL_SESSION with OPAL_UID_LOCKING_SP to retrieve info.
  429. @param[in/out] SupportedAttributes Return the support attribute info.
  430. @param[out] OpalBaseComId Return the base com id info.
  431. **/
  432. TCG_RESULT
  433. EFIAPI
  434. OpalGetSupportedAttributesInfo(
  435. OPAL_SESSION *Session,
  436. OPAL_DISK_SUPPORT_ATTRIBUTE *SupportedAttributes,
  437. UINT16 *OpalBaseComId
  438. );
  439. /**
  440. Creates a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts device using Admin SP Revert method.
  441. @param[in] AdminSpSession OPAL_SESSION to populate command for, needs comId
  442. @param[in] Psid PSID of device to revert.
  443. @param[in] PsidLength Length of PSID in bytes.
  444. **/
  445. TCG_RESULT
  446. EFIAPI
  447. OpalUtilPsidRevert(
  448. OPAL_SESSION *AdminSpSession,
  449. const VOID *Psid,
  450. UINT32 PsidLength
  451. );
  452. /**
  453. Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY,
  454. sets the OPAL_UID_ADMIN_SP_C_PIN_SID column with the new password,
  455. and activates the locking SP to copy SID PIN to Admin1 Locking SP PIN.
  456. @param[in] AdminSpSession OPAL_SESSION to populate command for, needs comId
  457. @param[in] GeneratedSid Generated SID of disk
  458. @param[in] SidLength Length of generatedSid in bytes
  459. @param[in] Password New admin password to set
  460. @param[in] PassLength Length of password in bytes
  461. **/
  462. TCG_RESULT
  463. EFIAPI
  464. OpalUtilSetAdminPasswordAsSid(
  465. OPAL_SESSION *AdminSpSession,
  466. const VOID *GeneratedSid,
  467. UINT32 SidLength,
  468. const VOID *Password,
  469. UINT32 PassLength
  470. );
  471. /**
  472. Opens a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY,
  473. and updates the specified locking range with the provided column values.
  474. @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
  475. @param[in] Password New admin password to set
  476. @param[in] PassLength Length of password in bytes
  477. @param[in] LockingRangeUid Locking range UID to set values
  478. @param[in] RangeStart Value to set RangeStart column for Locking Range
  479. @param[in] RangeLength Value to set RangeLength column for Locking Range
  480. @param[in] ReadLockEnabled Value to set readLockEnabled column for Locking Range
  481. @param[in] WriteLockEnabled Value to set writeLockEnabled column for Locking Range
  482. @param[in] ReadLocked Value to set ReadLocked column for Locking Range
  483. @param[in] WriteLocked Value to set WriteLocked column for Locking Range
  484. **/
  485. TCG_RESULT
  486. EFIAPI
  487. OpalUtilSetOpalLockingRange(
  488. OPAL_SESSION *LockingSpSession,
  489. const VOID *Password,
  490. UINT32 PassLength,
  491. TCG_UID LockingRangeUid,
  492. UINT64 RangeStart,
  493. UINT64 RangeLength,
  494. BOOLEAN ReadLockEnabled,
  495. BOOLEAN WriteLockEnabled,
  496. BOOLEAN ReadLocked,
  497. BOOLEAN WriteLocked
  498. );
  499. /**
  500. Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_SID_AUTHORITY,
  501. sets OPAL_UID_ADMIN_SP_C_PIN_SID with the new password,
  502. and sets OPAL_LOCKING_SP_C_PIN_ADMIN1 with the new password.
  503. @param[in] AdminSpSession OPAL_SESSION to populate command for, needs comId
  504. @param[in] OldPassword Current admin password
  505. @param[in] OldPasswordLength Length of current admin password in bytes
  506. @param[in] NewPassword New admin password to set
  507. @param[in] NewPasswordLength Length of new password in bytes
  508. **/
  509. TCG_RESULT
  510. EFIAPI
  511. OpalUtilSetAdminPassword(
  512. OPAL_SESSION *AdminSpSession,
  513. const VOID *OldPassword,
  514. UINT32 OldPasswordLength,
  515. const VOID *NewPassword,
  516. UINT32 NewPasswordLength
  517. );
  518. /**
  519. Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY
  520. and sets the User1 SP authority to enabled and sets the User1 password.
  521. @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
  522. @param[in] OldPassword Current admin password
  523. @param[in] OldPasswordLength Length of current admin password in bytes
  524. @param[in] NewPassword New admin password to set
  525. @param[in] NewPasswordLength Length of new password in bytes
  526. **/
  527. TCG_RESULT
  528. EFIAPI
  529. OpalUtilSetUserPassword(
  530. OPAL_SESSION *LockingSpSession,
  531. const VOID *OldPassword,
  532. UINT32 OldPasswordLength,
  533. const VOID *NewPassword,
  534. UINT32 NewPasswordLength
  535. );
  536. /**
  537. Verify whether user input the correct password.
  538. @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
  539. @param[in] Password Admin password
  540. @param[in] PasswordLength Length of password in bytes
  541. @param[in/out] HostSigningAuthority Use the Host signing authority type.
  542. **/
  543. TCG_RESULT
  544. EFIAPI
  545. OpalUtilVerifyPassword (
  546. OPAL_SESSION *LockingSpSession,
  547. const VOID *Password,
  548. UINT32 PasswordLength,
  549. TCG_UID HostSigningAuthority
  550. );
  551. /**
  552. Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY
  553. and generates a new global locking range key to erase the Data.
  554. @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
  555. @param[in] Password Admin or user password
  556. @param[in] PasswordLength Length of password in bytes
  557. @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
  558. **/
  559. TCG_RESULT
  560. EFIAPI
  561. OpalUtilSecureErase(
  562. OPAL_SESSION *LockingSpSession,
  563. const VOID *Password,
  564. UINT32 PasswordLength,
  565. BOOLEAN *PasswordFailed
  566. );
  567. /**
  568. Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY and disables the User1 authority.
  569. @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
  570. @param[in] Password Admin password
  571. @param[in] PasswordLength Length of password in bytes
  572. @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
  573. **/
  574. TCG_RESULT
  575. EFIAPI
  576. OpalUtilDisableUser(
  577. OPAL_SESSION *LockingSpSession,
  578. const VOID *Password,
  579. UINT32 PasswordLength,
  580. BOOLEAN *PasswordFailed
  581. );
  582. /**
  583. Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts the device using the RevertSP method.
  584. @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
  585. @param[in] KeepUserData TRUE to keep existing Data on the disk, or FALSE to erase it
  586. @param[in] Password Admin password
  587. @param[in] PasswordLength Length of password in bytes
  588. @param[in/out] PasswordFailed indicates if password failed (start session didn't work)
  589. @param[in] Msid Input Msid info.
  590. @param[in] MsidLength Input Msid info length.
  591. **/
  592. TCG_RESULT
  593. EFIAPI
  594. OpalUtilRevert(
  595. OPAL_SESSION *LockingSpSession,
  596. BOOLEAN KeepUserData,
  597. const VOID *Password,
  598. UINT32 PasswordLength,
  599. BOOLEAN *PasswordFailed,
  600. UINT8 *Msid,
  601. UINT32 MsidLength
  602. );
  603. /**
  604. After revert success, set SID to MSID.
  605. @param[in] AdminSpSession OPAL_SESSION to populate command for, needs comId
  606. @param Password, Input password info.
  607. @param PasswordLength, Input password length.
  608. @param[in] Msid Input Msid info.
  609. @param[in] MsidLength Input Msid info length.
  610. **/
  611. TCG_RESULT
  612. EFIAPI
  613. OpalUtilSetSIDtoMSID (
  614. OPAL_SESSION *AdminSpSession,
  615. const VOID *Password,
  616. UINT32 PasswordLength,
  617. UINT8 *Msid,
  618. UINT32 MsidLength
  619. );
  620. /**
  621. Update global locking range.
  622. @param[in] LockingSpSession OPAL_SESSION to populate command for, needs comId
  623. @param Password, Input password info.
  624. @param PasswordLength, Input password length.
  625. @param ReadLocked, Read lock info.
  626. @param WriteLocked write lock info.
  627. **/
  628. TCG_RESULT
  629. EFIAPI
  630. OpalUtilUpdateGlobalLockingRange(
  631. OPAL_SESSION *LockingSpSession,
  632. const VOID *Password,
  633. UINT32 PasswordLength,
  634. BOOLEAN ReadLocked,
  635. BOOLEAN WriteLocked
  636. );
  637. /**
  638. Update global locking range.
  639. @param Session, The session info for one opal device.
  640. @param Msid, The data buffer to save Msid info.
  641. @param MsidBufferLength, The data buffer length for Msid.
  642. @param MsidLength, The actual data length for Msid.
  643. **/
  644. TCG_RESULT
  645. EFIAPI
  646. OpalUtilGetMsid(
  647. OPAL_SESSION *Session,
  648. UINT8 *Msid,
  649. UINT32 MsidBufferLength,
  650. UINT32 *MsidLength
  651. );
  652. /**
  653. The function determines who owns the device by attempting to start a session with different credentials.
  654. If the SID PIN matches the MSID PIN, the no one owns the device.
  655. If the SID PIN matches the ourSidPin, then "Us" owns the device. Otherwise it is unknown.
  656. @param[in] Session The session info for one opal device.
  657. @param Msid, The Msid info.
  658. @param MsidLength, The data length for Msid.
  659. **/
  660. OPAL_OWNER_SHIP
  661. EFIAPI
  662. OpalUtilDetermineOwnership(
  663. OPAL_SESSION *Session,
  664. UINT8 *Msid,
  665. UINT32 MsidLength
  666. );
  667. /**
  668. The function returns if admin password exists.
  669. @param[in] OwnerShip The owner ship of the opal device.
  670. @param[in] LockingFeature The locking info of the opal device.
  671. @retval TRUE Admin password existed.
  672. @retval FALSE Admin password not existed.
  673. **/
  674. BOOLEAN
  675. EFIAPI
  676. OpalUtilAdminPasswordExists(
  677. IN UINT16 OwnerShip,
  678. IN TCG_LOCKING_FEATURE_DESCRIPTOR *LockingFeature
  679. );
  680. /**
  681. Get Active Data Removal Mechanism Value.
  682. @param[in] Session, The session info for one opal device.
  683. @param[in] GeneratedSid Generated SID of disk
  684. @param[in] SidLength Length of generatedSid in bytes
  685. @param[out] ActiveDataRemovalMechanism Return the active data removal mechanism.
  686. **/
  687. TCG_RESULT
  688. EFIAPI
  689. OpalUtilGetActiveDataRemovalMechanism (
  690. OPAL_SESSION *Session,
  691. const VOID *GeneratedSid,
  692. UINT32 SidLength,
  693. UINT8 *ActiveDataRemovalMechanism
  694. );
  695. /**
  696. Get the supported Data Removal Mechanism list.
  697. @param[in] Session, The session info for one opal device.
  698. @param[out] RemovalMechanismLists Return the supported data removal mechanism lists.
  699. **/
  700. TCG_RESULT
  701. EFIAPI
  702. OpalUtilGetDataRemovalMechanismLists (
  703. IN OPAL_SESSION *Session,
  704. OUT UINT32 *RemovalMechanismLists
  705. );
  706. #endif // _OPAL_CORE_H_