Mac Developer Library

Developer

Security Framework Reference Authorization Plug-in Reference

Options
Deployment Target:

On This Page
Language:

Authorization Plug-in Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import Security

Objective-C

@import Security;

The Authorization Plug-in API enables you to create plug-ins that can participate in authorization decisions.

Authorization Plug-ins are available starting in OS X v10.4.

You should read this document if you need to extend OS X authorization services to perform authorizations in a new way or to implement a new policy that is too complex to be implemented entirely with the authorization policy database.

Organization of This Document

This document consists of an introduction and a reference to the authorization plug-in API. It contains the following sections:

  • About Authorization Plug-ins gives a brief introduction to the purpose and use of authorization plug-ins and gives basic instructions for installing one.

  • Authorization Plug-in Functions describes the functions that your plug-in can call to communicate with the authorization engine. You use these functions to set and get data and to report the status of your plug-in.

  • Functions Implemented By the Plug-in describes the functions that must be implemented by your plug-in. These functions are called by the authorization engine in order to install the plug-in, implement and execute the plug-in’s authorization mechanisms, and deactivate or remove the plug-in.

  • Authorization Plug-in Data Types describes the structures and other data types defined in AuthorizationPlugin.h.

  • Authorization Plug-in Constants describes the constants defined in AuthorizationPlugin.h.

  • Authorization Plug-in Result Codes lists the result codes used by authorization plug-ins.

See Also

For more information about OS X authorization services, see the following documents:

About Authorization Plug-ins

To install an authorization plug-in, you write the plug-in using the API described in this document, install the bundle in /System/Library/CoreServices/SecurityAgentPlugins, and use the AuthorizationRightSet function to add an entry to the authorization policy database that references the plug-in. The authorization policy database contains a set of rules that the Security Server uses to authorize rights for a user. Most of the rules directly specify the criteria to allow or deny access; however, some reference external code (referred to as authorization mechanisms) that define the behavior. The authorization database is described in The Policy Database section of Authorization Services Programming Guide. To invoke a plug-in, you pass the name of the database entry that references that plug-in in the rights parameter of the AuthorizationCopyRights function.

A typical use for authorization plug-ins is to implement policies that are not included in the standard authorization configuration. For example, you could write a plug-in that authorizes a user to send a fax by requiring a personal identification number (PIN) for a specific fax machine.

A plug-in’s main entry point must be the function AuthorizationPluginCreate, which exchanges the plug-in’s interface (AuthorizationPluginInterface) and the authorization interface of the Security Server (AuthorizationCallbacks).

When you add a policy to the authorization policy database, it can refer to any number of plug-ins. Each plug-in includes one or more authorization mechanisms, where a mechanism is a code module that performs one step in the authorization process.

For example, if you wrote a policy for sending faxes that required users to select the fax machine they wanted to use and enter a PIN for that machine, you might name the policy com.ifoo.ifax.send. To implement the policy, you could write a plug-in called SendFaxPlugin that contains two mechanisms: SelectFaxMachine and GetUserPIN. You would add your plug-in code to the folder /System/Library/CoreServices/SecurityAgentPlugins as a bundle called SendFaxPlugin.bundle and you would use the AuthorizationRightSet function to add the lines shown in Listing 1 to the authorization policy database:

Listing 1Plug-in entry in policy database
  • <key>com.ifoo.ifax.send</key>
  • <dict>
  • <key>class</key>
  • <string>evaluate-mechanisms</string>
  • <key>comment</key>
  • <string>Rule to evaluate whether user has right to
  • use a specific fax machine.
  • </string>
  • <key>mechanisms</key>
  • <array>
  • <string>SendFaxPlugin:SelectFaxMachine</string>
  • <string>SendFaxPlugin:GetUserPIN</string>
  • </array>
  • </dict>

Notice that each plug-in is identified by the name of the plug-in, a colon, and the name of the mechanism; for example SendFaxPlugin:SelectFaxMachine where SelectFaxMachine is a mechanism in the plug-in SendFaxPlugin.The keys used in the dictionary entry are listed in the files AuthorizationTags.h and AuthorizationTagsPriv.h. (Note that AuthorizationTagsPriv.h is not part of the public API. Apple reserves the right to change this file or its contents with future releases.)

