AuthorizationPriv.h
1 /* 2 * Copyright (c) 2002-2004,2011-2014 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 * AuthorizationPriv.h -- Authorization SPIs 27 * Private APIs for implementing access control in applications and daemons. 28 * 29 */ 30 31 #ifndef _SECURITY_AUTHORIZATIONPRIV_H_ 32 #define _SECURITY_AUTHORIZATIONPRIV_H_ 33 34 #include <Security/Authorization.h> 35 #include <Security/AuthSession.h> 36 #include <sys/types.h> // uid_t 37 #include <mach/message.h> 38 #include <CoreFoundation/CFDictionary.h> 39 40 #if defined(__cplusplus) 41 extern "C" { 42 #endif 43 44 45 /*! 46 @header AuthorizationPriv 47 Version 1.1 04/2003 48 49 This header contains private APIs for authorization services. 50 This is the private extension of <Security/Authorization.h>, a public header file. 51 */ 52 53 /*! 54 @enum Private (for now) AuthorizationFlags 55 */ 56 enum { 57 kAuthorizationFlagLeastPrivileged = (1 << 5), 58 kAuthorizationFlagSheet = (1 << 6), 59 kAuthorizationFlagIgnorePasswordOnly = (1 << 7), 60 kAuthorizationFlagIgnoreDarkWake = (1 << 8), 61 }; 62 63 /*! 64 @enum Private operations for AuthorizationHandlePreloginOverride 65 */ 66 enum { 67 kAuthorizationOverrideOperationSet, 68 kAuthorizationOverrideOperationReset, 69 kAuthorizationOverrideOperationQuery 70 }; 71 72 /*! 73 @function AuthorizationCreateWithAuditToken 74 @abstract Create a AuthorizationRef for the process that sent the mach message 75 represented by the audit token. Requires root. 76 @param token The audit token of a mach message 77 @param environment (input/optional) An AuthorizationItemSet containing environment state used when making the autorization decision. See the AuthorizationEnvironment type for details. 78 @param flags (input) options specified by the AuthorizationFlags enum. set all unused bits to zero to allow for future expansion. 79 @param authorization (output) 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. 80 81 @result errAuthorizationSuccess 0 authorization or all requested rights succeeded. 82 83 errAuthorizationDenied -60005 The authorization for one or more of the requested rights was denied. 84 */ 85 86 OSStatus AuthorizationCreateWithAuditToken(audit_token_t token, 87 const AuthorizationEnvironment * _Nullable environment, 88 AuthorizationFlags flags, 89 AuthorizationRef _Nullable * _Nonnull authorization); 90 91 /*! 92 @function AuthorizationExecuteWithPrivilegesExternalForm 93 Run an executable tool with enhanced privileges after passing 94 suitable authorization procedures. 95 96 @param extForm authorization in external form that is used to authorize 97 access to the enhanced privileges. It is also passed to the tool for 98 further access control. 99 @param pathToTool Full pathname to the tool that should be executed 100 with enhanced privileges. 101 @param flags Option bits (reserved). Must be zero. 102 @param arguments An argv-style vector of strings to be passed to the tool. 103 @param communicationsPipe Assigned a UNIX stdio FILE pointer for 104 a bidirectional pipe to communicate with the tool. The tool will have 105 this pipe as its standard I/O channels (stdin/stdout). If NULL, do not 106 establish a communications pipe. 107 108 @discussion This function has been deprecated and should no longer be used. 109 Use a launchd-launched helper tool and/or the Service Mangement framework 110 for this functionality. 111 */ 112 113 OSStatus AuthorizationExecuteWithPrivilegesExternalForm(const AuthorizationExternalForm * _Nonnull extForm, 114 const char * _Nonnull pathToTool, 115 AuthorizationFlags flags, 116 char * _Nonnull const * _Nonnull arguments, 117 FILE * _Nullable * _Nonnull communicationsPipe) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA); 118 119 /*! 120 @function AuthorizationExecuteWithPrivileges 121 Run an executable tool with enhanced privileges after passing 122 suitable authorization procedures. 123 @param authorization An authorization reference that is used to authorize 124 access to the enhanced privileges. It is also passed to the tool for 125 further access control. 126 @param pathToTool Full pathname to the tool that should be executed 127 with enhanced privileges. 128 @param options Option bits (reserved). Must be zero. 129 @param arguments An argv-style vector of strings to be passed to the tool. 130 @param communicationsPipe Assigned a UNIX stdio FILE pointer for 131 a bidirectional pipe to communicate with the tool. The tool will have 132 this pipe as its standard I/O channels (stdin/stdout). If NULL, do not 133 establish a communications pipe. 134 135 @discussion This function has been deprecated and should no longer be used. 136 Use a launchd-launched helper tool and/or the Service Mangement framework 137 for this functionality. 138 */ 139 OSStatus AuthorizationExecuteWithPrivileges(AuthorizationRef _Nonnull authorization, 140 const char * _Nonnull pathToTool, 141 AuthorizationFlags options, 142 char * __nonnull const * __nonnull arguments, 143 FILE * __nullable * __nullable communicationsPipe) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA); 144 145 /*! 146 @function AuthorizationCopyRightProperties 147 Returns a dictionary with the properties associated with the given authorization right 148 @param rightName right name for which we need the propertiers 149 @param output CFDictionaryRef which will hold the properties 150 151 */ 152 OSStatus AuthorizationCopyRightProperties(const char * __nonnull rightName, CFDictionaryRef __nullable * __nullable output) __OSX_AVAILABLE_STARTING(__MAC_10_15, __IPHONE_NA); 153 154 /*! 155 @function AuthorizationCopyPrivilegedReference 156 From within a tool launched via the AuthorizationExecuteWithPrivileges function 157 ONLY, retrieve the AuthorizationRef originally passed to that function. 158 While AuthorizationExecuteWithPrivileges already verified the authorization to 159 launch your tool, the tool may want to avail itself of any additional pre-authorizations 160 the caller may have obtained through that reference. 161 162 @discussion This function has been deprecated and should no longer be used. 163 Use a launchd-launched helper tool and/or the Service Mangement framework 164 for this functionality. 165 */ 166 OSStatus AuthorizationCopyPrivilegedReference(AuthorizationRef __nullable * __nonnull authorization, 167 AuthorizationFlags flags) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA); 168 169 /* 170 @function AuthorizationDismiss 171 @abstract Dismisses all Authorization dialogs associated to the calling process. 172 Any active authorization requests will be canceled and return errAuthorizationDenied 173 */ 174 175 OSStatus AuthorizationDismiss(void); 176 177 /*! 178 @function SessionSetDistinguishedUser 179 This function allows the creator of a (new) security session to associate an arbitrary 180 UNIX user identity (uid) with the session. This uid can be retrieved with 181 SessionGetDistinguishedUser by anyone who knows the session's id, and may also 182 be used by the system for identification (but not authentication) purposes. 183 184 This call can only be made by the process that created the session, and only 185 once. 186 187 This is a private API, and is subject to change. 188 189 @param session (input) Session-id for which to set the uid. Can be one of the 190 special constants defined in AuthSession.h. 191 @param user (input) The uid to set. 192 */ 193 OSStatus SessionSetDistinguishedUser(SecuritySessionId session, uid_t user); 194 195 196 /*! 197 @function SessionGetDistinguishedUser 198 Retrieves the distinguished uid of a session as set by the session creator 199 using the SessionSetDistinguishedUser call. 200 201 @param session (input) Session-id for which to set the uid. Can be one of the 202 special constants defined in AuthSession.h. 203 @param user (output) Will receive the uid. Unchanged on error. 204 */ 205 OSStatus SessionGetDistinguishedUser(SecuritySessionId session, uid_t * _Nonnull user); 206 207 /*! 208 @function SessionSetUserPreferences 209 Set preferences from current application context for session (for use during agent interactions). 210 211 @param session (input) Session-id for which to set the user preferences. Can be one of the special constants defined in AuthSession.h. 212 */ 213 OSStatus SessionSetUserPreferences(SecuritySessionId session); 214 215 216 /*! 217 @function AuthorizationEnableSmartCard 218 Enable or disable system login using smartcard or get current status. 219 220 @param authRef (input) The authorization object on which this operation is performed. 221 @param enable (input) desired smartcard login support state, TRUE to enable, FALSE to disable 222 */ 223 OSStatus AuthorizationEnableSmartCard(AuthorizationRef _Nonnull authRef, Boolean enable); 224 225 /*! 226 @function AuthorizationExecuteWithPrivilegesInternal 227 Run an executable tool with enhanced privileges after passing 228 suitable authorization procedures. Allows better control and communication 229 with privileged tool. 230 231 @param authorization An authorization reference that is used to authorize 232 access to the enhanced privileges. It is also passed to the tool for 233 further access control. 234 @param pathToTool Full pathname to the tool that should be executed 235 with enhanced privileges. 236 @param arguments An argv-style vector of strings to be passed to the tool. 237 @param newProcessPid (output, optional) PID of privileged process is stored here. 238 @param uid Desired UID under which privileged tool should be running. 239 @param stdOut File descriptor of the pipe which should be used to receive stdout from the privileged tool, use -1 if not needed. 240 @param stdErr File descriptor of the pipe which should be used to receive stderr from the privileged tool, use -1 if not needed. 241 @param stdIn File descriptor which will contain write-end of the stdin pipe of the privileged tool, use -1 if not needed. 242 @param processFinished This block is called when privileged process finishes. 243 */ 244 OSStatus AuthorizationExecuteWithPrivilegesInternal(const AuthorizationRef _Nonnull authorization, 245 const char * _Nonnull pathToTool, 246 const char * _Nonnull const * _Nonnull arguments, 247 pid_t * _Nullable newProcessPid, 248 const uid_t uid, 249 int stdOut, 250 int stdErr, 251 int stdIn, 252 void(^__nullable processFinished)(const int exitStatus)); 253 254 /*! 255 @function AuthorizationExecuteWithPrivilegesExternalFormInternal 256 Run an executable tool with enhanced privileges after passing 257 suitable authorization procedures. Allows better control and communication 258 with privileged tool. 259 260 @param extAuthorization authorization in external form that is used to authorize 261 access to the enhanced privileges. It is also passed to the tool for 262 further access control. 263 @param pathToTool Full pathname to the tool that should be executed 264 with enhanced privileges. 265 @param arguments An argv-style vector of strings to be passed to the tool. 266 @param newProcessPid (output, optional) PID of privileged process is stored here. 267 @param uid Desired UID under which privileged tool should be running. 268 @param stdOut File descriptor of the pipe which should be used to receive stdout from the privileged tool, use -1 if not needed. 269 @param stdErr File descriptor of the pipe which should be used to receive stderr from the privileged tool, use -1 if not needed. 270 @param stdIn File descriptor which will contain write-end of the stdin pipe of the privileged tool, use -1 if not needed. 271 @param processFinished This block is called when privileged process finishes. 272 */ 273 OSStatus AuthorizationExecuteWithPrivilegesExternalFormInternal(const AuthorizationExternalForm * _Nonnull extAuthorization, 274 const char * _Nonnull pathToTool, 275 const char * _Nullable const * _Nullable arguments, 276 pid_t * _Nullable newProcessPid, 277 const uid_t uid, 278 int stdOut, 279 int stdErr, 280 int stdIn, 281 void(^__nullable processFinished)(const int exitStatus)); 282 283 /*! 284 @function AuthorizationCopyPreloginUserDatabase 285 Fills output with a CFArrayRef with user database from Prelogin volume 286 287 @param volumeUuid Optional uuid of the volume for which user database will be returned. If not set, users from all volumes are returned. 288 @param flags Specifies subset of data required in the output 289 @param output Output array of dictionaries - each dictionary with details for each user 290 */ 291 OSStatus AuthorizationCopyPreloginUserDatabase(const char * _Nullable const volumeUuid, const UInt32 flags, CFArrayRef _Nonnull * _Nonnull output); 292 293 /*! 294 @function AuthorizationCopyPreloginPreferencesValue 295 Fills output with a CFTypeRef of a value of the item 296 297 @param volumeUuid Specifies uuid of the volume for which preferences are stored 298 @param username If NULL, global pref value is queried, otherwise user-specific preferences are queried 299 @param domain preference domain like "com.apple.tokenlogin" 300 @param item specifies name of the item to be returned 301 @param output Output CFTypeRef with the value of the desired preference 302 */ 303 OSStatus AuthorizationCopyPreloginPreferencesValue(const char * _Nonnull const volumeUuid, const char * _Nullable const username, const char * _Nonnull const domain, const char * _Nullable const item, CFTypeRef _Nonnull * _Nonnull output); 304 305 /*! 306 @function AuthorizationHandlePreloginOverride 307 Handles FVUnlock Smartcard Enforcement 308 309 @param volumeUuid Specifies uuid of the volume for which the operation will be executed 310 @param operation Specifies required operation: 311 kAuthorizationOverrideOperationSet - temporarily disable SC enforcement 312 kAuthorizationOverrideOperationReset - turn off temporary SC enforcement 313 kAuthorizationOverrideOperationQuery - query current status 314 @param result If operation was to query current status, true will be set if SC enforcement is temporarily disabled or false if not 315 */ 316 OSStatus AuthorizationHandlePreloginOverride(const char * _Nonnull const volumeUuid, const char operation, Boolean * _Nullable result); 317 318 #if defined(__cplusplus) 319 } 320 #endif 321 322 #endif /* !_SECURITY_AUTHORIZATIONPRIV_H_ */