AuthorizationPlugin.h
1 /* 2 * Copyright (c) 2001-2002,2004,2011-2012,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 * AuthorizationPlugin.h 27 * AuthorizationPlugin -- APIs for implementing authorization plugins. 28 */ 29 30 #ifndef _SECURITY_AUTHORIZATIONPLUGIN_H_ 31 #define _SECURITY_AUTHORIZATIONPLUGIN_H_ 32 33 #include <Security/Authorization.h> 34 35 #if defined(__cplusplus) 36 extern "C" { 37 #endif 38 39 CF_ASSUME_NONNULL_BEGIN 40 41 /*! 42 @header AuthorizationPlugin 43 44 The AuthorizationPlugin API allows the creation of plugins that can participate 45 in authorization decisions. Using the AuthorizationDB API the system can be configured 46 to use these plugins. Plugins are loaded into a separate process, the pluginhost, to 47 isolate the process of authorization from the client. There are two types of pluginhosts. 48 One runs as an anonymous user and can be used to communicate with the user, for example 49 to ask for a password. Another one runs with root privileges to perform privileged 50 operations that may be required. 51 52 A typical use is to implement additional policies that cannot be expressed in the 53 authorization configuration. 54 55 Plugins implement a handshake function called AuthorizationPluginCreate with which 56 their interface (AuthorizationPluginInterface) and the engine's interface 57 (AuthorizationCallbacks) are exchanged. Plugins are asked to create 58 Mechanisms, which are the basic element as authorizations are performed. 59 60 Mechanisms are invoked when it is time for them to make a decision. A decision is 61 made by setting a single result (AuthorizationResult). Mechanisms in the 62 authorization can communicate auxiliary information by setting and/or getting hints 63 and setting and/or getting context data. Hints are advisory and don't need to be 64 looked at, nor are they preserved as part of the authorization result. Context data 65 becomes part of the result of the authorization. 66 67 Context data is tagged with a flag that describes whether the information is returned 68 to the authorization client upon request (AuthorizationCopyInfo() in Authorization.h) 69 or whether it's private to the mechanisms making a decision. 70 71 */ 72 73 74 /*! 75 @typedef AuthorizationValue 76 Auxiliary data is passed between the engine and the mechanism as AuthorizationValues 77 */ 78 typedef struct AuthorizationValue 79 { 80 size_t length; 81 void * __nullable data; 82 } AuthorizationValue; 83 84 /*! 85 @typedef AuthorizationValueVector 86 A vector of AuthorizationValues. Used to communicate arguments passed from the 87 configuration file <code>authorization(5)</code>. 88 */ 89 typedef struct AuthorizationValueVector 90 { 91 UInt32 count; 92 AuthorizationValue *values; 93 } AuthorizationValueVector; 94 95 /*! 96 @typedef 97 Data produced as context during the authorization evaluation is tagged. 98 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(). 99 If data is marked as volatile (kAuthorizationContextFlagVolatile), this value will not be remembered in the AuthorizationRef. 100 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. 101 */ 102 typedef CF_OPTIONS(UInt32, AuthorizationContextFlags) 103 { 104 kAuthorizationContextFlagExtractable = (1 << 0), 105 kAuthorizationContextFlagVolatile = (1 << 1), 106 kAuthorizationContextFlagSticky = (1 << 2) 107 }; 108 109 110 /*! 111 @typedef AuthorizationMechanismId 112 The mechanism id specified in the configuration is passed to the plugin to create the appropriate mechanism. 113 */ 114 typedef const AuthorizationString AuthorizationMechanismId; 115 116 /*! 117 @typedef AuthorizationPluginId 118 Not used by plugin writers. Loaded plugins are identified by their name. 119 */ 120 typedef const AuthorizationString AuthorizationPluginId; 121 122 /*! 123 @typedef AuthorizationPluginRef 124 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. 125 */ 126 typedef void *AuthorizationPluginRef; 127 128 /*! 129 @typedef AuthorizationMechanismRef 130 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. 131 */ 132 typedef void *AuthorizationMechanismRef; 133 134 /*! 135 @typedef AuthorizationEngineRef 136 Handle passed from the engine to an instance of a mechanism in a plugin (corresponds to a particular AuthorizationMechanismRef). 137 */ 138 typedef struct __OpaqueAuthorizationEngine *AuthorizationEngineRef; 139 140 /*! 141 @typedef AuthorizationSessionId 142 A unique value for an AuthorizationSession being evaluated, provided by the authorization engine. 143 A session is represented by a top level call to an Authorization API. 144 */ 145 typedef void *AuthorizationSessionId; 146 147 /*! 148 @enum AuthorizationResult 149 Possible values for SetResult() in AuthorizationCallbacks. 150 151 @constant kAuthorizationResultAllow the operation succeeded and authorization should be granted as far as this mechanism is concerned. 152 @constant kAuthorizationResultDeny the operation succeeded but authorization should be denied as far as this mechanism is concerned. 153 @constant kAuthorizationResultUndefined the operation failed for some reason and should not be retried for this session. 154 @constant kAuthorizationResultUserCanceled the user has requested that the evaluation be terminated. 155 */ 156 typedef CF_CLOSED_ENUM(UInt32, AuthorizationResult) { 157 kAuthorizationResultAllow, 158 kAuthorizationResultDeny, 159 kAuthorizationResultUndefined, 160 kAuthorizationResultUserCanceled, 161 }; 162 163 /*! 164 @enum 165 Version of the interface (AuthorizationPluginInterface) implemented by the plugin. 166 The value is matched to the definition in this file. 167 */ 168 enum { 169 kAuthorizationPluginInterfaceVersion = 0 170 }; 171 172 /*! 173 @enum 174 Version of the callback structure (AuthorizationCallbacks) passed to the plugin. 175 The value is matched to the definition in this file. The engine may provide a newer 176 interface. 177 */ 178 enum { 179 kAuthorizationCallbacksVersion = 4 180 }; 181 182 183 /*! 184 @typedef 185 Callback API provided by the AuthorizationEngine. 186 187 @field version Engine callback version. 188 @field SetResult Set a result after a call to AuthorizationSessionInvoke. 189 @field RequestInterrupt Request authorization engine to interrupt all mechamisms invoked after this mechamism has called SessionSetResult and then call AuthorizationSessionInvoke again. 190 @field DidDeactivate Respond to the Deactivate request. 191 @field GetContextValue Read value from context. AuthorizationValue does not own data. 192 @field SetContextValue Write value to context. AuthorizationValue and data are copied. 193 @field GetHintValue Read value from hints. AuthorizationValue does not own data. 194 @field SetHintValue Write value to hints. AuthorizationValue and data are copied. 195 @field GetArguments Read arguments passed. AuthorizationValueVector does not own data. 196 @field GetSessionId Read SessionId. 197 @field GetLAContext Returns LAContext which will have LACredentialCTKPIN credential set if PIN is available otherwise context without credentials is returned. LAContext can be used for operations with Tokens which would normally require PIN. Caller owns returned context and is responsible for release. 198 @field GetTokenIdentities Returns array of identities. Caller owns returned array and is reponsible for release. 199 @field GetTKTokenWatcher Returns TKTokenWatcher object. Caller owns returned context and is responsible for release. 200 @field RemoveContextValue Removes value from context. 201 @field RemoveHintValue Removes value from hints. 202 203 */ 204 typedef struct AuthorizationCallbacks { 205 206 /* Engine callback version. */ 207 UInt32 version; 208 209 /* Set a result after a call to AuthorizationSessionInvoke. */ 210 OSStatus (*SetResult)(AuthorizationEngineRef inEngine, AuthorizationResult inResult); 211 212 /* Request authorization engine to interrupt all mechamisms invoked after 213 this mechamism has called SessionSetResult and then call 214 AuthorizationSessionInvoke again. */ 215 OSStatus (*RequestInterrupt)(AuthorizationEngineRef inEngine); 216 217 /* Respond to the Deactivate request. */ 218 OSStatus (*DidDeactivate)(AuthorizationEngineRef inEngine); 219 220 /* Read value from context. AuthorizationValue does not own data. */ 221 OSStatus (*GetContextValue)(AuthorizationEngineRef inEngine, 222 AuthorizationString inKey, 223 AuthorizationContextFlags * __nullable outContextFlags, 224 const AuthorizationValue * __nullable * __nullable outValue); 225 226 /* Write value to context. AuthorizationValue and data are copied. */ 227 OSStatus (*SetContextValue)(AuthorizationEngineRef inEngine, 228 AuthorizationString inKey, 229 AuthorizationContextFlags inContextFlags, 230 const AuthorizationValue *inValue); 231 232 /* Read value from hints. AuthorizationValue does not own data. */ 233 OSStatus (*GetHintValue)(AuthorizationEngineRef inEngine, 234 AuthorizationString inKey, 235 const AuthorizationValue * __nullable * __nullable outValue); 236 237 /* Write value to hints. AuthorizationValue and data are copied. */ 238 OSStatus (*SetHintValue)(AuthorizationEngineRef inEngine, 239 AuthorizationString inKey, 240 const AuthorizationValue *inValue); 241 242 /* Read arguments passed. AuthorizationValueVector does not own data. */ 243 OSStatus (*GetArguments)(AuthorizationEngineRef inEngine, 244 const AuthorizationValueVector * __nullable * __nonnull outArguments); 245 246 /* Read SessionId. */ 247 OSStatus (*GetSessionId)(AuthorizationEngineRef inEngine, 248 AuthorizationSessionId __nullable * __nullable outSessionId); 249 250 /* Read value from hints. AuthorizationValue does not own data. */ 251 OSStatus (*GetImmutableHintValue)(AuthorizationEngineRef inEngine, 252 AuthorizationString inKey, 253 const AuthorizationValue * __nullable * __nullable outValue); 254 255 /* 256 Available only on systems with callback version 2 or higher 257 Constructs LAContext object based od actual user credentials, 258 userful for kSecUseAuthenticationContext for SecItem calls. 259 Caller is responsible for outValue release */ 260 OSStatus (*GetLAContext)(AuthorizationEngineRef inEngine, 261 CFTypeRef __nullable * __nullable outValue) __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_NA); 262 263 /* 264 Available only on systems with callback version 2 or higher 265 Returns array of available identities available on tokens. Each array item consists of two 266 elements. The first one is SecIdentityRef and the second one is textual description of that identity 267 context parameter may contain CFTypeRef returned by GetLAContext. 268 Caller is responsible for outValue release */ 269 OSStatus (*GetTokenIdentities)(AuthorizationEngineRef inEngine, 270 CFTypeRef context, 271 CFArrayRef __nullable * __nullable outValue) __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_NA); 272 273 /* 274 Available only on systems with callback version 3 or higher 275 Constructs TKTokenWatcher object. 276 Caller is responsible for outValue release */ 277 OSStatus (*GetTKTokenWatcher)(AuthorizationEngineRef inEngine, 278 CFTypeRef __nullable * __nullable outValue) __OSX_AVAILABLE_STARTING(__MAC_10_13_4, __IPHONE_NA); 279 280 /* Remove value from hints. */ 281 OSStatus (*RemoveHintValue)(AuthorizationEngineRef inEngine, 282 AuthorizationString inKey); 283 284 /* Write value to context. */ 285 OSStatus (*RemoveContextValue)(AuthorizationEngineRef inEngine, 286 AuthorizationString inKey); 287 288 } AuthorizationCallbacks; 289 290 291 /*! 292 @typedef 293 Interface that must be implemented by each plugin. 294 295 @field version Must be set to kAuthorizationPluginInterfaceVersion 296 @field PluginDestroy Plugin should clean up and release any resources it is holding. 297 @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. 298 @field MechanismInvoke Invoke an instance of a mechanism. It should call SetResult during or after returning from this function. 299 @field MechanismDeactivate Mechanism should respond with a DidDeactivate as soon as possible 300 @field MechanismDestroy Mechanism should clean up and release any resources it is holding 301 */ 302 typedef struct AuthorizationPluginInterface 303 { 304 /* Must be set to kAuthorizationPluginInterfaceVersion. */ 305 UInt32 version; 306 307 /* 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. */ 308 OSStatus (*PluginDestroy)(AuthorizationPluginRef inPlugin); 309 310 /* The plugin should create a mechanism named mechanismId. The mechanism needs to use the 311 AuthorizationEngineRef for the callbacks and pass back an AuthorizationMechanismRef for 312 itself. MechanismDestroy will be called when it is no longer needed. */ 313 OSStatus (*MechanismCreate)(AuthorizationPluginRef inPlugin, 314 AuthorizationEngineRef inEngine, 315 AuthorizationMechanismId mechanismId, 316 AuthorizationMechanismRef __nullable * __nonnull outMechanism); 317 318 /* Invoke an instance of a mechanism. It should call SetResult during or after returning from this function. */ 319 OSStatus (*MechanismInvoke)(AuthorizationMechanismRef inMechanism); 320 321 /* Mechanism should respond with a DidDeactivate as soon as possible. */ 322 OSStatus (*MechanismDeactivate)(AuthorizationMechanismRef inMechanism); 323 324 /* Mechanism should clean up and release any resources it is holding. */ 325 OSStatus (*MechanismDestroy)(AuthorizationMechanismRef inMechanism); 326 327 } AuthorizationPluginInterface; 328 329 330 /*! 331 @function AuthorizationPluginCreate 332 333 Initialize a plugin after it gets loaded. This is the main entry point to a plugin. This function will only be called once. 334 After all Mechanism instances have been destroyed outPluginInterface->PluginDestroy will be called. 335 336 @param callbacks (input) A pointer to an AuthorizationCallbacks which contains the callbacks implemented by the AuthorizationEngine. 337 @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. 338 @param outPluginInterface (output) On successful completion should contain a pointer to a AuthorizationPluginInterface that will stay valid until outPluginInterface->PluginDestroy is called. */ 339 OSStatus AuthorizationPluginCreate(const AuthorizationCallbacks *callbacks, 340 AuthorizationPluginRef __nullable * __nonnull outPlugin, 341 const AuthorizationPluginInterface * __nullable * __nonnull outPluginInterface); 342 343 CF_ASSUME_NONNULL_END 344 345 #if defined(__cplusplus) 346 } 347 #endif 348 349 #endif /* _SECURITY_AUTHORIZATIONPLUGIN_H_ */