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