The Security Server loads plug-ins into a separate process—a plug-in host—to isolate the process of authorization from the client. There are two plug-in hosts:

  • One runs as an anonymous user and can be used to communicate with the user, for example to ask for a password.

  • One runs with root privileges to perform privileged operations.

In this document, the portion of the Security Server that deals with authorization and authentication, together with the plug-in hosts, is referred to as the authorization engine.

To have a specific mechanism run with root privileges, add a comma and the word privileged to the mechanism name; for example:

<string>SendFaxPlugin:ChangeUserPIN,privileged</string>

When the authorization engine needs an authorization decision based on a policy that belongs to the plug-in, the authorization engine calls each mechanism belonging to that policy in turn, in the order they are listed in the policy database. For each mechanism, the authorization engine calls the plug-in’s MechanismInvoke function, passing the plug-in name:mechanism name for that mechanism.

The mechanism calls the SetResult function to report the authorization decision. The authorization engine does not consider the authorization complete and approved until all the mechanisms have returned a positive (kAuthorizationResultAllow) authorization decision, one of the mechanisms has returned a negative (kAuthorizationResultDeny) decision, the maximum number of retries has been reached (kAuthorizationResultUndefined), or the user has canceled the attempt (kAuthorizationResultUserCanceled).

Mechanisms in the authorization can communicate auxiliary information by setting and getting hints and context data. Hints are data values for use during authorization; for example, you can use a hint to pass an intermediate value from one mechanism to a subsequent mechanism. They are not preserved as part of the authorization result. Context data is information that can be useful to an application, such as a user name entered by the user during the authorization process. Context data can be added, read, or modified by each mechanism in the authorization and is preserved by the Security Server. Context data can also be made available to the authorization client after authorization is complete. See SetHintValue and SetContextValue for more information on hints and context data.

When the authorization plug-in sets context data, it tags the data with a flag that specifies whether the information should be returned to the authorization client upon request (by using the AuthorizationCopyInfo function) or whether it’s restricted to the mechanisms involved in the authorization.

Functions

