OSX/libsecurity_authorization/lib/Authorization.h

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