SecurityServer/Authorization/AuthorizationPlugin.h

   1 /*
   2  * Copyright (c) 2001 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 /*
  20  *  AuthorizationPlugin.h
  21  *  AuthorizationPlugin -- APIs for implementing authorization plugins.
  22  */
  23
  24 #if !defined(__AuthorizationPlugin__)
  25 #define __AuthorizationPlugin__ 1
  26
  27 #include <Security/Authorization.h>
  28
  29 #if defined(__cplusplus)
  30 extern "C" {
  31 #endif
  32
  33
  34 /*!
  35         @header AuthorizationPlugin
  36         Version 0.3 05/09/2001
  37
  38         Foo bar @@@.
  39
  40 */
  41
  42
  43 /*!
  44         @typedef AuthorizationValue
  45         @@@
  46 */
  47 typedef struct AuthorizationValue
  48 {
  49     UInt32 length;
  50     void *data;
  51 } AuthorizationValue;
  52
  53 typedef struct AuthorizationValueVector
  54 {
  55         UInt32 count;
  56         AuthorizationValue *values;
  57 } AuthorizationValueVector;
  58
  59 typedef UInt32 AuthorizationContextFlags;
  60 enum
  61 {
  62     /* If set, it will be possible to obtain the value of this attribute usingAuthorizationCopyInfo(). */
  63     kAuthorizationContextFlagExtractable = (1 << 0),
  64
  65     /* If set, this value will not be remembered in a "credential".  @@@ Do we need this? */
  66     kAuthorizationContextFlagVolatile = (1 << 1)
  67 };
  68
  69
  70 /*!
  71         @typedef AuthorizationMechanismId
  72         @@@
  73 */
  74 typedef const AuthorizationString AuthorizationMechanismId;
  75
  76 /*!
  77         @typedef AuthorizationPluginRef
  78         An instance of a plugin (even though there will probably only be one).
  79 */
  80 typedef void *AuthorizationPluginRef;
  81
  82 /*!
  83         @typedef AuthorizationMechanismRef
  84         An instance of a mechanism in a plugin.
  85 */
  86 typedef void *AuthorizationMechanismRef;
  87
  88 /*!
  89         @typedef AuthorizationEngineRef
  90         The engines handle for an instance of a mechanism in a plugin (corresponds to a particular AuthorizationMechanismRef).
  91 */
  92 typedef struct __OpaqueAuthorizationEngine *AuthorizationEngineRef;
  93
  94
  95 /*!
  96         @typedef AuthorizationSessionId
  97         A unique value for an AuthorizationSession being evaluated, provided by the authorization engine.
  98     A session is represented by a top level call to an Authorization API.
  99     @@@ Should this be changed to tie a session to the lifetime of an AuthorizationRef?  -- Michael
 100 */
 101 typedef void *AuthorizationSessionId;
 102
 103 /*!
 104         @typedef AuthorizationResult
 105         Possible values that SetResult may use.
 106
 107     @param kAuthorizationResultAllow the operation succeeded and should be allowed as far as this mechanism is concerned.
 108     @param kAuthorizationResultDeny the operation succeeded and should be denied as far as this mechanism is concerned.
 109     @param kAuthorizationResultUndefined the operation failed for some reason and should not be retried for this session.
 110     @param kAuthorizationResultUserCanceled the user has requested that the evaluation be terminated.
 111 */
 112 typedef UInt32 AuthorizationResult;
 113 enum
 114 {
 115     kAuthorizationResultAllow,
 116     kAuthorizationResultDeny,
 117     kAuthorizationResultUndefined,
 118     kAuthorizationResultUserCanceled,
 119 };
 120
 121 enum {
 122     kAuthorizationPluginInterfaceVersion = 0,
 123 };
 124
 125 enum {
 126     kAuthorizationCallbacksVersion = 0,
 127 };
 128
 129
 130 /* Callback API of the AuthorizationEngine. */
 131 typedef struct AuthorizationCallbacks {
 132     /* Will be set to kAuthorizationCallbacksVersion. */
 133     UInt32 version;
 134
 135     /* Flow control */
 136
 137     /* Set a result after a call to AuthorizationSessionInvoke. */
 138     OSStatus (*SetResult)(AuthorizationEngineRef inEngine, AuthorizationResult inResult);
 139
 140     /* Request authorization engine to interrupt all mechamisms invoked after this mechamism has called SessionSetResult and then call AuthorizationSessionInvoke again. */
 141     OSStatus (*RequestInterrupt)(AuthorizationEngineRef inEngine);
 142
 143     OSStatus (*DidDeactivate)(AuthorizationEngineRef inEngine);
 144
 145
 146     /* Getters and setters */
 147     OSStatus (*GetContextValue)(AuthorizationEngineRef inEngine,
 148         AuthorizationString inKey,
 149         AuthorizationContextFlags *outContextFlags,
 150         const AuthorizationValue **outValue);
 151
 152     OSStatus (*SetContextValue)(AuthorizationEngineRef inEngine,
 153         AuthorizationString inKey,
 154         AuthorizationContextFlags inContextFlags,
 155         const AuthorizationValue *inValue);
 156
 157     OSStatus (*GetHintValue)(AuthorizationEngineRef inEngine,
 158         AuthorizationString inKey,
 159         const AuthorizationValue **outValue);
 160
 161     OSStatus (*SetHintValue)(AuthorizationEngineRef inEngine,
 162         AuthorizationString inKey,
 163         const AuthorizationValue *inValue);
 164
 165     OSStatus (*GetArguments)(AuthorizationEngineRef inEngine,
 166         const AuthorizationValueVector **outArguments);
 167
 168     OSStatus (*GetSessionId)(AuthorizationEngineRef inEngine,
 169         AuthorizationSessionId *outSessionId);
 170
 171
 172 } AuthorizationCallbacks;
 173
 174
 175 /* Functions that must be implemented by each plugin. */
 176
 177 typedef struct AuthorizationPluginInterface
 178 {
 179     /* Must be set to kAuthorizationPluginInterfaceVersion. */
 180     UInt32 version;
 181
 182     /* 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.  */
 183     OSStatus (*PluginDestroy)(AuthorizationPluginRef inPlugin);
 184
 185     /* The plugin should create an AuthorizationMechanismRef and remeber inEngine, mechanismId and callbacks for future reference.  It is guaranteed that MechanismDestroy will be called on the returned AuthorizationMechanismRef sometime after this function.  */
 186     OSStatus (*MechanismCreate)(AuthorizationPluginRef inPlugin,
 187         AuthorizationEngineRef inEngine,
 188         AuthorizationMechanismId mechanismId,
 189         AuthorizationMechanismRef *outMechanism);
 190
 191     /* Invoke (or evaluate) an instance of a mechanism (created with MechanismCreate).  It should call SetResult during or after returning from this function.  */
 192     OSStatus (*MechanismInvoke)(AuthorizationMechanismRef inMechanism);
 193
 194     /* Plugin should respond with a SessionDidDeactivate asap. */
 195     OSStatus (*MechanismDeactivate)(AuthorizationMechanismRef inMechanism);
 196
 197     OSStatus (*MechanismDestroy)(AuthorizationMechanismRef inMechanism);
 198
 199 } AuthorizationPluginInterface;
 200
 201
 202 /* @function AuthorizationPluginCreate
 203
 204     Initialize a plugin after it gets loaded.  This is the main entry point to a plugin.  This function will only be called once and after all Mechanism instances have been destroyed outPluginInterface->PluginDestroy will be called.
 205
 206     @param callbacks (input) A pointer to an AuthorizationCallbacks which contains the callbacks implemented by the AuthorizationEngine.
 207     @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.
 208     @param outPluginInterface (output) On successful completion should contain a pointer to a AuthorizationPluginInterface that will stay valid until outPluginInterface->PluginDestroy is called. */
 209 OSStatus AuthorizationPluginCreate(const AuthorizationCallbacks *callbacks,
 210     AuthorizationPluginRef *outPlugin,
 211     const AuthorizationPluginInterface **outPluginInterface);
 212
 213 #if defined(__cplusplus)
 214 }
 215 #endif
 216
 217 #endif /* ! __AuthorizationPlugin__ */