[apple/security.git] / libsecurity_authorization / lib / AuthorizationPriv.h

/*
 * Copyright (c) 2002-2004 Apple Computer, Inc. All Rights Reserved.
 * 
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */


/*
 *  AuthorizationPriv.h -- Authorization SPIs
 *  Private APIs for implementing access control in applications and daemons.
 *  
 */

#ifndef _SECURITY_AUTHORIZATIONPRIV_H_
#define _SECURITY_AUTHORIZATIONPRIV_H_

#include <Security/Authorization.h>
#include <Security/AuthSession.h>
#include <sys/types.h>	// uid_t
#include <mach/message.h>

#if defined(__cplusplus)
extern "C" {
#endif


/*!
	@header AuthorizationPriv
	Version 1.1 04/2003

	This header contains private APIs for authorization services.
	This is the private extension of <Security/Authorization.h>, a public header file.
*/

/*!
	@enum Private (for now) AuthorizationFlags
*/
enum {
	kAuthorizationFlagLeastPrivileged		= (1 << 5)
};

/*!
    @function AuthorizationCreateWithAuditToken
    @abstract Create a AuthorizationRef for the process that sent the mach message
        represented by the audit token. Requires root.
    @param token The audit token of a mach message
    @param environment (input/optional) An AuthorizationItemSet containing enviroment state used when making the autorization decision.  See the AuthorizationEnvironment type for details.
    @param flags (input) options specified by the AuthorizationFlags enum.  set all unused bits to zero to allow for future expansion.
    @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.
 
    @result errAuthorizationSuccess 0 authorization or all requested rights succeeded.
 
    errAuthorizationDenied -60005 The authorization for one or more of the requested rights was denied.
*/

OSStatus AuthorizationCreateWithAuditToken(audit_token_t token,
    const AuthorizationEnvironment *environment,
    AuthorizationFlags flags,
    AuthorizationRef *authorization);

/*!
    @function AuthorizationExecuteWithPrivilegesExternalForm
    Run an executable tool with enhanced privileges after passing
    suitable authorization procedures.

    @param authorization in external form that is used to authorize
    access to the enhanced privileges. It is also passed to the tool for
    further access control.
    @param pathToTool Full pathname to the tool that should be executed
    with enhanced privileges.
    @param options Option bits (reserved). Must be zero.
    @param arguments An argv-style vector of strings to be passed to the tool.
    @param communicationsPipe Assigned a UNIX stdio FILE pointer for
    a bidirectional pipe to communicate with the tool. The tool will have
    this pipe as its standard I/O channels (stdin/stdout). If NULL, do not
    establish a communications pipe.

    @discussion This function has been deprecated and should no longer be used.
    Use a launchd-launched helper tool and/or the Service Mangement framework
    for this functionality.
*/
    
OSStatus AuthorizationExecuteWithPrivilegesExternalForm(const AuthorizationExternalForm * extForm,
    const char *pathToTool,
    AuthorizationFlags flags,
    char *const *arguments,
    FILE **communicationsPipe) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_7,__IPHONE_NA,__IPHONE_NA);

/*
    @function AuthorizationDismiss
    @abstract Dismisses all Authorization dialogs associated to the calling process.
        Any active authorization requests will be canceled and return errAuthorizationDenied
*/

OSStatus AuthorizationDismiss(void);
    
/*!
	@function SessionSetDistinguishedUser
	This function allows the creator of a (new) security session to associate an arbitrary
	UNIX user identity (uid) with the session. This uid can be retrieved with
	SessionGetDistinguishedUser by anyone who knows the session's id, and may also
	be used by the system for identification (but not authentication) purposes.
	
	This call can only be made by the process that created the session, and only
	once.
	
	This is a private API, and is subject to change.
	
	@param session (input) Session-id for which to set the uid. Can be one of the
        special constants defined in AuthSession.h.
	@param user (input) The uid to set.
 */
OSStatus SessionSetDistinguishedUser(SecuritySessionId session, uid_t user);


/*!
	@function SessionGetDistinguishedUser
	Retrieves the distinguished uid of a session as set by the session creator
	using the SessionSetDistinguishedUser call.
	
	@param session (input) Session-id for which to set the uid. Can be one of the
        special constants defined in AuthSession.h.
	@param user (output) Will receive the uid. Unchanged on error.
 */
OSStatus SessionGetDistinguishedUser(SecuritySessionId session, uid_t *user);

/*!
	@function SessionSetUserPreferences
	Set preferences from current application context for session (for use during agent interactions).
	
	@param session (input) Session-id for which to set the user preferences. Can be one of the special constants defined in AuthSession.h.
 */
OSStatus SessionSetUserPreferences(SecuritySessionId session);

    
/*!
    @function AuthorizationEnableSmartCard
    Enable or disable system login using smartcard or get current status.
 
    @param authorization (input) The authorization object on which this operation is performed.
    @param enable (input) desired smartcard login support state, TRUE to enable, FALSE to disable
 */
OSStatus AuthorizationEnableSmartCard(AuthorizationRef authRef, Boolean enable);

#if defined(__cplusplus)
}
#endif

#endif /* !_SECURITY_AUTHORIZATIONPRIV_H_ */
Commit	Line	Data
b1ab9ed8 A	1	/*
	2	* Copyright (c) 2002-2004 Apple Computer, 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
427c49bc	37	#include <mach/message.h>
b1ab9ed8 A	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
427c49bc A	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
	73	OSStatus 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
	100	OSStatus 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
	112	OSStatus AuthorizationDismiss(void);
	113
b1ab9ed8 A	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	*/
	130	OSStatus 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	*/
	142	OSStatus 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	*/
	150	OSStatus SessionSetUserPreferences(SecuritySessionId session);
	151
427c49bc A	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	*/
	160	OSStatus AuthorizationEnableSmartCard(AuthorizationRef authRef, Boolean enable);
b1ab9ed8 A	161
	162	#if defined(__cplusplus)
	163	}
	164	#endif
	165
	166	#endif /* !_SECURITY_AUTHORIZATIONPRIV_H_ */