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 };
  58
  59 /*!
  60     @function AuthorizationCreateWithAuditToken
  61     @abstract Create a AuthorizationRef for the process that sent the mach message
  62         represented by the audit token. Requires root.
  63     @param token The audit token of a mach message
  64     @param environment (input/optional) An AuthorizationItemSet containing environment state used when making the autorization decision.  See the AuthorizationEnvironment type for details.
  65     @param flags (input) options specified by the AuthorizationFlags enum.  set all unused bits to zero to allow for future expansion.
  66     @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.
  67
  68     @result errAuthorizationSuccess 0 authorization or all requested rights succeeded.
  69
  70     errAuthorizationDenied -60005 The authorization for one or more of the requested rights was denied.
  71 */
  72
  73 OSStatus AuthorizationCreateWithAuditToken(audit_token_t token,
  74     const AuthorizationEnvironment * _Nullable environment,
  75     AuthorizationFlags flags,
  76     AuthorizationRef _Nullable * _Nonnull authorization);
  77
  78 /*!
  79     @function AuthorizationExecuteWithPrivilegesExternalForm
  80     Run an executable tool with enhanced privileges after passing
  81     suitable authorization procedures.
  82
  83     @param extForm authorization in external form that is used to authorize
  84     access to the enhanced privileges. It is also passed to the tool for
  85     further access control.
  86     @param pathToTool Full pathname to the tool that should be executed
  87     with enhanced privileges.
  88     @param flags Option bits (reserved). Must be zero.
  89     @param arguments An argv-style vector of strings to be passed to the tool.
  90     @param communicationsPipe Assigned a UNIX stdio FILE pointer for
  91     a bidirectional pipe to communicate with the tool. The tool will have
  92     this pipe as its standard I/O channels (stdin/stdout). If NULL, do not
  93     establish a communications pipe.
  94
  95     @discussion This function has been deprecated and should no longer be used.
  96     Use a launchd-launched helper tool and/or the Service Mangement framework
  97     for this functionality.
  98 */
  99
 100 OSStatus AuthorizationExecuteWithPrivilegesExternalForm(const AuthorizationExternalForm * _Nonnull extForm,
 101     const char * _Nonnull pathToTool,
 102     AuthorizationFlags flags,
 103     char * _Nonnull const * _Nonnull arguments,
 104     FILE * _Nullable * _Nonnull communicationsPipe) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA);
 105
 106 /*!
 107  @function AuthorizationExecuteWithPrivileges
 108  Run an executable tool with enhanced privileges after passing
 109  suitable authorization procedures.
 110  @param authorization An authorization reference that is used to authorize
 111  access to the enhanced privileges. It is also passed to the tool for
 112  further access control.
 113  @param pathToTool Full pathname to the tool that should be executed
 114  with enhanced privileges.
 115  @param options Option bits (reserved). Must be zero.
 116  @param arguments An argv-style vector of strings to be passed to the tool.
 117  @param communicationsPipe Assigned a UNIX stdio FILE pointer for
 118  a bidirectional pipe to communicate with the tool. The tool will have
 119  this pipe as its standard I/O channels (stdin/stdout). If NULL, do not
 120  establish a communications pipe.
 121
 122  @discussion This function has been deprecated and should no longer be used.
 123  Use a launchd-launched helper tool and/or the Service Mangement framework
 124  for this functionality.
 125  */
 126 OSStatus AuthorizationExecuteWithPrivileges(AuthorizationRef _Nonnull authorization,
 127                                                                                                 const char * _Nonnull pathToTool,
 128                                                                                                 AuthorizationFlags options,
 129                                                                                                 char * __nonnull const * __nonnull arguments,
 130                                                                                                 FILE * __nullable * __nullable communicationsPipe) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA);
 131
 132 /*!
 133  @function AuthorizationPreauthorizeCredentials
 134  Tries to preauthorize provided credentials by authorizationhost PAM. No user interface will be shown.
 135  Credentials is set of the context items which will be passed to the authorizationhost.
 136  */
 137 OSStatus AuthorizationPreauthorizeCredentials(AuthorizationRef _Nonnull authorization,
 138                                                                                           const AuthorizationItemSet * __nonnull credentials) __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);
 139
 140 /*!
 141  @function AuthorizationCopyPrivilegedReference
 142  From within a tool launched via the AuthorizationExecuteWithPrivileges function
 143  ONLY, retrieve the AuthorizationRef originally passed to that function.
 144  While AuthorizationExecuteWithPrivileges already verified the authorization to
 145  launch your tool, the tool may want to avail itself of any additional pre-authorizations
 146  the caller may have obtained through that reference.
 147
 148  @discussion This function has been deprecated and should no longer be used.
 149  Use a launchd-launched helper tool and/or the Service Mangement framework
 150  for this functionality.
 151  */
 152 OSStatus AuthorizationCopyPrivilegedReference(AuthorizationRef __nullable * __nonnull authorization,
 153                                                                                                   AuthorizationFlags flags) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA);
 154
 155 /*
 156     @function AuthorizationDismiss
 157     @abstract Dismisses all Authorization dialogs associated to the calling process.
 158         Any active authorization requests will be canceled and return errAuthorizationDenied
 159 */
 160
 161 OSStatus AuthorizationDismiss(void);
 162
 163 /*!
 164         @function SessionSetDistinguishedUser
 165         This function allows the creator of a (new) security session to associate an arbitrary
 166         UNIX user identity (uid) with the session. This uid can be retrieved with
 167         SessionGetDistinguishedUser by anyone who knows the session's id, and may also
 168         be used by the system for identification (but not authentication) purposes.
 169
 170         This call can only be made by the process that created the session, and only
 171         once.
 172
 173         This is a private API, and is subject to change.
 174
 175         @param session (input) Session-id for which to set the uid. Can be one of the
 176         special constants defined in AuthSession.h.
 177         @param user (input) The uid to set.
 178  */
 179 OSStatus SessionSetDistinguishedUser(SecuritySessionId session, uid_t user);
 180
 181
 182 /*!
 183         @function SessionGetDistinguishedUser
 184         Retrieves the distinguished uid of a session as set by the session creator
 185         using the SessionSetDistinguishedUser call.
 186
 187         @param session (input) Session-id for which to set the uid. Can be one of the
 188         special constants defined in AuthSession.h.
 189         @param user (output) Will receive the uid. Unchanged on error.
 190  */
 191 OSStatus SessionGetDistinguishedUser(SecuritySessionId session, uid_t * _Nonnull user);
 192
 193 /*!
 194         @function SessionSetUserPreferences
 195         Set preferences from current application context for session (for use during agent interactions).
 196
 197         @param session (input) Session-id for which to set the user preferences. Can be one of the special constants defined in AuthSession.h.
 198  */
 199 OSStatus SessionSetUserPreferences(SecuritySessionId session);
 200
 201
 202 /*!
 203     @function AuthorizationEnableSmartCard
 204     Enable or disable system login using smartcard or get current status.
 205
 206     @param authRef (input) The authorization object on which this operation is performed.
 207     @param enable (input) desired smartcard login support state, TRUE to enable, FALSE to disable
 208  */
 209 OSStatus AuthorizationEnableSmartCard(AuthorizationRef _Nonnull authRef, Boolean enable);
 210
 211 #if defined(__cplusplus)
 212 }
 213 #endif
 214
 215 #endif /* !_SECURITY_AUTHORIZATIONPRIV_H_ */