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 AuthorizationPluginId
  78         @@@ Not used by plugin writers
  79  */
  80 typedef const AuthorizationString AuthorizationPluginId;
  81
  82
  83
  84 /*!
  85         @typedef AuthorizationPluginRef
  86         An instance of a plugin (even though there will probably only be one).
  87 */
  88 typedef void *AuthorizationPluginRef;
  89
  90 /*!
  91         @typedef AuthorizationMechanismRef
  92         An instance of a mechanism in a plugin.
  93 */
  94 typedef void *AuthorizationMechanismRef;
  95
  96 /*!
  97         @typedef AuthorizationEngineRef
  98         The engines handle for an instance of a mechanism in a plugin (corresponds to a particular AuthorizationMechanismRef).
  99 */
 100 typedef struct __OpaqueAuthorizationEngine *AuthorizationEngineRef;
 101
 102
 103 /*!
 104         @typedef AuthorizationSessionId
 105         A unique value for an AuthorizationSession being evaluated, provided by the authorization engine.
 106     A session is represented by a top level call to an Authorization API.
 107     @@@ Should this be changed to tie a session to the lifetime of an AuthorizationRef?  -- Michael
 108 */
 109 typedef void *AuthorizationSessionId;
 110
 111 /*!
 112         @typedef AuthorizationResult
 113         Possible values that SetResult may use.
 114
 115     @param kAuthorizationResultAllow the operation succeeded and should be allowed as far as this mechanism is concerned.
 116     @param kAuthorizationResultDeny the operation succeeded and should be denied as far as this mechanism is concerned.
 117     @param kAuthorizationResultUndefined the operation failed for some reason and should not be retried for this session.
 118     @param kAuthorizationResultUserCanceled the user has requested that the evaluation be terminated.
 119 */
 120 typedef UInt32 AuthorizationResult;
 121 enum
 122 {
 123     kAuthorizationResultAllow,
 124     kAuthorizationResultDeny,
 125     kAuthorizationResultUndefined,
 126     kAuthorizationResultUserCanceled,
 127 };
 128
 129 enum {
 130     kAuthorizationPluginInterfaceVersion = 0
 131 };
 132
 133 enum {
 134     kAuthorizationCallbacksVersion = 0
 135 };
 136
 137
 138 /* Callback API of the AuthorizationEngine. */
 139 typedef struct AuthorizationCallbacks {
 140     /* Will be set to kAuthorizationCallbacksVersion. */
 141     UInt32 version;
 142
 143     /* Flow control */
 144
 145     /* Set a result after a call to AuthorizationSessionInvoke. */
 146     OSStatus (*SetResult)(AuthorizationEngineRef inEngine, AuthorizationResult inResult);
 147
 148     /* Request authorization engine to interrupt all mechamisms invoked after this mechamism has called SessionSetResult and then call AuthorizationSessionInvoke again. */
 149     OSStatus (*RequestInterrupt)(AuthorizationEngineRef inEngine);
 150
 151     OSStatus (*DidDeactivate)(AuthorizationEngineRef inEngine);
 152
 153
 154     /* Getters and setters */
 155     OSStatus (*GetContextValue)(AuthorizationEngineRef inEngine,
 156         AuthorizationString inKey,
 157         AuthorizationContextFlags *outContextFlags,
 158         const AuthorizationValue **outValue);
 159
 160     OSStatus (*SetContextValue)(AuthorizationEngineRef inEngine,
 161         AuthorizationString inKey,
 162         AuthorizationContextFlags inContextFlags,
 163         const AuthorizationValue *inValue);
 164
 165     OSStatus (*GetHintValue)(AuthorizationEngineRef inEngine,
 166         AuthorizationString inKey,
 167         const AuthorizationValue **outValue);
 168
 169     OSStatus (*SetHintValue)(AuthorizationEngineRef inEngine,
 170         AuthorizationString inKey,
 171         const AuthorizationValue *inValue);
 172
 173     OSStatus (*GetArguments)(AuthorizationEngineRef inEngine,
 174         const AuthorizationValueVector **outArguments);
 175
 176     OSStatus (*GetSessionId)(AuthorizationEngineRef inEngine,
 177         AuthorizationSessionId *outSessionId);
 178
 179
 180 } AuthorizationCallbacks;
 181
 182
 183 /* Functions that must be implemented by each plugin. */
 184
 185 typedef struct AuthorizationPluginInterface
 186 {
 187     /* Must be set to kAuthorizationPluginInterfaceVersion. */
 188     UInt32 version;
 189
 190     /* 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.  */
 191     OSStatus (*PluginDestroy)(AuthorizationPluginRef inPlugin);
 192
 193     /* 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.  */
 194     OSStatus (*MechanismCreate)(AuthorizationPluginRef inPlugin,
 195         AuthorizationEngineRef inEngine,
 196         AuthorizationMechanismId mechanismId,
 197         AuthorizationMechanismRef *outMechanism);
 198
 199     /* Invoke (or evaluate) an instance of a mechanism (created with MechanismCreate).  It should call SetResult during or after returning from this function.  */
 200     OSStatus (*MechanismInvoke)(AuthorizationMechanismRef inMechanism);
 201
 202     /* Plugin should respond with a SessionDidDeactivate asap. */
 203     OSStatus (*MechanismDeactivate)(AuthorizationMechanismRef inMechanism);
 204
 205     OSStatus (*MechanismDestroy)(AuthorizationMechanismRef inMechanism);
 206
 207 } AuthorizationPluginInterface;
 208
 209
 210 /* @function AuthorizationPluginCreate
 211
 212     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.
 213
 214     @param callbacks (input) A pointer to an AuthorizationCallbacks which contains the callbacks implemented by the AuthorizationEngine.
 215     @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.
 216     @param outPluginInterface (output) On successful completion should contain a pointer to a AuthorizationPluginInterface that will stay valid until outPluginInterface->PluginDestroy is called. */
 217 OSStatus AuthorizationPluginCreate(const AuthorizationCallbacks *callbacks,
 218     AuthorizationPluginRef *outPlugin,
 219     const AuthorizationPluginInterface **outPluginInterface);
 220
 221 #if defined(__cplusplus)
 222 }
 223 #endif
 224
 225 #endif /* ! __AuthorizationPlugin__ */