Your authorization plug-in communicates with the authorization engine through the engine’s callback functions. These functions are declared in the AuthorizationCallbacks structure passed to your plug-in through the AuthorizationPluginCreate function.

  • Return the result of an authorization operation.

    Declaration

    Objective-C

    OSStatus (*SetResult)( AuthorizationEngineRef inEngine, AuthorizationResult inResult );

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    inResult

    The result of the authorization attempt. See Authorization Result for possible values.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    When an application calls the AuthorizationCopyRights function to request a specific authorization right, the Security Agent looks for that right in the authorization policy database. If that right corresponds to your plug-in, the authorization engine calls the MechanismInvoke function for each mechanism listed in the policy database for your plug-in.

    When the authorization engine calls your MechanismInvoke function, your plug-in should invoke the specified mechanism to attempt an authorization operation. You use the SetResult function to return the results of this operation. If the mechanism returns kAuthorizationResultAllow, then the authorization engine calls the next mechanism (if any) specified in the authorization policy database for the policy. If any of the mechanisms report a result other than kAuthorizationResultAllow, the authorization attempt fails. If all of the mechanisms report results of kAuthorizationResultAllow, the authorization is considered to have succeeded.

    Note that you can spin off a separate process and return from MechanismInvoke before calling SetResult. For example, you might do so to avoid blocking the Security Server if your mechanism takes a significant amount of time to complete or if you want to be able to cancel the operation by calling the RequestInterrupt function (if, for example, the user has clicked Cancel).In that case, your separate process must call the SetResult function to report the result; the authorization engine does not call the next mechanism until you do so.

    The authorization engine sends you the entry point to the SetResult function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Availability

    Available in OS X v10.4 and later.

  • Request the authorization engine to interrupt the currently active authorization mechanism.

    Declaration

    Objective-C

    OSStatus (*RequestInterrupt)( AuthorizationEngineRef inEngine, );

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    When you call this function, the security engine calls the MechanismDeactivate function for your plug-in’s currently-active mechanism; that is, the mechanism that was last invoked and that has not yet called the SetResult function to report its result. Your mechanism should then stop any active processing and call the DidDeactivate function. When all mechanisms are inactive (that is, they have called either SetResult or DidDeactivate), the authorization engine calls the MechanismInvoke function for the mechanism that called RequestInterrupt so that it can resume the authorization process from that point. After all mechanisms have called SetResult, the authorization engine calls each mechanism’s MechanismDestroy function.

    If your mechanism spins off a separate process or UI thread, that thread can call the RequestInterrupt function to reinvoke the mechanism, even if that mechanism has already called the SetResult function. For example, if your plug-in implements a smart card authentication method, reading and evaluating the card might take several minutes to perform. Therefore, in order to avoid blocking other processing while the card is being evaluated, you might spin off a UI thread to interact with the user and then return from MechanismInvoke. When the card has been read, the UI thread calls the SetResult function with a value of kAuthorizationResultAllow and changes the UI to request the user’s PIN. The authorization engine calls the next mechanism, which verifies the PIN. If the user pulls out the card before the verification is complete, the UI thread can call RequestInterrupt. The authorization engine then calls the active mechanism’s MechanismDeactivate function, causing it to terminate the PIN verification and call DidDeactivate. Then the authorization engine calls your UI mechanism’s MechanismInvoke function again. Your UI can then prompt the user to reinsert the card.

    To understand this sequence better, suppose your plug-in contains three mechanisms: A, B, and C. Mechanism A has called SetResult and has no active processes. Mechanism B has called SetResult, but still has a UI thread running. Mechanism C is running and has not yet called SetResult. The user clicks Cancel or otherwise interrupts the UI thread, causing the UI thread to call the RequestInterrupt function. The following sequence of events occurs:

    1. The authorization engine calls mechanism C’s MechanismDeactivate function.

    2. Mechanism C stops active processing and calls the DidDeactivate function.

    3. The authorization engine calls mechanism B’s MechanismInvoke function (because mechanism B is the one that called RequestInterrupt).

    4. Mechanism B updates the UI and calls the SetResult function with the value kAuthorizationResultAllow.

    5. The authorization engine calls mechanism C’s MechanismInvoke function.

    6. Mechanism C completes processing and calls SetResult with kAuthorizationResultAllow.

    7. The authorization engine calls the MechanismDestroy function of each mechanism in turn (A, B, then C).

    The authorization engine sends you the entry point to the RequestInterrupt function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Availability

    Available in OS X v10.4 and later.

  • Report the successful deactivation of an authorization mechanism.

    Declaration

    Objective-C

    OSStatus (*DidDeactivate)( AuthorizationEngineRef inEngine, );

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    You must call this function after deactivating your authorization mechanism in response to a call to your MechanismDeactivate function. The authorization engine waits for confirmation that all mechanisms have deactivated before continuing.

    The authorization engine sends you the entry point to the DidDeactivate function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Availability

    Available in OS X v10.4 and later.

  • Read a value collected during authorization.

    Declaration

    Objective-C

    OSStatus (*GetContextValue)( AuthorizationEngineRef inEngine, AuthorizationString inKey, AuthorizationContextFlags *outContextFlags, const AuthorizationValue **outValue);

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    inKey

    A key indicating which value you want to retrieve. This key must correspond to one you specified when you used the SetContextValue function to store a context value.

    outContextFlags

    On output points to a flag that indicates whether this value is available to the authorization client.

    outValue

    On input, allocate a pointer to an AuthorizationValue structure. On output, the structure contains the size of the data and a pointer to the data. Because your AuthorizationValue structure does not own the data, you must not deallocate the structure or the data pointed to by the structure.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    Your plug-in authorization mechanism might collect data such as the user name and other authentication information during evaluation of authorization. You can use the SetContextValue function to have the Security Server store this data and the GetContextValue function to retrieve it.

    The authorization engine sends you the entry point to the GetContextValue function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Do not call this function after you have called the SetResult function. If you do so, the data retrieved by the GetContextValue function might not reflect the current value even though the function returns the errAuthorizationSuccess result code.

    Availability

    Available in OS X v10.4 and later.

  • Store data collected during authorization as a key-value pair.

    Declaration

    Objective-C

    OSStatus (*SetContextValue)( AuthorizationEngineRef inEngine, AuthorizationString inKey, AuthorizationContextFlags inContextFlags, const AuthorizationValue *inValue);

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    inKey

    A key identifying the value you are storing. For standard values such as user names, use the keys listed in DirectoryService/DirServicesConst.h. If you need to define a new key, use reverse domain notation (such as com.apple.ifoo) and make sure the key is unique. For example, you can use your company name as a prefix for the key name.

    inContextFlags

    A flag that indicates whether this value should be available to the authorization client.

    inValue

    A pointer to an AuthorizationValue structure that contains the size of the context data and a pointer to the data. Both the structure and the data are copied to the context maintained by the Security Server.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    Your plug-in authorization mechanism collects data such as the user name and other authentication information during evaluation of authorization. You can use this function to have the Security Server store this data and the GetContextValue function to retrieve it.

    When you store this context data, you flag it to indicate whether the authorization client can obtain the value with the AuthorizationCopyInfo function. If data is set to be extractable (kAuthorizationContextFlagExtractable), it is possible for the authorization client to use the AuthorizationCopyInfo function to obtain the value. If data is marked as volatile (kAuthorizationContextFlagVolatile), the value is not available to the client. In any case, sensitive data such as a user’s password is not provided to the client.

    The authorization engine sends you the entry point to the SetContextValue function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Do not call this function after you have called the SetResult function. If you do so, the function does not set the context data, even though the function returns the errAuthorizationSuccess result code.

    Availability

    Available in OS X v10.4 and later.

  • Read a value stored by the plug-in authorization mechanism.

    Declaration

    Objective-C

    OSStatus (*GetHintValue)( AuthorizationEngineRef inEngine, AuthorizationString inKey, const AuthorizationValue **outValue);

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    inKey

    A key indicating which value you want to retrieve. This key must correspond to one you specified when you used the GetHintValue function to store a hint value.

    outValue

    On input, allocate a pointer to an AuthorizationValue structure. On output, the structure contains the size of the data and a pointer to the data. Because your AuthorizationValue structure does not own the data, you must not deallocate the structure or the data pointed to by the structure.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    Your plug-in authorization mechanism can save and retrieve auxiliary information—called hints—for use by subsequent mechanisms that are part of the same authorization. You use the SetHintValue function to have the Security Server store this data and the GetHintValue function to retrieve it. Hints are not preserved as part of the authorization result; once all mechanisms have approved the authorization or any mechanism has denied it, the security engine disposes of the hints.

    The authorization engine sends you the entry point to the GetHintValue function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Do not call this function after you have called the SetResult function. If you do so, the data retrieved by the GetHintValue function might not reflect the current value even though the function returns the errAuthorizationSuccess result code.

    Availability

    Available in OS X v10.4 and later.

  • Store data needed during authorization as a key-value pair.

    Declaration

    Objective-C

    OSStatus (*SetHintValue)( AuthorizationEngineRef inEngine, AuthorizationString inKey, const AuthorizationValue *inValue);

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    inKey

    A key identifying the value you are storing. For standard values such as a time stamp, use the keys listed in DirectoryService/DirServicesConst.h. If you need to define a new key, make sure the key is unique. For example, you can use your company name as a prefix for the key name.

    inValue

    A pointer to an AuthorizationValue structure that contains the size of the data and a pointer to the data. Both the structure and the data are copied to storage maintained by the authorization engine.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    Your plug-in authorization mechanism can save and retrieve auxiliary information—called hints—for use by subsequent mechanisms that are part of the same authorization. You use the SetHintValue function to have the Security Server store this data and the GetHintValue function to retrieve it. Hints are not preserved as part of the authorization result; once all mechanisms have approved the authorization or any mechanism has denied it, the security engine disposes of the hints.

    The authorization engine sends you the entry point to the SetHintValue function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Do not call this function after you have called the SetResult function. If you do so, the function does not set the hint data, even though the function returns the errAuthorizationSuccess result code.

    Availability

    Available in OS X v10.4 and later.

  • Read the arguments for this authorization mechanism from the authorization policy database. Authorization policy database arguments have not yet been implemented.

    Declaration

    Objective-C

    OSStatus (*GetArguments)( AuthorizationEngineRef inEngine, const AuthorizationValueVector **outArguments);

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    outValue

    On input, allocate a pointer to an AuthorizationValueVector structure. On output, the structure contains the number of arguments and a pointer to the data. Because your AuthorizationValueVector structure does not own the data, you must not deallocate the structure or the data pointed to by the structure.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    The authorization policy database might contain arguments for each authentication mechanism. You can use this function to retrieve these arguments.

    The authorization engine sends you the entry point to the GetArguments function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Availability

    This function is available in OS X v10.4 and later; however, the database does not yet support arguments.

  • Read the session ID.

    Declaration

    Objective-C

    OSStatus (*GetSessionID)( AuthorizationEngineRef inEngine, AuthorizationSessionId *outSessionId);

    Parameters

    inEngine

    An opaque handle that is passed to your plug-in when the authorization engine calls your MechanismCreate function.

    outSessionId

    On output, points to the session ID.

    Return Value

    A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

    Discussion

    The session ID is a unique value provided by the authorization engine for a given authorization session. Normally, all the mechanisms in your plug-in are called in turn for a given authorization session and there is no need to ask for the session ID. However, if you were to launch an authorization daemon (for example) that caches data from different authorization sessions and then uses that data later, you might need to keep track of which session a given data item came from. The session ID is available for your use if you wish to implement such a system.

    The authorization engine sends you the entry point to the GetSessionID function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.

    Availability

    Available in OS X v10.4 and later.

