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