Mac Developer Library

Developer

SecurityFoundation Framework Reference SFAuthorization Class Reference

Options
Deployment Target:

On This Page
Language:

SFAuthorization

The SFAuthorization class allows you to restrict a user’s access to particular features in your Mac app or daemon. More...

Inheritance


Conforms To


Import Statement


import SecurityFoundation @import SecurityFoundation;

Availability


Available in OS X v10.3 and later
  • Returns an authorization object initialized with a default environment, flags, and rights.

    Declaration

    Swift

    class func authorization() -> AnyObject!

    Objective-C

    + (id)authorization

    Return Value

    The authorization object.

    Import Statement

    import SecurityFoundation

    Availability

    Available in OS X v10.3 and later.

  • Returns an authorization object initialized with the specified flags, rights and environment.

    Declaration

    Swift

    class func authorizationWithFlags(_ flags: AuthorizationFlags, rights rights: UnsafePointer<AuthorizationRights>, environment environment: UnsafePointer<AuthorizationEnvironment>) -> AnyObject!

    Objective-C

    + (id)authorizationWithFlags:(AuthorizationFlags)flags rights:(const AuthorizationRights *)rights environment:(const AuthorizationEnvironment *)environment

    Parameters

    flags

    A bit mask for specifying authorization options. Use the following option sets:

    • Pass the constant kAuthorizationFlagDefaults if no options are necessary.

    • Specify the kAuthorizationFlagExtendRights mask to request rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

    • Specify the kAuthorizationFlagPartialRights and kAuthorizationFlagExtendRights masks to request partial rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

    • Specify the kAuthorizationFlagPreAuthorize and kAuthorizationFlagExtendRights masks to preauthorize rights.

    • Specify the kAuthorizationFlagDestroyRights mask to prevent the Security framework from preserving the rights obtained during this call.

    rights

    A pointer to a set of authorization rights you create. Pass NULL if the application requires no rights at this time.

    environment

    Data used when authorizing or preauthorizing rights. In OS X v10.3 and later, you can pass icon or prompt data to be used in the authentication dialog box. Possible values for this parameter are listed in Security.framework/Headers/AuthorizationTags.h. The data passed in this parameter is not stored in the authorization reference; it is used only during authorization. If you are not passing any data in this parameter, pass the constant kAuthorizationEmptyEnvironment.

    Return Value

    The authorization object.

    Discussion

    Normally, such initialization is not required, as you pass in flags, rights, and environmental data when you request authorization.

    Import Statement

    import SecurityFoundation

    Availability

    Available in OS X v10.3 and later.

    See Also

    + authorization

  • Initializes an authorization object with default environment, flags, and rights.

    Declaration

    Swift

    init!()

    Objective-C

    - (id)init

    Import Statement

    import SecurityFoundation

    Availability

    Available in OS X v10.5 and later.

  • Initializes an authorization object with the specified flags, rights, and environment.

    Declaration

    Swift

    init!(flags flags: AuthorizationFlags, rights rights: UnsafePointer<AuthorizationRights>, environment environment: UnsafePointer<AuthorizationEnvironment>)

    Objective-C

    - (id)initWithFlags:(AuthorizationFlags)flags rights:(const AuthorizationRights *)rights environment:(const AuthorizationEnvironment *)environment

    Parameters

    flags

    A bit mask for specifying authorization options. Use the following option sets:

    • Pass the constant kAuthorizationFlagDefaults if no options are necessary.

    • Specify the kAuthorizationFlagExtendRights mask to request rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

    • Specify the kAuthorizationFlagPartialRights and kAuthorizationFlagExtendRights masks to request partial rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

    • Specify the kAuthorizationFlagPreAuthorize and kAuthorizationFlagExtendRights masks to preauthorize rights.

    • Specify the kAuthorizationFlagDestroyRights mask to prevent the Security framework from preserving the rights obtained during this call.

    rights

    A pointer to a set of authorization rights you create. Pass NULL if the application requires no rights at this time.

    environment

    Data used when authorizing or preauthorizing rights. In OS X v10.3 and later, you can pass icon or prompt data to be used in the authentication dialog box. Possible values for this parameter are listed in Security/AuthorizationTags.h. If you are not passing any data in this parameter, pass the constant kAuthorizationEmptyEnvironment.

    Return Value

    The authorization object.

    Discussion

    You can use this method to initialize an authorization object. Normally, such initialization is not required, as you pass in flags, rights, and environmental data when you request authorization.

    Import Statement

    import SecurityFoundation

    Availability

    Available in OS X v10.3 and later.

  • Authorizes and preauthorizes rights to access a privileged operation and returns the granted rights.

    Declaration

    Objective-C

    - (OSStatus)permitWithRights:(const AuthorizationRights *)rights flags:(AuthorizationFlags)flags environment:(const AuthorizationEnvironment *)environment authorizedRights:(AuthorizationRights *)authorizedRights

    Parameters

    rights

    A pointer to a set of authorization rights you create. Pass NULL if the application requires no rights at this time.

    flags

    A bit mask for specifying authorization options. Use the following option sets:

    • Pass the constant kAuthorizationFlagDefaults if no options are necessary.

    • Specify the kAuthorizationFlagExtendRights mask to request rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

    • Specify the kAuthorizationFlagPartialRights and kAuthorizationFlagExtendRights masks to request partial rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

    • Specify the kAuthorizationFlagPreAuthorize and kAuthorizationFlagExtendRights masks to preauthorize rights.

    • Specify the kAuthorizationFlagDestroyRights mask to prevent the Security framework from preserving the rights obtained during this call.

    environment

    Data used when authorizing or preauthorizing rights. In OS X v10.3 and later, you can pass icon or prompt data to be used in the authentication dialog box. Possible values for this parameter are listed in Security/AuthorizationTags.h. If you are not passing any data in this parameter, pass the constant kAuthorizationEmptyEnvironment.

    authorizedRights

    A pointer to a newly allocated AuthorizationRights structure. On return, this structure contains the rights granted by the Security framework. If you do not require this information, pass NULL. If you specify the kAuthorizationFlagPreAuthorize mask in the flags parameter, the method returns all the requested rights, including those not granted, but the flags of the rights that could not be preauthorized include the kAuthorizationFlagCanNotPreAuthorize bit.

    Free the memory associated with this set of rights by calling the Authorization Services function AuthorizationFreeItemSet.

    Discussion

    There are three main reasons to use this method. The first reason is to preauthorize rights by specifying the kAuthorizationFlagPreAuthorize, kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options. Preauthorization is most useful when a right has a zero timeout. For example, you can preauthorize in the application and if it succeeds, call the helper tool and request authorization. This eliminates calling the helper tool if the Security framework cannot later authorize the specified rights.

    The second reason to use this method is to authorize rights before performing a privileged operation by specifying the kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options.

    The third reason to use this method is to authorize partial rights. By specifying the kAuthorizationFlagPartialRights, kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options, the Security framework grants all rights it can authorize. On return, the authorized set contains all the rights.

    If you do not specify the kAuthorizationFlagPartialRights mask and the Security framework denies at least one right, then the status of this method on return is errAuthorizationDenied.

    If you do not specify the kAuthorizationFlagInteractionAllowed mask and the Security framework requires user interaction, then the status of this method on return is errAuthorizationInteractionNotAllowed.

    If you specify the kAuthorizationFlagInteractionAllowed mask and the user cancels the authentication process, then the status of this method on return is errAuthorizationCanceled.

    Special Considerations

    The authorizedRights parameter is not supported in OS X v10.3; use the Authorization Services function AuthorizationCopyRights instead. In OS X v10.3 there is an error in the signature in the header file for this parameter. If you pass this argument as (AuthorizationRights **)authorizedRights, as shown in this document, it works as described.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

  • Authorizes and preauthorizes rights to access a privileged operation and returns the granted rights.

    Declaration

    Swift

    func obtainWithRights(_ rights: UnsafePointer<AuthorizationRights>, flags flags: AuthorizationFlags, environment environment: UnsafePointer<AuthorizationEnvironment>, authorizedRights authorizedRights: UnsafeMutablePointer<UnsafeMutablePointer<AuthorizationRights>>, error error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)obtainWithRights:(const AuthorizationRights *)rights flags:(AuthorizationFlags)flags environment:(const AuthorizationEnvironment *)environment authorizedRights:(AuthorizationRights **)authorizedRights error:(NSError **)error

    Parameters

    rights

    A pointer to a set of authorization rights you create. Pass NULL if the application requires no rights at this time.

    flags

    A bit mask for specifying authorization options. Use the following option sets:

    • Pass the constant kAuthorizationFlagDefaults if no options are necessary.

    • Specify the kAuthorizationFlagExtendRights mask to request rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

    • Specify the kAuthorizationFlagPartialRights and kAuthorizationFlagExtendRights masks to request partial rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

    • Specify the kAuthorizationFlagPreAuthorize and kAuthorizationFlagExtendRights masks to preauthorize rights.

    • Specify the kAuthorizationFlagDestroyRights mask to prevent the Security framework from preserving the rights obtained during this call.

    environment

    Data used when authorizing or preauthorizing rights. In OS X v10.3 and later, you can pass icon or prompt data to be used in the authentication dialog box. Possible values for this parameter are listed in Security/AuthorizationTags.h. If you are not passing any data in this parameter, pass the constant kAuthorizationEmptyEnvironment.

    authorizedRights

    A pointer to a newly allocated AuthorizationRights structure. On return, this structure contains the rights granted by the Security framework. If you do not require this information, pass NULL. If you specify the kAuthorizationFlagPreAuthorize mask in the flags parameter, the method returns all the requested rights, including those not granted, but the flags of the rights that could not be preauthorized include the kAuthorizationFlagCanNotPreAuthorize bit.

    Free the memory associated with this set of rights by calling the Authorization Services function AuthorizationFreeItemSet.

    error

    On completion, the result code returned by the method. See “Result Codes” in Authorization Services C Reference.

    Return Value

    YEStrue if operation completes successfully.

    Discussion

    There are three main reasons to use this method. The first reason is to preauthorize rights by specifying the kAuthorizationFlagPreAuthorize, kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options. Preauthorization is most useful when a right has a zero timeout. For example, you can preauthorize in the application and if it succeeds, call the helper tool and request authorization. This eliminates calling the helper tool if the Security framework cannot later authorize the specified rights.

    The second reason to use this method is to authorize rights before performing a privileged operation by specifying the kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options.

    The third reason to use this method is to authorize partial rights. By specifying the kAuthorizationFlagPartialRights, kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options, the Security framework grants all rights it can authorize. On return, the authorized set contains all the rights.

    If you do not specify the kAuthorizationFlagPartialRights mask and the Security framework denies at least one right, then the method returns NOfalse and the error parameter returns errAuthorizationDenied.

    If you do not specify the kAuthorizationFlagInteractionAllowed mask and the Security framework requires user interaction, then the method returns NOfalse and the error parameter returns errAuthorizationInteractionNotAllowed.

    If you specify the kAuthorizationFlagInteractionAllowed mask and the user cancels the authentication process, then the method returns NOfalse and the error parameter returns errAuthorizationCanceled.

    Import Statement

    import SecurityFoundation

    Availability

    Available in OS X v10.5 and later.

  • Authorizes and preauthorizes one specific right.

    Deprecation Statement

    Use obtainWithRight:flags: instead.

    Declaration

    Objective-C

    - (OSStatus)permitWithRight:(AuthorizationString)rightName flags:(AuthorizationFlags)flags

    Parameters

    rightName

    The name of an authorization right.

    flags

    A bit mask for specifying authorization options. See permitWithRights:flags:environment:authorizedRights for details about possible flag values.

    Discussion

    Use this method to authorize or preauthorize a single right.

    Import Statement

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.5.

  • Authorizes and preauthorizes one specific right.

    Declaration

    Swift

    func obtainWithRight(_ rightName: AuthorizationString, flags flags: AuthorizationFlags, error error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)obtainWithRight:(AuthorizationString)rightName flags:(AuthorizationFlags)flags error:(NSError **)error

    Parameters

    rightName

    The name of an authorization right.

    flags

    A bit mask for specifying authorization options. See obtainWithRights:flags:environment:authorizedRights:error: for details about possible flag values.

    error

    On completion, the result code returned by the method. See “Result Codes” in Authorization Services C Reference.

    Return Value

    YEStrue if operation completes successfully.

    Discussion

    Use this method to authorize or preauthorize a single right.

    Import Statement

    import SecurityFoundation

    Availability

    Available in OS X v10.3 and later.