SecurityPkg/Include/Library/TcgStorageOpalLib.h

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