SecurityServer/Authorization/Authorization.h

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