Callbacks

  • Initializes the plug-in and exchanges interfaces with the authorization engine.

    Declaration

    Objective-C

    OSStatus AuthorizationPluginCreate ( const AuthorizationCallbacks *callbacks, AuthorizationPluginRef *outPlugin, const AuthorizationPluginInterface **outPluginInterface );

    Parameters

    callbacks

    A pointer to a structure containing entry points to the Security Server. The functions in this interface are described in Calling the Authorization Engine.

    outPlugin

    On input, a pointer that you can assign, on output, to a reference value that you define. The authorization engine passes this reference back to you in any subsequent calls to your functions outPluginInterface->MechanismCreate (MechanismCreate) and outPluginInterface->PluginDestroy (MechanismDestroy) so that you can identify the instance of the plug-in affected.

    outPluginInterface

    On input, a pointer that you assign, on output, to a structure containing entry points in the plug-in. This structure remains valid until the authorization engine calls outPluginInterface->PluginDestroy.

    Return Value

    A result code. Return errAuthorizationSuccess (no error) if the function completes successfully and errAuthorizationInternal (Security Server internal error) if any error occurs.

    Discussion

    This function is the main entry point to the plug-in. The authorization engine calls this function only once. The plug-in receives a structure (AuthorizationCallbacks) containing the entry points to the Security Server’s functions (described in Calling the Authorization Engine) and returns a structure (AuthorizationPluginInterface) containing the entry points to all of the plug-in’s routines (Authorization Plug-in Interface Functions). Both of these structures contain version numbers. The authorization engine matches the version of its interface to the version in your plug-in’s AuthorizationPluginInterface structure in order to ensure that older plug-ins will continue to function correctly after the Security Server is updated.

    If your plug-in is running in OS X v10.5 or later and displays a window before the user has logged in, you must set the kHIWindowBitCanBeVisibleWithoutLogin flag on the window.

    For Cocoa, the NSWindow method to do this is:

    • - (void)setCanBecomeVisibleWithoutLogin:(BOOL)flag;

    This method is available in OS X v10.5 and later; see NSWindow Class Reference.

    For Carbon, you set the kHIWindowBitCanBeVisibleWithoutLogin attribute directly; see Window Manager Reference. This attribute is also supported by IBCarbonRuntime and when archiving a window.

    Availability

    Available in OS X v10.4 and later.

