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