SecurityPkg/Include/Library/TcgStorageOpalLib.h

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