You must declare and implement the functions referred to in the AuthorizationPluginInterface structure that you pass to the authorization engine with the AuthorizationPluginCreate function.

  • Notifies the plug-in that it is about to be unloaded.

    Declaration

    Objective-C

    OSStatus (*PluginDestroy)( AuthorizationPluginRef inPlugin );

    Parameters

    inPlugin

    The authorization plug-in reference you assigned to the plug-in in the AuthorizationPluginCreate function.

    Return Value

    A result code. Return errAuthorizationSuccess (no error) if the function completes successfully and errAuthorizationInternal (Security Server internal error) if any error occurs.

    Discussion

    When this function is called, your plug-in should release any resources it is holding and do any other cleanup necessary (such as deleting temporary files) before it is unloaded.

    Availability

    Available in OS X v10.4 and later.

  • Create an authorization mechanism.

    Declaration

    Objective-C

    OSStatus (*MechanismCreate)( AuthorizationPluginRef inPlugin, AuthorizationEngineRef inEngine, AuthorizationMechanismId mechanismId, AuthorizationMechanismRef *outMechanism );

    Parameters

    inPlugin

    The authorization plug-in reference you assigned to the plug-in in the AuthorizationPluginCreate function.

    inEngine

    An opaque handle that you must pass back to the authorization engine when you call one of the engine’s callback functions.

    mechanismID

    The mechanism ID specified in the authorization policy database is passed to the plug-in so that the plug-in can create the appropriate mechanism.

    outMechanism

    On output, points to an authorization mechanism reference that you define. The authorization engine includes this reference when it calls your plug-in so that you can identify which instance of a mechanism to invoke, deactivate, or destroy.

    Return Value

    A result code. Return errAuthorizationSuccess (no error) if the function completes successfully and errAuthorizationInternal (Security Server internal error) if any error occurs.

    Discussion

    A given authorization plug-in can implement any number of authorization mechanisms, distinguished by their mechanism names in the authorization policy database. For an example, see Listing 1.

    When the authorization engine calls your MechanismCreate function, you should create a mechanism of the type specified by the mechanismID parameter and return an authorization mechanism reference. Subsequently, the authorization engine can call your MechanismInvoke function to perform an authorization, or can direct you to deactivate or destroy the mechanism instance by calling your MechanismDeactivate or MechanismDestroy functions.

    Availability

    Available in OS X v10.4 and later.

  • Invoke an authorization mechanism to perform an authorization operation.

    Declaration

    Objective-C

    OSStatus (*MechanismInvoke)( AuthorizationMechanismRef inMechanism );

    Parameters

    inMechanism

    An authorization mechanism reference that you returned when your MechanismCreate function was called to create the mechanism.

    Return Value

    A result code. Return errAuthorizationSuccess (no error) if the function completes successfully and errAuthorizationInternal (Security Server internal error) if any error occurs.

    Discussion

    When the authorization engine calls your MechanismInvoke function, you should perform the authorization operation indicated by the mechanism reference. You can use the functions GetArguments, GetContextValue, and GetHintValue to get more information, if any, about the authorization.

    Availability

    Available in OS X v10.4 and later.

  • Deactivate an authorization mechanism.

    Declaration

    Objective-C

    OSStatus (*MechanismDeactivate)( AuthorizationMechanismRef inMechanism );

    Parameters

    inMechanism

    An authorization mechanism reference that you returned when your MechanismCreate function was called to create the mechanism.

    Return Value

    A result code. Return errAuthorizationSuccess (no error) if the function completes successfully and errAuthorizationInternal (Security Server internal error) if any error occurs.

    Discussion

    The authorization engine calls the MechanismDeactivate function of each active mechanism when you call the RequestInterrupt function. To deactivate your mechanism, you must stop any processing that is currently underway; for example, you should terminate any threads or UI processes that you initiated.

    After you have terminated all processing, you must call the DidDeactivate function; the authorization engine waits for you to call this function before it resumes operation.

    Availability

    Available in OS X v10.4 and later.

  • Destroy an authorization mechanism.

    Declaration

    Objective-C

    OSStatus (*MechanismDestroy)( AuthorizationMechanismRef inMechanism );

    Parameters

    inMechanism

    An authorization mechanism reference that you returned when your MechanismCreate function was called to create the mechanism.

    Return Value

    A result code. Return errAuthorizationSuccess (no error) if the function completes successfully and errAuthorizationInternal (Security Server internal error) if any error occurs.

    Discussion

    When the authorization engine calls your MechanismDestroy function, you must release all resources owned by your mechanism and do any other cleanup necessary (such as deleting temporary files).

    Availability

    Available in OS X v10.4 and later.

