SecurityPkg/Include/Library/OpalPasswordSupportLib.h

   1 /** @file
   2   Header file of Opal password support 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
  16 #ifndef _OPAL_PASSWORD_SUPPORT_LIB_H_
  17 #define _OPAL_PASSWORD_SUPPORT_LIB_H_
  18
  19 #include <Protocol/DevicePath.h>
  20 #include <Library/TcgStorageOpalLib.h>
  21
  22
  23 #pragma pack(1)
  24
  25 //
  26 // Structure that is used to represent the available actions for an OpalDisk.
  27 // The data can then be utilized to expose/hide certain actions available to an end user
  28 // by the consumer of this library.
  29 //
  30 typedef struct {
  31     //
  32     // Indicates if the disk can support PSID Revert action.  should verify disk supports PSID authority
  33     //
  34     UINT16 PsidRevert : 1;
  35
  36     //
  37     // Indicates if the disk can support Revert action
  38     //
  39     UINT16 Revert : 1;
  40
  41     //
  42     // Indicates if the user must keep data for revert action.  It is true if no media encryption is supported.
  43     //
  44     UINT16 RevertKeepDataForced : 1;
  45
  46     //
  47     // Indicates if the disk can support set Admin password
  48     //
  49     UINT16 AdminPass : 1;
  50
  51     //
  52     // Indicates if the disk can support set User password.  This action requires that a user
  53     // password is first enabled.
  54     //
  55     UINT16 UserPass : 1;
  56
  57     //
  58     // Indicates if unlock action is available.  Requires disk to be currently locked.
  59     //
  60     UINT16 Unlock : 1;
  61
  62     //
  63     // Indicates if Secure Erase action is available.  Action requires admin credentials and media encryption support.
  64     //
  65     UINT16 SecureErase : 1;
  66
  67     //
  68     // Indicates if Disable User action is available.  Action requires admin credentials.
  69     //
  70     UINT16 DisableUser : 1;
  71 } OPAL_DISK_ACTIONS;
  72
  73 //
  74 // Structure that is used to represent the Opal device with password info.
  75 //
  76 typedef struct {
  77   LIST_ENTRY                 Link;
  78
  79   UINT8                      Password[32];
  80   UINT8                      PasswordLength;
  81
  82   EFI_DEVICE_PATH_PROTOCOL   OpalDevicePath;
  83 } OPAL_DISK_AND_PASSWORD_INFO;
  84
  85 #pragma pack()
  86
  87 /**
  88
  89   The function performs determines the available actions for the OPAL_DISK provided.
  90
  91   @param[in]   SupportedAttributes   The support attribute for the device.
  92   @param[in]   LockingFeature        The locking status for the device.
  93   @param[in]   OwnerShip             The ownership for the device.
  94   @param[out]  AvalDiskActions       Pointer to fill-out with appropriate disk actions.
  95
  96 **/
  97 TCG_RESULT
  98 EFIAPI
  99 OpalSupportGetAvailableActions(
 100   IN  OPAL_DISK_SUPPORT_ATTRIBUTE      *SupportedAttributes,
 101   IN  TCG_LOCKING_FEATURE_DESCRIPTOR   *LockingFeature,
 102   IN  UINT16                           OwnerShip,
 103   OUT OPAL_DISK_ACTIONS                *AvalDiskActions
 104   );
 105
 106 /**
 107   Enable Opal Feature for the input device.
 108
 109   @param[in]      Session            The opal session for the opal device.
 110   @param[in]      Msid               Msid
 111   @param[in]      MsidLength         Msid Length
 112   @param[in]      Password           Admin password
 113   @param[in]      PassLength         Length of password in bytes
 114   @param[in]      DevicePath         The device path for the opal devcie.
 115
 116 **/
 117 TCG_RESULT
 118 EFIAPI
 119 OpalSupportEnableOpalFeature(
 120   IN OPAL_SESSION              *Session,
 121   IN VOID                      *Msid,
 122   IN UINT32                    MsidLength,
 123   IN VOID                      *Password,
 124   IN UINT32                    PassLength,
 125   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 126   );
 127
 128 /**
 129   Creates a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts device using Admin SP Revert method.
 130
 131   @param[in]      Session            The opal session for the opal device.
 132   @param[in]      Psid               PSID of device to revert.
 133   @param[in]      PsidLength         Length of PSID in bytes.
 134   @param[in]      DevicePath         The device path for the opal devcie.
 135
 136 **/
 137 TCG_RESULT
 138 EFIAPI
 139 OpalSupportPsidRevert(
 140   IN OPAL_SESSION              *Session,
 141   IN VOID                      *Psid,
 142   IN UINT32                    PsidLength,
 143   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 144   );
 145
 146 /**
 147   Opens a session with OPAL_UID_ADMIN_SP as OPAL_ADMIN_SP_PSID_AUTHORITY, then reverts the device using the RevertSP method.
 148
 149   @param[in]      Session            The opal session for the opal device.
 150   @param[in]      KeepUserData       TRUE to keep existing Data on the disk, or FALSE to erase it
 151   @param[in]      Password           Admin password
 152   @param[in]      PasswordLength     Length of password in bytes
 153   @param[in]      Msid               Msid
 154   @param[in]      MsidLength         Msid Length
 155   @param[out]     PasswordFailed     indicates if password failed (start session didn't work)
 156   @param[in]      DevicePath         The device path for the opal devcie.
 157
 158 **/
 159 TCG_RESULT
 160 EFIAPI
 161 OpalSupportRevert(
 162   IN  OPAL_SESSION              *Session,
 163   IN  BOOLEAN                   KeepUserData,
 164   IN  VOID                      *Password,
 165   IN  UINT32                    PasswordLength,
 166   IN  VOID                      *Msid,
 167   IN  UINT32                    MsidLength,
 168   OUT BOOLEAN                   *PasswordFailed,
 169   IN  EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 170   );
 171
 172 /**
 173   Set new password.
 174
 175   @param[in]      Session            The opal session for the opal device.
 176   @param[in]      OldPassword        Current admin password
 177   @param[in]      OldPasswordLength  Length of current admin password in bytes
 178   @param[in]      NewPassword        New admin password to set
 179   @param[in]      NewPasswordLength  Length of new password in bytes
 180   @param[in]      DevicePath         The device path for the opal devcie.
 181   @param[in]      SetAdmin           Whether set admin password or user password.
 182                                      TRUE for admin, FALSE for user.
 183
 184 **/
 185 TCG_RESULT
 186 EFIAPI
 187 OpalSupportSetPassword(
 188   IN OPAL_SESSION              *Session,
 189   IN VOID                      *OldPassword,
 190   IN UINT32                    OldPasswordLength,
 191   IN VOID                      *NewPassword,
 192   IN UINT32                    NewPasswordLength,
 193   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
 194   IN BOOLEAN                   SetAdmin
 195   );
 196
 197 /**
 198   Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_ADMIN1_AUTHORITY and disables the User1 authority.
 199
 200   @param[in]      Session            The opal session for the opal device.
 201   @param[in]      Password           Admin password
 202   @param[in]      PasswordLength     Length of password in bytes
 203   @param[out]     PasswordFailed     Indicates if password failed (start session didn't work)
 204   @param[in]      DevicePath         The device path for the opal devcie.
 205
 206 **/
 207 TCG_RESULT
 208 EFIAPI
 209 OpalSupportDisableUser(
 210   IN  OPAL_SESSION              *Session,
 211   IN  VOID                      *Password,
 212   IN  UINT32                    PasswordLength,
 213   OUT BOOLEAN                   *PasswordFailed,
 214   IN  EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 215   );
 216
 217 /**
 218   Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY
 219   and updates the global locking range ReadLocked and WriteLocked columns to FALSE.
 220
 221   @param[in]      Session            The opal session for the opal device.
 222   @param[in]      Password           Admin or user password
 223   @param[in]      PasswordLength     Length of password in bytes
 224   @param[in]      DevicePath         The device path for the opal devcie.
 225
 226 **/
 227 TCG_RESULT
 228 EFIAPI
 229 OpalSupportUnlock(
 230   IN OPAL_SESSION               *Session,
 231   IN VOID                       *Password,
 232   IN UINT32                     PasswordLength,
 233   IN EFI_DEVICE_PATH_PROTOCOL   *DevicePath
 234   );
 235
 236 /**
 237   Starts a session with OPAL_UID_LOCKING_SP as OPAL_LOCKING_SP_USER1_AUTHORITY or OPAL_LOCKING_SP_ADMIN1_AUTHORITY
 238   and updates the global locking range ReadLocked and WriteLocked columns to TRUE.
 239
 240   @param[in]      Session             The opal session for the opal device.
 241   @param[in]      Password            Admin or user password
 242   @param[in]      PasswordLength      Length of password in bytes
 243   @param[in]      DevicePath          The device path for the opal devcie.
 244
 245 **/
 246 TCG_RESULT
 247 EFIAPI
 248 OpalSupportLock(
 249   IN OPAL_SESSION               *Session,
 250   IN VOID                       *Password,
 251   IN UINT32                     PasswordLength,
 252   IN EFI_DEVICE_PATH_PROTOCOL   *DevicePath
 253   );
 254
 255 /**
 256   Check if the password is full zero.
 257
 258   @param[in]   Password       Points to the Data Buffer
 259
 260   @retval      TRUE           This password string is full zero.
 261   @retval      FALSE          This password string is not full zero.
 262
 263 **/
 264 LIST_ENTRY *
 265 EFIAPI
 266 OpalSupportGetOpalDeviceList (
 267   VOID
 268   );
 269
 270 /**
 271   Transfer the password to the smm driver.
 272
 273   @param[in]  DevicePath     The device path for the opal devcie.
 274   @param      PasswordLen    The input password length.
 275   @param      Password       Input password buffer.
 276
 277   @retval  EFI_SUCCESS       Do the required action success.
 278   @retval  Others            Error occured.
 279
 280 **/
 281 EFI_STATUS
 282 EFIAPI
 283 OpalSupportSendPasword(
 284   EFI_DEVICE_PATH_PROTOCOL    *DevicePath,
 285   UINTN                       PasswordLen,
 286   VOID                        *Password
 287   );
 288
 289 #endif // _OPAL_CORE_H_