+++ /dev/null
-/*
- * Copyright (c) 2001-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@
- */
-
-
-/*
- * AuthorizationPlugin.h
- * AuthorizationPlugin -- APIs for implementing authorization plugins.
- */
-
-#ifndef _SECURITY_AUTHORIZATIONPLUGIN_H_
-#define _SECURITY_AUTHORIZATIONPLUGIN_H_
-
-#include <Security/Authorization.h>
-
-#if defined(__cplusplus)
-extern "C" {
-#endif
-
-
-/*!
- @header AuthorizationPlugin
-
- The AuthorizationPlugin API allows the creation of plugins that can participate
- in authorization decisions. Using the AuthorizationDB API the system can be configured
- to use these plugins. Plugins are loaded into a separate process, the pluginhost, to
- isolate the process of authorization from the client. There are two types of pluginhosts.
- One runs as an anonymous user and can be used to communicate with the user, for example
- to ask for a password. Another one runs with root privileges to perform privileged
- operations that may be required.
-
- A typical use is to implement additional policies that cannot be expressed in the
- authorization configuration.
-
- Plugins implement a handshake function called AuthorizationPluginCreate with which
- their interface (AuthorizationPluginInterface) and the engine's interface
- (AuthorizationCallbacks) are exchanged. Plugins are asked to create
- Mechanisms, which are the basic element as authorizations are performed.
-
- Mechanisms are invoked when it is time for them to make a decision. A decision is
- made by setting a single result (AuthorizationResult). Mechanisms in the
- authorization can communicate auxiliary information by setting and/or getting hints
- and setting and/or getting context data. Hints are advisory and don't need to be
- looked at, nor are they preserved as part of the authorization result. Context data
- becomes part of the result of the authorization.
-
- Context data is tagged with a flag that describes whether the information is returned
- to the authorization client upon request (AuthorizationCopyInfo() in Authorization.h)
- or whether it's private to the mechanisms making a decision.
-
-*/
-
-
-/*!
- @typedef AuthorizationValue
- Auxiliary data is passed between the engine and the mechanism as AuthorizationValues
-*/
-typedef struct AuthorizationValue
-{
- size_t length;
- void *data;
-} AuthorizationValue;
-
-/*!
- @typedef AuthorizationValueVector
- A vector of AuthorizationValues. Used to communicate arguments passed from the
- configuration file <code>authorization(5)</code>.
-*/
-typedef struct AuthorizationValueVector
-{
- UInt32 count;
- AuthorizationValue *values;
-} AuthorizationValueVector;
-
-/*!
- @typedef
- Data produced as context during the authorization evaluation is tagged.
- If data is set to be extractable (kAuthorizationContextFlagExtractable), it will be possible for the client of authorization to obtain the value of this attribute using AuthorizationCopyInfo().
- If data is marked as volatile (kAuthorizationContextFlagVolatile), this value will not be remembered in the AuthorizationRef.
- Sticky data (kAuthorizationContextFlagSticky) persists through a failed or interrupted evaluation. It can be used to propagate an error condition from a downstream plugin to an upstream one. It is not remembered in the AuthorizationRef.
-*/
-typedef UInt32 AuthorizationContextFlags;
-enum
-{
- kAuthorizationContextFlagExtractable = (1 << 0),
- kAuthorizationContextFlagVolatile = (1 << 1),
- kAuthorizationContextFlagSticky = (1 << 2)
-};
-
-
-/*!
- @typedef AuthorizationMechanismId
- The mechanism id specified in the configuration is passed to the plugin to create the appropriate mechanism.
-*/
-typedef const AuthorizationString AuthorizationMechanismId;
-
-/*!
- @typedef AuthorizationPluginId
- Not used by plugin writers. Loaded plugins are identified by their name.
- */
-typedef const AuthorizationString AuthorizationPluginId;
-
-/*!
- @typedef AuthorizationPluginRef
- Handle passed back by the plugin writer when creating a plugin. Any pluginhost will only instantiate one instance. The handle is used when creating mechanisms.
-*/
-typedef void *AuthorizationPluginRef;
-
-/*!
- @typedef AuthorizationMechanismRef
- Handle passed back by the plugin writer when creating an an instance of a mechanism in a plugin. One instance will be created for any authorization.
-*/
-typedef void *AuthorizationMechanismRef;
-
-/*!
- @typedef AuthorizationEngineRef
- Handle passed from the engine to an instance of a mechanism in a plugin (corresponds to a particular AuthorizationMechanismRef).
-*/
-typedef struct __OpaqueAuthorizationEngine *AuthorizationEngineRef;
-
-/*!
- @typedef AuthorizationSessionId
- A unique value for an AuthorizationSession being evaluated, provided by the authorization engine.
- A session is represented by a top level call to an Authorization API.
-*/
-typedef void *AuthorizationSessionId;
-
-/*!
- @typedef AuthorizationResult
- Type for SetResult(). See AuthorizationResultConstants for all allowed values.
-*/
-typedef UInt32 AuthorizationResult;
-
-/*!
- @enum AuthorizationResultConstants
- Possible values for SetResult() in AuthorizationCallbacks.
-
- @constant kAuthorizationResultAllow the operation succeeded and authorization should be granted as far as this mechanism is concerned.
- @constant kAuthorizationResultDeny the operation succeeded but authorization should be denied as far as this mechanism is concerned.
- @constant kAuthorizationResultUndefined the operation failed for some reason and should not be retried for this session.
- @constant kAuthorizationResultUserCanceled the user has requested that the evaluation be terminated.
-*/
-enum {
- kAuthorizationResultAllow,
- kAuthorizationResultDeny,
- kAuthorizationResultUndefined,
- kAuthorizationResultUserCanceled,
-};
-
-/*!
- @enum
- Version of the interface (AuthorizationPluginInterface) implemented by the plugin.
- The value is matched to the definition in this file.
-*/
-enum {
- kAuthorizationPluginInterfaceVersion = 0
-};
-
-/*!
- @enum
- Version of the callback structure (AuthorizationCallbacks) passed to the plugin.
- The value is matched to the definition in this file. The engine may provide a newer
- interface.
-*/
-enum {
- kAuthorizationCallbacksVersion = 1
-};
-
-
-/*!
- @struct
- Callback API provided by the AuthorizationEngine.
-
- @field version Engine callback version.
- @field SetResult Set a result after a call to AuthorizationSessionInvoke.
- @field RequestInterrupt Request authorization engine to interrupt all mechamisms invoked after this mechamism has called SessionSetResult and then call AuthorizationSessionInvoke again.
- @field DidDeactivate Respond to the Deactivate request.
- @field GetContextValue Read value from context. AuthorizationValue does not own data.
- @field SetContextValue Write value to context. AuthorizationValue and data are copied.
- @field GetHintValue Read value from hints. AuthorizationValue does not own data.
- @field SetHintValue Write value to hints. AuthorizationValue and data are copied.
- @field GetArguments Read arguments passed. AuthorizationValueVector does not own data.
- @field GetSessionId Read SessionId.
-*/
-typedef struct AuthorizationCallbacks {
-
- /* Engine callback version. */
- UInt32 version;
-
- /* Set a result after a call to AuthorizationSessionInvoke. */
- OSStatus (*SetResult)(AuthorizationEngineRef inEngine, AuthorizationResult inResult);
-
- /* Request authorization engine to interrupt all mechamisms invoked after
- this mechamism has called SessionSetResult and then call
- AuthorizationSessionInvoke again. */
- OSStatus (*RequestInterrupt)(AuthorizationEngineRef inEngine);
-
- /* Respond to the Deactivate request. */
- OSStatus (*DidDeactivate)(AuthorizationEngineRef inEngine);
-
- /* Read value from context. AuthorizationValue does not own data. */
- OSStatus (*GetContextValue)(AuthorizationEngineRef inEngine,
- AuthorizationString inKey,
- AuthorizationContextFlags *outContextFlags,
- const AuthorizationValue **outValue);
-
- /* Write value to context. AuthorizationValue and data are copied. */
- OSStatus (*SetContextValue)(AuthorizationEngineRef inEngine,
- AuthorizationString inKey,
- AuthorizationContextFlags inContextFlags,
- const AuthorizationValue *inValue);
-
- /* Read value from hints. AuthorizationValue does not own data. */
- OSStatus (*GetHintValue)(AuthorizationEngineRef inEngine,
- AuthorizationString inKey,
- const AuthorizationValue **outValue);
-
- /* Write value to hints. AuthorizationValue and data are copied. */
- OSStatus (*SetHintValue)(AuthorizationEngineRef inEngine,
- AuthorizationString inKey,
- const AuthorizationValue *inValue);
-
- /* Read arguments passed. AuthorizationValueVector does not own data. */
- OSStatus (*GetArguments)(AuthorizationEngineRef inEngine,
- const AuthorizationValueVector **outArguments);
-
- /* Read SessionId. */
- OSStatus (*GetSessionId)(AuthorizationEngineRef inEngine,
- AuthorizationSessionId *outSessionId);
-
- /* Read value from hints. AuthorizationValue does not own data. */
- OSStatus (*GetImmutableHintValue)(AuthorizationEngineRef inEngine,
- AuthorizationString inKey,
- const AuthorizationValue **outValue);
-
-} AuthorizationCallbacks;
-
-
-/*!
- @struct
- Interface that must be implemented by each plugin.
-
- @field version Must be set to kAuthorizationPluginInterfaceVersion
- @field PluginDestroy Plugin should clean up and release any resources it is holding.
- @field MechanismCreate The plugin should create a mechanism named mechanismId. The mechanism needs to use the AuthorizationEngineRef for the callbacks and pass back a AuthorizationMechanismRef for itself. MechanismDestroy will be called when it is no longer needed.
- @field MechanismInvoke Invoke an instance of a mechanism. It should call SetResult during or after returning from this function.
- @field MechanismDeactivate Mechanism should respond with a DidDeactivate as soon as possible
- @field MechanismDestroy Mechanism should clean up and release any resources it is holding
-*/
-typedef struct AuthorizationPluginInterface
-{
- /* Must be set to kAuthorizationPluginInterfaceVersion. */
- UInt32 version;
-
- /* Notify a plugin that it is about to be unloaded so it get a chance to clean up and release any resources it is holding. */
- OSStatus (*PluginDestroy)(AuthorizationPluginRef inPlugin);
-
- /* The plugin should create a mechanism named mechanismId. The mechanism needs to use the
- AuthorizationEngineRef for the callbacks and pass back an AuthorizationMechanismRef for
- itself. MechanismDestroy will be called when it is no longer needed. */
- OSStatus (*MechanismCreate)(AuthorizationPluginRef inPlugin,
- AuthorizationEngineRef inEngine,
- AuthorizationMechanismId mechanismId,
- AuthorizationMechanismRef *outMechanism);
-
- /* Invoke an instance of a mechanism. It should call SetResult during or after returning from this function. */
- OSStatus (*MechanismInvoke)(AuthorizationMechanismRef inMechanism);
-
- /* Mechanism should respond with a DidDeactivate as soon as possible. */
- OSStatus (*MechanismDeactivate)(AuthorizationMechanismRef inMechanism);
-
- /* Mechanism should clean up and release any resources it is holding. */
- OSStatus (*MechanismDestroy)(AuthorizationMechanismRef inMechanism);
-
-} AuthorizationPluginInterface;
-
-
-/*!
- @function AuthorizationPluginCreate
-
- Initialize a plugin after it gets loaded. This is the main entry point to a plugin. This function will only be called once.
- After all Mechanism instances have been destroyed outPluginInterface->PluginDestroy will be called.
-
- @param callbacks (input) A pointer to an AuthorizationCallbacks which contains the callbacks implemented by the AuthorizationEngine.
- @param outPlugin (output) On successful completion should contain a valid AuthorizationPluginRef. This will be passed in to any subsequent calls the engine makes to outPluginInterface->MechanismCreate and outPluginInterface->PluginDestroy.
- @param outPluginInterface (output) On successful completion should contain a pointer to a AuthorizationPluginInterface that will stay valid until outPluginInterface->PluginDestroy is called. */
-OSStatus AuthorizationPluginCreate(const AuthorizationCallbacks *callbacks,
- AuthorizationPluginRef *outPlugin,
- const AuthorizationPluginInterface **outPluginInterface);
-
-#if defined(__cplusplus)
-}
-#endif
-
-#endif /* _SECURITY_AUTHORIZATIONPLUGIN_H_ */
projects / apple / security.git / blobdiff