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) 40extern "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*/ 55enum { 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 enviroment 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 aquired 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 73OSStatus AuthorizationCreateWithAuditToken(audit_token_t token, 74 const AuthorizationEnvironment *environment, 75 AuthorizationFlags flags, 76 AuthorizationRef *authorization); 77 78/*! 79 @function AuthorizationExecuteWithPrivilegesExternalForm 80 Run an executable tool with enhanced privileges after passing 81 suitable authorization procedures. 82 83 @param 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 options 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 100OSStatus AuthorizationExecuteWithPrivilegesExternalForm(const AuthorizationExternalForm * extForm, 101 const char *pathToTool, 102 AuthorizationFlags flags, 103 char *const *arguments, 104 FILE **communicationsPipe) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA); 105 106/* 107 @function AuthorizationDismiss 108 @abstract Dismisses all Authorization dialogs associated to the calling process. 109 Any active authorization requests will be canceled and return errAuthorizationDenied 110*/ 111 112OSStatus AuthorizationDismiss(void); 113 114/*! 115 @function SessionSetDistinguishedUser 116 This function allows the creator of a (new) security session to associate an arbitrary 117 UNIX user identity (uid) with the session. This uid can be retrieved with 118 SessionGetDistinguishedUser by anyone who knows the session's id, and may also 119 be used by the system for identification (but not authentication) purposes. 120 121 This call can only be made by the process that created the session, and only 122 once. 123 124 This is a private API, and is subject to change. 125 126 @param session (input) Session-id for which to set the uid. Can be one of the 127 special constants defined in AuthSession.h. 128 @param user (input) The uid to set. 129 */ 130OSStatus SessionSetDistinguishedUser(SecuritySessionId session, uid_t user); 131 132 133/*! 134 @function SessionGetDistinguishedUser 135 Retrieves the distinguished uid of a session as set by the session creator 136 using the SessionSetDistinguishedUser call. 137 138 @param session (input) Session-id for which to set the uid. Can be one of the 139 special constants defined in AuthSession.h. 140 @param user (output) Will receive the uid. Unchanged on error. 141 */ 142OSStatus SessionGetDistinguishedUser(SecuritySessionId session, uid_t *user); 143 144/*! 145 @function SessionSetUserPreferences 146 Set preferences from current application context for session (for use during agent interactions). 147 148 @param session (input) Session-id for which to set the user preferences. Can be one of the special constants defined in AuthSession.h. 149 */ 150OSStatus SessionSetUserPreferences(SecuritySessionId session); 151 152 153/*! 154 @function AuthorizationEnableSmartCard 155 Enable or disable system login using smartcard or get current status. 156 157 @param authorization (input) The authorization object on which this operation is performed. 158 @param enable (input) desired smartcard login support state, TRUE to enable, FALSE to disable 159 */ 160OSStatus AuthorizationEnableSmartCard(AuthorizationRef authRef, Boolean enable); 161 162#if defined(__cplusplus) 163} 164#endif 165 166#endif /* !_SECURITY_AUTHORIZATIONPRIV_H_ */ 167