Data Types

Constants

  • Defines flags that specify whether authentication data should be made available to the authorization client.

    Declaration

    Objective-C

    typedef UInt32 AuthorizationContextFlags; enum { kAuthorizationContextFlagExtractable = (1 << 0), kAuthorizationContextFlagVolatile = (1 << 1), kAuthorizationContextFlagSticky = (1 << 2) };

    Constants

    • kAuthorizationContextFlagExtractable

      kAuthorizationContextFlagExtractable

      It is possible for the authorization client to use the AuthorizationCopyInfo function to obtain the value.

      Available in OS X v10.4 and later.

    • kAuthorizationContextFlagVolatile

      kAuthorizationContextFlagVolatile

      The value is not saved for the authorization client.

      Available in OS X v10.4 and later.

    • kAuthorizationContextFlagSticky

      kAuthorizationContextFlagSticky

      This data persists through an interrupted or failed evaluation.

      This flag can be used to propagate an error condition from a downstream plug-in to an upstream one. It is not remembered in the authorization reference (see Authorization Services C Reference.

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.4 and later.

  • The result of an authorization evaluation.

    Declaration

    Objective-C

    enum { kAuthorizationResultAllow, kAuthorizationResultDeny, kAuthorizationResultUndefined, kAuthorizationResultUserCanceled, };

    Constants

    • kAuthorizationResultAllow

      kAuthorizationResultAllow

      The authorization operation succeeded and authorization should be granted.

      Available in OS X v10.4 and later.

    • kAuthorizationResultDeny

      kAuthorizationResultDeny

      The authorization operation succeeded and authorization should be denied.

      Available in OS X v10.4 and later.

    • kAuthorizationResultUndefined

      kAuthorizationResultUndefined

      The authorization operation failed and should not be retried for this session.

      Available in OS X v10.4 and later.

    • kAuthorizationResultUserCanceled

      kAuthorizationResultUserCanceled

      The user has requested that the authorization evaluation be terminated.

      Available in OS X v10.4 and later.

  • The version of the interface implemented by the plug-in.

    Declaration

    Objective-C

    enum { kAuthorizationPluginInterfaceVersion = 0 };

    Discussion

    The plug-in interface is defined by the AuthorizationPluginInterface structure and described in Functions Implemented By the Plug-in.

  • The version of the interface implemented by the authorization engine.

    Declaration

    Objective-C

    enum { kAuthorizationCallbacksVersion = 0 };

    Discussion

    The authorization engine interface is defined by the AuthorizationCallbacks structure and described in Calling the Authorization Engine.

Result Codes

The result codes used by authorization plug-ins are listed in the table below.

  • The operation completed successfully.

    Value

    0

    Description

    The operation completed successfully.

    Available in OS X v10.0 and later.

  • An unrecognized internal error occurred.

    Value

    -60008

    Description

    An unrecognized internal error occurred.

    Available in OS X v10.0 and later.