SecurityServer/Authorization/Authorization.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 /*
  20  *  Authorization.h
  21  *  Authorization -- APIs for implementing access control in applications and daemons.
  22  *
  23  *    Copyright (C) 2000, 2001 by Apple Computer, Inc., all rights reserved
  24  *
  25  */
  26
  27 #if !defined(__Authorization__)
  28 #define __Authorization__ 1
  29
  30 #include <CoreServices/../Frameworks/CarbonCore.framework/Headers/MacTypes.h>
  31 #include <stdio.h>
  32
  33 #if defined(__cplusplus)
  34 extern "C" {
  35 #endif
  36
  37
  38 /*!
  39         @header Authorization
  40         Version 1.0 10/16/2000
  41
  42         The Authorization API contains all the APIs that a application or tool that need pre-authorization or need an authorization desision made.
  43
  44         A typical use cases are a preference panel that would start off calling AuthorizationCreate() (without UI) to get an authorization object.  Then call AuthorizationCopyRights() to figure out what is currently allowed.
  45
  46         If any of the operations that the preference panel wishes to perform are currently not allowed the lock icon in the window would show up in the locked state.  Otherwise it would show up unlocked.
  47
  48         When the user locks the lock AuthorizationFree() is called with the kAuthorizationFreeFlagDestroy to destroy any authorization rights that have been aquired.
  49
  50         When the user unlocks the lock AuthorizationCreate() is called with the kAuthorizationFlagInteractionAllowed and kAuthorizationFlagExtendRights flags to obtain all required rights.  The old authorization object can be freed by calling AuthorizationFree() with no flags.
  51
  52 */
  53
  54
  55
  56 /*!
  57         @define kAuthorizationEmptyEnvironment
  58         Parameter to specify to AuthorizationCreate when no environment is being provided.
  59 */
  60 #define kAuthorizationEmptyEnvironment  NULL
  61
  62
  63 /*!
  64         @enum AuthorizationStatus
  65         Error codes returned by Authorization API.
  66 */
  67 enum {
  68         errAuthorizationSuccess                                 = 0,      /* The operation completed successfully. */
  69     errAuthorizationInvalidSet                          = -60001, /* The set parameter is invalid. */
  70     errAuthorizationInvalidRef                          = -60002, /* The authorization parameter is invalid. */
  71     errAuthorizationInvalidTag                          = -60003, /* The tag parameter is invalid. */
  72     errAuthorizationInvalidPointer                      = -60004, /* The authorizedRights parameter is invalid. */
  73         errAuthorizationDenied                                  = -60005, /* The authorization was denied. */
  74         errAuthorizationCanceled                                = -60006, /* The authorization was cancled by the user. */
  75         errAuthorizationInteractionNotAllowed   = -60007, /* The authorization was denied since no user interaction was possible. */
  76         errAuthorizationInternal                = -60008, /* something else went wrong */
  77         errAuthorizationExternalizeNotAllowed   = -60009, /* authorization externalization denied */
  78         errAuthorizationInternalizeNotAllowed   = -60010, /* authorization internalization denied */
  79         errAuthorizationInvalidFlags            = -60011, /* invalid option flag(s) */
  80         errAuthorizationToolExecuteFailure      = -60031, /* cannot execute privileged tool */
  81         errAuthorizationToolEnvironmentError    = -60032  /* privileged tool environment error */
  82 };
  83
  84
  85 /*!
  86         @enum AuthorizationFlags
  87         Optional flags passed in to serveral Authorization APIs. See the description of AuthorizationCreate, AuthorizationCopyRights and AuthorizationFree for a description of how they affect those calls.
  88 */
  89 enum {
  90         kAuthorizationFlagDefaults              = 0,
  91         kAuthorizationFlagInteractionAllowed    = (1 << 0),
  92         kAuthorizationFlagExtendRights                  = (1 << 1),
  93         kAuthorizationFlagPartialRights                 = (1 << 2),
  94         kAuthorizationFlagDestroyRights                 = (1 << 3),
  95         kAuthorizationFlagPreAuthorize                  = (1 << 4),
  96
  97         // private bits (do not use)
  98         kAuthorizationFlagNoData                = (1 << 20)
  99 };
 100
 101
 102 /*!
 103         @typedef AuthorizationFlags
 104         Optional flags passed in to AuthorizationCreate.
 105 */
 106 typedef UInt32 AuthorizationFlags;
 107
 108
 109 /*!
 110         @enum AuthorizationRightFlags
 111         Flags returned in the flags field of ItemSet Items when calling AuthorizationCopyRights().
 112 */
 113 enum {
 114         kAuthorizationFlagCanNotPreAuthorize    = (1 << 0)
 115 };
 116
 117
 118 /*!
 119         @typedef AuthorizationRef
 120         Opaque reference to an authorization object.
 121 */
 122 typedef const struct AuthorizationOpaqueRef                     *AuthorizationRef;
 123
 124
 125 /*!
 126         @typedef AuthorizationString
 127         A zero terminated string in UTF-8 encoding.
 128 */
 129 typedef const char *AuthorizationString;
 130
 131
 132 /*!
 133         @typedef AuthorizationItem
 134         Each AuthorizationItem describes a single string-named item with optional
 135         parameter value. The value must be contiguous memory of valueLength bytes;
 136         internal structure is defined separately for each name.
 137
 138         @param name name of the item, as an AuthorizationString. Mandatory.
 139         @param value Pointer to the optional parameter value associated with name.
 140         Must be NULL if no parameter value.
 141         @param valueLength Number of bytes in parameter value. Must be zero if no parameter.
 142         @param reserved Reserved field. Must be set to NULL on creation. Do not modify after that.
 143 */
 144 typedef struct {
 145         AuthorizationString name;
 146         UInt32 valueLength;
 147         void *value;
 148         UInt32 flags;
 149 } AuthorizationItem;
 150
 151
 152 /*!
 153         @typedef AuthorizationItemSet
 154         An AuthorizationItemSet structure represents a set of zero or more AuthorizationItems.  Since it is a set it should not contain any identical AuthorizationItems.
 155
 156         @param count Number of items identified by items.
 157         @param items Pointer to an array of items.
 158 */
 159 typedef struct {
 160         UInt32 count;
 161         AuthorizationItem *items;
 162 } AuthorizationItemSet;
 163
 164
 165
 166 /*!
 167         @typedef AuthorizationExternalForm
 168         An AuthorizationExternalForm structure can hold the externalized form of
 169         an AuthorizationRef. As such, it can be transmitted across IPC channels
 170         to other processes, which can re-internalize it to recover a valid AuthorizationRef
 171         handle.
 172         The data contained in an AuthorizationExternalForm should be considered opaque.
 173
 174         SECURITY NOTE: Applications should take care to not disclose the AuthorizationExternalForm to
 175         potential attackers since it would authorize rights to them.
 176 */
 177 enum {
 178         kAuthorizationExternalFormLength = 32
 179 };
 180
 181 typedef struct {
 182         char bytes[kAuthorizationExternalFormLength];
 183 } AuthorizationExternalForm;
 184
 185
 186
 187 /*!
 188         @typedef AuthorizationRights
 189         An AuthorizationItemSet representing a set of rights each with an associated argument (value).
 190         Each argument value is as defined for the specific right they belong to.  Argument values may not contain pointers as the should be copyable to different address spaces.
 191 */
 192 typedef AuthorizationItemSet AuthorizationRights;
 193
 194
 195 /*!
 196         @typedef AuthorizationEnvironment
 197         An AuthorizationItemSet representing environmental information of potential use
 198         to authorization decisions.
 199 */
 200 typedef AuthorizationItemSet AuthorizationEnvironment;
 201
 202
 203 /*!
 204     @function AuthorizationCreate
 205     Create a new autorization object which can be used in other authorization calls.  When the authorization is no longer needed AuthorizationFree should be called.
 206
 207         When the kAuthorizationFlagInteractionAllowed flag is set, user interaction will happen when required.  Failing to set this flag will result in this call failing with a errAuthorizationInteractionNotAllowed status when interaction is required.
 208
 209         Setting the kAuthorizationFlagExtendRights flag will extend the currently available rights. If this flag is set the returned AuthorizationRef will grant all the rights requested when errAuthorizationSuccess is returned. If this flag is not set the operation will almost certainly succeed, but no attempt will be made to make the requested rights availible.
 210                 Call AuthorizationCopyRights to figure out which of the requested rights are granted by the returned AuthorizationRef.
 211
 212         Setting the kAuthorizationFlagPartialRights flag will cause this call to succeed if only some of the requested rights are being granted by the returned AuthorizationRef. Unless this flag is set this API will fail if not all the requested rights could be obtained.
 213
 214         Setting the kAuthorizationFlagDestroyRights flag will prevent any rights obtained during this call from being preserved after returning from this API (This is most useful when the authorization parameter is NULL and the caller doesn't want to affect the session state in any way).
 215
 216         Setting the kAuthorizationFlagPreAuthorize flag will pre authorize the requested rights so that at a later time -- by calling AuthorizationMakeExternalForm() follow by AuthorizationCreateFromExternalForm() -- the obtained rights can be used in a different process.  Rights that can't be preauthorized will be treated as if they were authorized for the sake of returning an error (in other words if all rights are either authorized or could not be preauthorized this call will still succeed).
 217                 The rights which could not be preauthorized are not currently authorized and may fail to authorize when a later call to AuthorizationCopyRights() is made, unless the kAuthorizationFlagExtendRights and kAuthorizationFlagInteractionAllowed flags are set.  Even then they might still fail if the user does not supply the correct credentials.
 218                 The reason for passing in this flag is to provide correct audit trail information and to avoid unnecessary user interaction.
 219
 220     @param rights (input/optional) An AuthorizationItemSet containing rights for which authorization is being requested.  If none are specified the resulting AuthorizationRef will authorize nothing at all.
 221     @param environment (input/optional) An AuthorizationItemSet containing enviroment state used when making the autorization decision.  See the AuthorizationEnvironment type for details.
 222     @param flags (input) options specified by the AuthorizationFlags enum.  set all unused bits to zero to allow for future expansion.
 223     @param authorization (output optional) A pointer to an AuthorizationRef to be returned.  When the returned AuthorizationRef is no longer needed AuthorizationFree should be called to prevent anyone from using the aquired rights.  If NULL is specified no new rights are returned, but the system will attempt to authorize all the requested rights and return the appropriate status.
 224
 225     @result errAuthorizationSuccess 0 authorization or all requested rights succeeded.
 226
 227         errAuthorizationDenied -60005 The authorization for one or more of the requested rights was denied.
 228
 229         errAuthorizationCanceled -60006 The authorization was cancled by the user.
 230
 231         errAuthorizationInteractionNotAllowed -60007 The authorization was denied since no interaction with the user was allowed.
 232 */
 233 OSStatus AuthorizationCreate(const AuthorizationRights *rights,
 234         const AuthorizationEnvironment *environment,
 235         AuthorizationFlags flags,
 236         AuthorizationRef *authorization);
 237
 238
 239 /*!
 240     @function AuthorizationFree
 241     Destroy an AutorizationRef object. If the kAuthorizationFreeFlagDestroy flag is passed,
 242         any rights associated with the authorization are lost. Otherwise, only local resources
 243         are released, and the rights may still be available to other clients.
 244
 245         Setting the kAuthorizationFlagDestroyRights flag will prevent any rights that were obtained by the specified authorization object to be preserved after returning from this API.  This effectivaly locks down all potentially shared authorizations.
 246
 247     @param authorization (input) The authorization object on which this operation is performed.
 248
 249         @param flags (input) Bit mask of option flags to this call.
 250
 251     @result errAuthorizationSuccess 0 No error.
 252
 253     errAuthorizationInvalidRef -60002 The authorization parameter is invalid.
 254 */
 255 OSStatus AuthorizationFree(AuthorizationRef authorization, AuthorizationFlags flags);
 256
 257
 258 /*!
 259         @function AuthorizationCopyRights
 260     Given a set of rights, return the subset that is currently authorized
 261     by the AuthorizationRef given.
 262
 263         When the kAuthorizationFlagInteractionAllowed flag is set, user interaction will happen when required.  Failing to set this flag will result in this call failing with a errAuthorizationInteractionNotAllowed status when interaction is required.
 264
 265         Setting the kAuthorizationFlagExtendRights flag will extend the currently available rights.
 266
 267         Setting the kAuthorizationFlagPartialRights flag will cause this call to succeed if only some of the requested rights are being granted by the returned AuthorizationRef.  Unless this flag is set this API will fail if not all the requested rights could be obtained.
 268
 269         Setting the kAuthorizationFlagDestroyRights flag will prevent any additional rights obtained during this call from being preserved after returning from this API.
 270
 271         Setting the kAuthorizationFlagPreAuthorize flag will pre authorize the requested rights so that at a later time -- by calling AuthorizationMakeExternalForm() follow by AuthorizationCreateFromExternalForm() -- the obtained rights can be used in a different process.  Rights that can't be preauthorized will be treated as if they were authorized for the sake of returning an error (in other words if all rights are either authorized or could not be preauthorized this call will still succeed), and they will be returned in authorizedRights with their kAuthorizationFlagCanNotPreAuthorize bit in the flags field set to 1.
 272                 The rights which could not be preauthorized are not currently authorized and may fail to authorize when a later call to AuthorizationCopyRights() is made, unless the kAuthorizationFlagExtendRights and kAuthorizationFlagInteractionAllowed flags are set.  Even then they might still fail if the user does not supply the correct credentials.
 273                 The reason for passing in this flag is to provide correct audit trail information and to avoid unnecessary user interaction.
 274
 275         Setting the kAuthorizationFlagPreAuthorize flag will pre authorize the requested rights so that at a later time -- by calling AuthorizationMakeExternalForm() follow by AuthorizationCreateFromExternalForm() -- the obtained rights can be used in a different process.  When this flags is specified rights that can't be preauthorized will be returned as if they were authorized with their kAuthorizationFlagCanNotPreAuthorize bit in the flags field set to 1.  These rights are not currently authorized and may fail to authorize later unless kAuthorizationFlagExtendRights and kAuthorizationFlagInteractionAllowed flags are set when the actual authorization is done.  And even then they might still fail if the user does not supply the correct credentials.
 276
 277     @param authorization (input) The authorization object on which this operation is performed.
 278     @param rights (input) A rights set (see AuthorizationCreate).
 279     @param environment (input/optional) An AuthorizationItemSet containing enviroment state used when making the autorization decision.  See the AuthorizationEnvironment type for details.
 280     @param flags (input) options specified by the AuthorizationFlags enum.  set all unused bits to zero to allow for future expansion.
 281     @param authorizedRights (output/optional) A pointer to a newly allocated AuthorizationInfoSet in which the authorized subset of rights are returned (authorizedRights should be deallocated by calling AuthorizationFreeInfoSet() when it is no longer needed).  If NULL the only information returned is the status.  Note that if the kAuthorizationFlagPreAuthorize flag was specified rights that could not be preauthorized are returned in authorizedRights, but their flags contains the kAuthorizationFlagCanNotPreAuthorize bit.
 282
 283     @result errAuthorizationSuccess 0 No error.
 284
 285         errAuthorizationInvalidRef -60002 The authorization parameter is invalid.
 286
 287     errAuthorizationInvalidSet -60001 The rights parameter is invalid.
 288
 289     errAuthorizationInvalidPointer -60004 The authorizedRights parameter is invalid.
 290 */
 291 OSStatus AuthorizationCopyRights(AuthorizationRef authorization,
 292         const AuthorizationRights *rights,
 293         const AuthorizationEnvironment *environment,
 294         AuthorizationFlags flags,
 295         AuthorizationRights **authorizedRights);
 296
 297
 298 /*!
 299         @function AuthorizationCopyInfo
 300         Returns sideband information (e.g. access credentials) obtained from a call to AuthorizationCreate.  The format of this data depends of the tag specified.
 301
 302     @param authorization (input) The authorization object on which this operation is performed.
 303     @param tag (input/optional) An optional string tag specifing which sideband information should be returned.  When NULL is specified all available information is returned.
 304     @param flags (input) options specified by the AuthorizationFlags enum.  set all unused bits to zero to allow for future expansion.
 305     @param info (output) A pointer to a newly allocated AuthorizationInfoSet in which the requested sideband infomation is returned (info should be deallocated by calling AuthorizationFreeInfoSet() when it is no longer needed).
 306
 307     @result errAuthorizationSuccess 0 No error.
 308
 309     errAuthorizationInvalidRef -60002 The authorization parameter is invalid.
 310
 311     errAuthorizationInvalidTag -60003 The tag parameter is invalid.
 312
 313     errAuthorizationInvalidPointer -60004 The info parameter is invalid.
 314 */
 315 OSStatus AuthorizationCopyInfo(AuthorizationRef authorization,
 316         AuthorizationString tag,
 317         AuthorizationItemSet **info);
 318
 319
 320 /*!
 321         @function AuthorizationMakeExternalForm
 322         Turn an Authorization into an external "byte blob" form so it can be
 323         transmitted to another process.
 324         Note that *storing* the external form somewhere will probably not do what
 325         you want, since authorizations are bounded by sessions, processes, and possibly
 326         time limits. This is for online transmission of authorizations.
 327
 328         @param authorization The (valid) authorization reference to externalize
 329         @param extForm Pointer to an AuthorizationExternalForm variable to fill.
 330
 331         @result TBD
 332 */
 333 OSStatus AuthorizationMakeExternalForm(AuthorizationRef authorization,
 334         AuthorizationExternalForm *extForm);
 335
 336
 337 /*!
 338         @function AuthorizationCreateFromExternalForm
 339         Turn an Authorization into an external "byte blob" form so it can be
 340         transmitted to another process.
 341         Note that *storing* the external form somewhere will probably not do what
 342         you want, since authorizations are bounded by sessions, processes, and possibly
 343         time limits. This is for online transmission of authorizations.
 344
 345         @param extForm Pointer to an AuthorizationExternalForm value.
 346         @param authorization Will be filled with a valid AuthorizationRef on success.
 347
 348         @result TBD
 349 */
 350 OSStatus AuthorizationCreateFromExternalForm(const AuthorizationExternalForm *extForm,
 351         AuthorizationRef *authorization);
 352
 353
 354 /*!
 355         @function AuthorizationFreeItemSet
 356         Release the memory allocated for an AuthorizationItemSet that was allocated
 357         by an API call.
 358
 359     @param set The AuthorizationItemSet to deallocate.
 360
 361     @result errAuthorizationSuccess 0 No error.
 362
 363     errAuthorizationInvalidSet -60001 The set parameter is invalid.
 364 */
 365 OSStatus AuthorizationFreeItemSet(AuthorizationItemSet *set);
 366
 367
 368 /*!
 369         @function AuthorizationExecuteWithPrivileges
 370         Run an executable tool with enhanced privileges after passing
 371         suitable authorization procedures.
 372
 373         @param authorization An authorization reference that is used to authorize
 374         access to the enhanced privileges. It is also passed to the tool for
 375         further access control.
 376         @param pathToTool Full pathname to the tool that should be executed
 377         with enhanced privileges.
 378         @param options Option bits (reserved). Must be zero.
 379         @param arguments An argv-style vector of strings to be passed to the tool.
 380         @param communicationsPipe Assigned a UNIX stdio FILE pointer for
 381         a bidirectional pipe to communicate with the tool. The tool will have
 382         this pipe as its standard I/O channels (stdin/stdout). If NULL, do not
 383         establish a communications pipe.
 384  */
 385 OSStatus AuthorizationExecuteWithPrivileges(AuthorizationRef authorization,
 386         const char *pathToTool,
 387         AuthorizationFlags options,
 388         char * const *arguments,
 389         FILE **communicationsPipe);
 390
 391
 392 /*!
 393         @function AuthorizationCopyPrivilegedReference
 394         From within a tool launched via the AuthorizationExecuteWithPrivileges function
 395         ONLY, retrieve the AuthorizationRef originally passed to that function.
 396         While AuthorizationExecuteWithPrivileges already verified the authorization to
 397         launch your tool, the tool may want to avail itself of any additional pre-authorizations
 398         the caller may have obtained through that reference.
 399  */
 400 OSStatus AuthorizationCopyPrivilegedReference(AuthorizationRef *authorization,
 401         AuthorizationFlags flags);
 402
 403
 404 #if defined(__cplusplus)
 405 }
 406 #endif
 407
 408 #endif /* ! __Authorization__ */