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