MdePkg/Include/Protocol/UserManager.h

   1 /** @file
   2   UEFI 2.2 User Manager Protocol definition.
   3
   4   This protocol manages user profiles.
   5
   6   Copyright (c) 2009, Intel Corporation
   7   All rights reserved. This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef __USER_MANAGER_H__
  18 #define __USER_MANAGER_H__
  19
  20 #include <Protocol/UserCredential.h>
  21
  22 ///
  23 /// Global ID for the User Manager Protocol
  24 ///
  25 #define EFI_USER_MANAGER_PROTOCOL_GUID \
  26   { \
  27     0x6fd5b00c, 0xd426, 0x4283, { 0x98, 0x87, 0x6c, 0xf5, 0xcf, 0x1c, 0xb1, 0xfe } \
  28   }
  29
  30 #define EFI_EVENT_GROUP_USER_PROFILE_CHANGED \
  31   { \
  32     0xbaf1e6de, 0x209e, 0x4adb, { 0x8d, 0x96, 0xfd, 0x8b, 0x71, 0xf3, 0xf6, 0x83 } \
  33   }
  34
  35 typedef struct _EFI_USER_MANAGER_PROTOCOL  EFI_USER_MANAGER_PROTOCOL;
  36
  37 /**
  38   Create a new user profile.
  39
  40   This function creates a new user profile with only a new user identifier attached and returns its
  41   handle. The user profile is non-volatile, but the handle User can change across reboots.
  42
  43   @param[in]  This               Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
  44   @param[out] User               On return, points to the new user profile handle.
  45                                  The user profile handle is unique only during this boot.
  46
  47   @retval EFI_SUCCESS            User profile was successfully created.
  48   @retval EFI_ACCESS_DENIED      Current user does not have sufficient permissions to create a user profile.
  49   @retval EFI_UNSUPPORTED        Creation of new user profiles is not supported.
  50   @retval EFI_INVALID_PARAMETER  The User parameter is NULL.
  51 **/
  52 typedef
  53 EFI_STATUS
  54 (EFIAPI *EFI_USER_PROFILE_CREATE)(
  55   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
  56   OUT      EFI_USER_PROFILE_HANDLE    *User
  57   );
  58
  59 /**
  60   Delete an existing user profile.
  61
  62   @param[in] This                Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
  63   @param[in] User                User profile handle.
  64
  65   @retval EFI_SUCCESS            User profile was successfully deleted.
  66   @retval EFI_ACCESS_DENIED      Current user does not have sufficient permissions to delete a user
  67                                  profile or there is only one user profile.
  68   @retval EFI_UNSUPPORTED        Deletion of new user profiles is not supported.
  69   @retval EFI_INVALID_PARAMETER  User does not refer to a valid user profile.
  70 **/
  71 typedef
  72 EFI_STATUS
  73 (EFIAPI *EFI_USER_PROFILE_DELETE)(
  74   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
  75   IN       EFI_USER_PROFILE_HANDLE    User
  76   );
  77
  78 /**
  79   Enumerate all of the enrolled users on the platform.
  80
  81   This function returns the next enrolled user profile. To retrieve the first user profile handle, point
  82   User at a NULL. Each subsequent call will retrieve another user profile handle until there are no
  83   more, at which point User will point to NULL.
  84
  85   @param[in]     This            Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
  86   @param[in,out] User            On entry, points to the previous user profile handle or NULL to
  87                                  start enumeration. On exit, points to the next user profile handle
  88                                  or NULL if there are no more user profiles.
  89
  90   @retval EFI_SUCCESS            Next enrolled user profile successfully returned.
  91   @retval EFI_ACCESS_DENIED      Next enrolled user profile was not successfully returned.
  92   @retval EFI_INVALID_PARAMETER  The User parameter is NULL.
  93 **/
  94 typedef
  95 EFI_STATUS
  96 (EFIAPI *EFI_USER_PROFILE_GET_NEXT)(
  97   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
  98   IN OUT   EFI_USER_PROFILE_HANDLE    *User
  99   );
 100
 101 /**
 102   Return the current user profile handle.
 103
 104   @param[in]  This               Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
 105   @param[out] CurrentUser        On return, points to the current user profile handle.
 106
 107   @retval EFI_SUCCESS            Current user profile handle returned successfully.
 108   @retval EFI_INVALID_PARAMETER  The CurrentUser parameter is NULL.
 109 **/
 110 typedef
 111 EFI_STATUS
 112 (EFIAPI *EFI_USER_PROFILE_CURRENT)(
 113   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
 114   OUT      EFI_USER_PROFILE_HANDLE    *CurrentUser
 115   );
 116
 117 /**
 118   Identify a user.
 119
 120   Identify the user and, if authenticated, returns the user handle and changes the current user profile.
 121   All user information marked as private in a previously selected profile is no longer available for
 122   inspection.
 123   Whenever the current user profile is changed then the an event with the GUID
 124   EFI_EVENT_GROUP_USER_PROFILE_CHANGED is signaled.
 125
 126   @param[in]  This               Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
 127   @param[out] User               On return, points to the user profile handle for the current user profile.
 128
 129   @retval EFI_SUCCESS            User was successfully identified.
 130   @retval EFI_ACCESS_DENIED      User was not successfully identified.
 131   @retval EFI_INVALID_PARAMETER  The User parameter is NULL.
 132 **/
 133 typedef
 134 EFI_STATUS
 135 (EFIAPI *EFI_USER_PROFILE_IDENTIFY)(
 136   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
 137   OUT      EFI_USER_PROFILE_HANDLE    *User
 138   );
 139
 140 /**
 141   Find a user using a user information record.
 142
 143   This function searches all user profiles for the specified user information record. The search starts
 144   with the user information record handle following UserInfo and continues until either the
 145   information is found or there are no more user profiles.
 146   A match occurs when the Info.InfoType field matches the user information record type and the
 147   user information record data matches the portion of Info passed the EFI_USER_INFO header.
 148
 149   @param[in]     This      Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
 150   @param[in,out] User      On entry, points to the previously returned user profile handle or NULL to start
 151                            searching with the first user profile. On return, points to the user profile handle or
 152                            NULL if not found.
 153   @param[in,out] UserInfo  On entry, points to the previously returned user information handle or NULL to start
 154                            searching with the first. On return, points to the user information handle of the user
 155                            information record or NULL if not found. Can be NULL, in which case only one user
 156                            information record per user can be returned.
 157   @param[in]     Info      Points to the buffer containing the user information to be compared to the user
 158                            information record. If NULL, then only the user information record type is compared.
 159                            If InfoSize is 0, then the user information record must be empty.
 160
 161   @param[in]     InfoSize  The size of Info, in bytes.
 162
 163   @retval EFI_SUCCESS      User information was found. User points to the user profile handle and
 164                            UserInfo points to the user information handle.
 165   @retval EFI_NOT_FOUND    User information was not found. User points to NULL and UserInfo points to NULL.
 166 **/
 167 typedef
 168 EFI_STATUS
 169 (EFIAPI *EFI_USER_PROFILE_FIND)(
 170   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
 171   IN OUT   EFI_USER_PROFILE_HANDLE    *User,
 172   IN OUT   EFI_USER_INFO_HANDLE       *UserInfo OPTIONAL,
 173   IN CONST EFI_USER_INFO              *Info,
 174   IN       UINTN                      InfoSize
 175   );
 176
 177 /**
 178   Called by credential provider to notify of information change.
 179
 180   This function allows the credential provider to notify the User Identity Manager when user status has
 181   changed while deselected.
 182   If the User Identity Manager doesn't support asynchronous changes in credentials, then this function
 183   should return EFI_UNSUPPORTED.
 184   If the User Identity Manager supports this, it will call User() to get the user identifier and then
 185   GetNextInfo() and GetInfo() in the User Credential Protocol to get all of the information
 186   from the credential and add it.
 187
 188   @param[in] This          Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
 189   @param[in] Changed       Handle on which is installed an instance of the
 190                            EFI_USER_CREDENTIAL_PROTOCOL where the user has changed.
 191
 192   @retval EFI_SUCCESS      The User Identity Manager has handled the notification.
 193   @retval EFI_NOT_READY    The function was called while the specified credential provider was not selected.
 194   @retval EFI_UNSUPPORTED  The User Identity Manager doesn't support asynchronous notifications.
 195 **/
 196 typedef
 197 EFI_STATUS
 198 (EFIAPI *EFI_USER_PROFILE_NOTIFY)(
 199   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
 200   IN       EFI_HANDLE                 Changed
 201   );
 202
 203 /**
 204   Return information attached to the user.
 205
 206   This function returns user information. The format of the information is described in User
 207   Information. The function may return EFI_ACCESS_DENIED if the information is marked private
 208   and the handle specified by User is not the current user profile. The function may return
 209   EFI_ACCESS_DENIED if the information is marked protected and the information is associated
 210   with a credential provider for which the user has not been authenticated.
 211
 212   @param[in]     This           Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
 213   @param[in]     User           Handle of the user whose profile will be retrieved.
 214   @param[in]     UserInfo       Handle of the user information data record.
 215   @param[out]    Info           On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user
 216                                 information. If the buffer is too small to hold the information, then
 217                                 EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the
 218                                 number of bytes actually required.
 219   @param[in,out] InfoSize       On entry, points to the size of Info. On return, points to the size of the user
 220                                 information.
 221
 222   @retval EFI_SUCCESS           Information returned successfully.
 223   @retval EFI_ACCESS_DENIED     The information about the specified user cannot be accessed by the current user.
 224   @retval EFI_BUFFER_TOO_SMALL  The number of bytes specified by *InfoSize is too small to hold
 225                                 the returned data. The actual size required is returned in *InfoSize.
 226 **/
 227 typedef
 228 EFI_STATUS
 229 (EFIAPI *EFI_USER_PROFILE_GET_INFO)(
 230   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
 231   IN       EFI_USER_PROFILE_HANDLE    User,
 232   IN       EFI_USER_INFO_HANDLE       UserInfo,
 233   OUT      EFI_USER_INFO              *Info,
 234   IN OUT   UINTN                      *InfoSize
 235   );
 236
 237 /**
 238   Add or update user information.
 239
 240   This function changes user information.  If NULL is pointed to by UserInfo, then a new user
 241   information record is created and its handle is returned in UserInfo. Otherwise, the existing one is
 242   replaced.
 243   If EFI_USER_INFO_EXCLUSIVE is specified in Info and a user information record of the same
 244   type already exists in the user profile, then EFI_ACCESS_DENIED will be returned and
 245   UserInfo will point to the handle of the existing record.
 246
 247   @param[in]     This             Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
 248   @param[in]     User             Handle of the user whose profile will be retrieved.
 249   @param[in,out] UserInfo         Handle of the user information data record.
 250   @param[in]     Info             On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user
 251                                   information. If the buffer is too small to hold the information, then
 252                                   EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the
 253                                   number of bytes actually required.
 254   @param[in]     InfoSize         On entry, points to the size of Info. On return, points to the size of the user
 255                                   information.
 256
 257   @retval EFI_SUCCESS             Information returned successfully.
 258   @retval EFI_ACCESS_DENIED       The record is exclusive.
 259   @retval EFI_SECURITY_VIOLATION  The current user does not have permission to change the specified
 260                                   user profile or user information record.
 261 **/
 262 typedef
 263 EFI_STATUS
 264 (EFIAPI *EFI_USER_PROFILE_SET_INFO)(
 265   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
 266   IN       EFI_USER_PROFILE_HANDLE    User,
 267   IN OUT   EFI_USER_INFO_HANDLE       *UserInfo,
 268   IN CONST EFI_USER_INFO              *Info,
 269   IN       UINTN                      InfoSize
 270   );
 271
 272 /**
 273   Delete user information.
 274
 275   Delete the user information attached to the user profile specified by the UserInfo.
 276
 277   @param[in] This            Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
 278   @param[in] User            Handle of the user whose information will be deleted.
 279   @param[in] UserInfo        Handle of the user information to remove.
 280
 281   @retval EFI_SUCCESS        User information deleted successfully.
 282   @retval EFI_NOT_FOUND      User information record UserInfo does not exist in the user profile.
 283   @retval EFI_ACCESS_DENIED  The current user does not have permission to delete this user information.
 284 **/
 285 typedef
 286 EFI_STATUS
 287 (EFIAPI *EFI_USER_PROFILE_DELETE_INFO)(
 288   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
 289   IN       EFI_USER_PROFILE_HANDLE    User,
 290   IN       EFI_USER_INFO_HANDLE       UserInfo
 291   );
 292
 293 /**
 294   Enumerate user information of all the enrolled users on the platform.
 295
 296   This function returns the next user information record. To retrieve the first user information record
 297   handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information
 298   record handle until there are no more, at which point UserInfo will point to NULL.
 299
 300   Note: in-consistency between code and the UEFI 2.3 specification that the type of the User parameter
 301   is EFI_USER_PROFILE_HANDLE. It should be spec error and wait for spec update.
 302
 303   @param[in]     This      Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
 304   @param[in]     User      Handle of the user whose information will be deleted.
 305   @param[in,out] UserInfo  Handle of the user information to remove.
 306
 307   @retval EFI_SUCCESS      User information returned.
 308   @retval EFI_NOT_FOUND    No more user information found.
 309 **/
 310 typedef
 311 EFI_STATUS
 312 (EFIAPI *EFI_USER_PROFILE_GET_NEXT_INFO)(
 313   IN CONST EFI_USER_MANAGER_PROTOCOL  *This,
 314   IN       EFI_USER_PROFILE_HANDLE    User,
 315   IN OUT   EFI_USER_INFO_HANDLE       *UserInfo
 316   );
 317
 318 ///
 319 /// This protocol provides the services used to manage user profiles.
 320 ///
 321 struct _EFI_USER_MANAGER_PROTOCOL {
 322   EFI_USER_PROFILE_CREATE         Create;
 323   EFI_USER_PROFILE_DELETE         Delete;
 324   EFI_USER_PROFILE_GET_NEXT       GetNext;
 325   EFI_USER_PROFILE_CURRENT        Current;
 326   EFI_USER_PROFILE_IDENTIFY       Identify;
 327   EFI_USER_PROFILE_FIND           Find;
 328   EFI_USER_PROFILE_NOTIFY         Notify;
 329   EFI_USER_PROFILE_GET_INFO       GetInfo;
 330   EFI_USER_PROFILE_SET_INFO       SetInfo;
 331   EFI_USER_PROFILE_DELETE_INFO    DeleteInfo;
 332   EFI_USER_PROFILE_GET_NEXT_INFO  GetNextInfo;
 333 };
 334
 335 extern EFI_GUID gEfiUserManagerProtocolGuid;
 336 extern EFI_GUID gEfiEventUserProfileChangedGuid;
 337
 338 #endif