OSX/libsecurity_authorization/lib/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     @function AuthorizationCreateWithAuditToken
  65     @abstract Create a AuthorizationRef for the process that sent the mach message
  66         represented by the audit token. Requires root.
  67     @param token The audit token of a mach message
  68     @param environment (input/optional) An AuthorizationItemSet containing environment state used when making the autorization decision.  See the AuthorizationEnvironment type for details.
  69     @param flags (input) options specified by the AuthorizationFlags enum.  set all unused bits to zero to allow for future expansion.
  70     @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.
  71
  72     @result errAuthorizationSuccess 0 authorization or all requested rights succeeded.
  73
  74     errAuthorizationDenied -60005 The authorization for one or more of the requested rights was denied.
  75 */
  76
  77 OSStatus AuthorizationCreateWithAuditToken(audit_token_t token,
  78     const AuthorizationEnvironment * _Nullable environment,
  79     AuthorizationFlags flags,
  80     AuthorizationRef _Nullable * _Nonnull authorization);
  81
  82 /*!
  83     @function AuthorizationExecuteWithPrivilegesExternalForm
  84     Run an executable tool with enhanced privileges after passing
  85     suitable authorization procedures.
  86
  87     @param extForm authorization in external form that is used to authorize
  88     access to the enhanced privileges. It is also passed to the tool for
  89     further access control.
  90     @param pathToTool Full pathname to the tool that should be executed
  91     with enhanced privileges.
  92     @param flags Option bits (reserved). Must be zero.
  93     @param arguments An argv-style vector of strings to be passed to the tool.
  94     @param communicationsPipe Assigned a UNIX stdio FILE pointer for
  95     a bidirectional pipe to communicate with the tool. The tool will have
  96     this pipe as its standard I/O channels (stdin/stdout). If NULL, do not
  97     establish a communications pipe.
  98
  99     @discussion This function has been deprecated and should no longer be used.
 100     Use a launchd-launched helper tool and/or the Service Mangement framework
 101     for this functionality.
 102 */
 103
 104 OSStatus AuthorizationExecuteWithPrivilegesExternalForm(const AuthorizationExternalForm * _Nonnull extForm,
 105     const char * _Nonnull pathToTool,
 106     AuthorizationFlags flags,
 107     char * _Nonnull const * _Nonnull arguments,
 108     FILE * _Nullable * _Nonnull communicationsPipe) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA);
 109
 110 /*!
 111  @function AuthorizationExecuteWithPrivileges
 112  Run an executable tool with enhanced privileges after passing
 113  suitable authorization procedures.
 114  @param authorization An authorization reference that is used to authorize
 115  access to the enhanced privileges. It is also passed to the tool for
 116  further access control.
 117  @param pathToTool Full pathname to the tool that should be executed
 118  with enhanced privileges.
 119  @param options Option bits (reserved). Must be zero.
 120  @param arguments An argv-style vector of strings to be passed to the tool.
 121  @param communicationsPipe Assigned a UNIX stdio FILE pointer for
 122  a bidirectional pipe to communicate with the tool. The tool will have
 123  this pipe as its standard I/O channels (stdin/stdout). If NULL, do not
 124  establish a communications pipe.
 125
 126  @discussion This function has been deprecated and should no longer be used.
 127  Use a launchd-launched helper tool and/or the Service Mangement framework
 128  for this functionality.
 129  */
 130 OSStatus AuthorizationExecuteWithPrivileges(AuthorizationRef _Nonnull authorization,
 131                                                                                                 const char * _Nonnull pathToTool,
 132                                                                                                 AuthorizationFlags options,
 133                                                                                                 char * __nonnull const * __nonnull arguments,
 134                                                                                                 FILE * __nullable * __nullable communicationsPipe) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA);
 135
 136 /*!
 137  @function AuthorizationCopyRightProperties
 138  Returns a dictionary with the properties associated with the given authorization right
 139  @param rightName right name for which we need the propertiers
 140  @param output CFDictionaryRef which will hold the properties
 141
 142  */
 143 OSStatus AuthorizationCopyRightProperties(const char * __nonnull rightName, CFDictionaryRef __nullable * __nullable output) __OSX_AVAILABLE_STARTING(__MAC_10_15, __IPHONE_NA);
 144
 145 /*!
 146  @function AuthorizationCopyPrivilegedReference
 147  From within a tool launched via the AuthorizationExecuteWithPrivileges function
 148  ONLY, retrieve the AuthorizationRef originally passed to that function.
 149  While AuthorizationExecuteWithPrivileges already verified the authorization to
 150  launch your tool, the tool may want to avail itself of any additional pre-authorizations
 151  the caller may have obtained through that reference.
 152
 153  @discussion This function has been deprecated and should no longer be used.
 154  Use a launchd-launched helper tool and/or the Service Mangement framework
 155  for this functionality.
 156  */
 157 OSStatus AuthorizationCopyPrivilegedReference(AuthorizationRef __nullable * __nonnull authorization,
 158                                                                                                   AuthorizationFlags flags) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA);
 159
 160 /*
 161     @function AuthorizationDismiss
 162     @abstract Dismisses all Authorization dialogs associated to the calling process.
 163         Any active authorization requests will be canceled and return errAuthorizationDenied
 164 */
 165
 166 OSStatus AuthorizationDismiss(void);
 167
 168 /*!
 169         @function SessionSetDistinguishedUser
 170         This function allows the creator of a (new) security session to associate an arbitrary
 171         UNIX user identity (uid) with the session. This uid can be retrieved with
 172         SessionGetDistinguishedUser by anyone who knows the session's id, and may also
 173         be used by the system for identification (but not authentication) purposes.
 174
 175         This call can only be made by the process that created the session, and only
 176         once.
 177
 178         This is a private API, and is subject to change.
 179
 180         @param session (input) Session-id for which to set the uid. Can be one of the
 181         special constants defined in AuthSession.h.
 182         @param user (input) The uid to set.
 183  */
 184 OSStatus SessionSetDistinguishedUser(SecuritySessionId session, uid_t user);
 185
 186
 187 /*!
 188         @function SessionGetDistinguishedUser
 189         Retrieves the distinguished uid of a session as set by the session creator
 190         using the SessionSetDistinguishedUser call.
 191
 192         @param session (input) Session-id for which to set the uid. Can be one of the
 193         special constants defined in AuthSession.h.
 194         @param user (output) Will receive the uid. Unchanged on error.
 195  */
 196 OSStatus SessionGetDistinguishedUser(SecuritySessionId session, uid_t * _Nonnull user);
 197
 198 /*!
 199         @function SessionSetUserPreferences
 200         Set preferences from current application context for session (for use during agent interactions).
 201
 202         @param session (input) Session-id for which to set the user preferences. Can be one of the special constants defined in AuthSession.h.
 203  */
 204 OSStatus SessionSetUserPreferences(SecuritySessionId session);
 205
 206
 207 /*!
 208     @function AuthorizationEnableSmartCard
 209     Enable or disable system login using smartcard or get current status.
 210
 211     @param authRef (input) The authorization object on which this operation is performed.
 212     @param enable (input) desired smartcard login support state, TRUE to enable, FALSE to disable
 213  */
 214 OSStatus AuthorizationEnableSmartCard(AuthorizationRef _Nonnull authRef, Boolean enable);
 215
 216 /*!
 217      @function AuthorizationExecuteWithPrivilegesInternal
 218      Run an executable tool with enhanced privileges after passing
 219      suitable authorization procedures. Allows better control and communication
 220      with privileged tool.
 221
 222      @param authorization An authorization reference that is used to authorize
 223      access to the enhanced privileges. It is also passed to the tool for
 224      further access control.
 225      @param pathToTool Full pathname to the tool that should be executed
 226      with enhanced privileges.
 227      @param arguments An argv-style vector of strings to be passed to the tool.
 228      @param newProcessPid (output, optional) PID of privileged process is stored here.
 229      @param uid Desired UID under which privileged tool should be running.
 230      @param stdOut File descriptor of the pipe which should be used to receive stdout from the privileged tool, use -1 if not needed.
 231      @param stdErr File descriptor of the pipe which should be used to receive stderr from the privileged tool, use -1 if not needed.
 232      @param stdIn File descriptor which will contain write-end of the stdin pipe of the privileged tool, use -1 if not needed.
 233      @param processFinished This block is called when privileged process finishes.
 234      */
 235 OSStatus AuthorizationExecuteWithPrivilegesInternal(const AuthorizationRef _Nonnull authorization,
 236                                                         const char * _Nonnull pathToTool,
 237                                                         const char * _Nonnull const * _Nonnull arguments,
 238                                                         pid_t * _Nullable newProcessPid,
 239                                                         const uid_t uid,
 240                                                         int stdOut,
 241                                                         int stdErr,
 242                                                         int stdIn,
 243                                                         void(^__nullable processFinished)(const int exitStatus));
 244
 245 /*!
 246      @function AuthorizationExecuteWithPrivilegesExternalFormInternal
 247      Run an executable tool with enhanced privileges after passing
 248      suitable authorization procedures. Allows better control and communication
 249      with privileged tool.
 250
 251      @param extAuthorization authorization in external form that is used to authorize
 252      access to the enhanced privileges. It is also passed to the tool for
 253      further access control.
 254      @param pathToTool Full pathname to the tool that should be executed
 255      with enhanced privileges.
 256      @param arguments An argv-style vector of strings to be passed to the tool.
 257      @param newProcessPid (output, optional) PID of privileged process is stored here.
 258      @param uid Desired UID under which privileged tool should be running.
 259      @param stdOut File descriptor of the pipe which should be used to receive stdout from the privileged tool, use -1 if not needed.
 260      @param stdErr File descriptor of the pipe which should be used to receive stderr from the privileged tool, use -1 if not needed.
 261      @param stdIn File descriptor which will contain write-end of the stdin pipe of the privileged tool, use -1 if not needed.
 262      @param processFinished This block is called when privileged process finishes.
 263      */
 264 OSStatus AuthorizationExecuteWithPrivilegesExternalFormInternal(const AuthorizationExternalForm * _Nonnull extAuthorization,
 265                                                                     const char * _Nonnull pathToTool,
 266                                                                     const char * _Nullable const * _Nullable arguments,
 267                                                                     pid_t * _Nullable newProcessPid,
 268                                                                     const uid_t uid,
 269                                                                     int stdOut,
 270                                                                     int stdErr,
 271                                                                     int stdIn,
 272                                                                     void(^__nullable processFinished)(const int exitStatus));
 273
 274 /*!
 275     @function AuthorizationCopyPreloginUserDatabase
 276     Returns CFArrayRef with user database from Prelogin volume
 277
 278     @param volumeUuid Optional uuid of the volume for which user database will be returned. If not set, users from all volumes are returned.
 279     @param flags Specifies subset of data required in the output
 280     @param output Output array of dictionaries- each dictionary with details for each user
 281 */
 282 OSStatus AuthorizationCopyPreloginUserDatabase(const char * _Nullable const volumeUuid, const UInt32 flags, CFArrayRef _Nonnull * _Nonnull output);
 283
 284 #if defined(__cplusplus)
 285 }
 286 #endif
 287
 288 #endif /* !_SECURITY_AUTHORIZATIONPRIV_H_ */