Authorization Services C

Overview

Authorization Services is an API that facilitates access control to restricted areas of the operating system and allows you to restrict a user’s access to particular features in your Mac app. Authorization Services is used in

  • software that restricts access to its own tools

  • applications that call system tools

  • software installers that install privileged tools or require access to restricted areas of the operating system

A companion volume to Authorization Services C Reference is Authorization Services Programming Guide, which explains the concepts behind authorization and provides examples of how to use Authorization Services. Objective-C methods that are equivalent to several of the functions in this document are described in SecurityFoundation.

Authorization Services is available in macOS 10.0 and later as part of the Security framework.

Symbols

Creating and Releasing Authorization References

func AuthorizationFree(AuthorizationRef, AuthorizationFlags)

Frees the memory associated with an authorization reference.

Externalizing and Internalizing Authorization References

Data Types

AuthorizationEnvironment

Represents a set of data about the environment, such as user name and other information gathered during evaluation of authorization.

AuthorizationFlags

Represents a bit mask of authorization options.

AuthorizationItem

Contains information about an authorization right or the authorization environment.

AuthorizationItemSet

Represents a set of authorization items.

AuthorizationRef

Represents a pointer to an opaque authorization reference structure.

AuthorizationRights

Represents a set of authorization rights.

AuthorizationString

Represents a zero-terminated string in UTF-8 encoding.

Constants

Authorization Options

Define valid authorization options.

Authorization Rights Mask

Defines values the Security Server sets in an authorization item’s flag field.

Name Tags

Specify the type of environment data or right.

Policy Database Constants

Defines constants for use in setting rights and rules in the policy database.

Result Codes

The most common result codes returned by the Security Server are listed in the table below.

var errAuthorizationSuccess: OSStatus

The operation completed successfully.

var errAuthorizationInvalidSet: OSStatus

The set parameter is invalid.

var errAuthorizationInvalidRef: OSStatus

The authorization parameter is invalid.

var errAuthorizationInvalidTag: OSStatus

The tag parameter is invalid.

var errAuthorizationInvalidPointer: OSStatus

The authorizedRights parameter is invalid.

var errAuthorizationDenied: OSStatus

The Security Server denied authorization for one or more requested rights. This error is also returned if there was no definition found in the policy database, or a definition could not be created.

var errAuthorizationCanceled: OSStatus

The user canceled the operation.

var errAuthorizationInteractionNotAllowed: OSStatus

The Security Server denied authorization because no user interaction is allowed.

var errAuthorizationInternal: OSStatus

An unrecognized internal error occurred.

var errAuthorizationExternalizeNotAllowed: OSStatus

The Security Server denied externalization of the authorization reference.

var errAuthorizationInternalizeNotAllowed: OSStatus

The Security Server denied internalization of the authorization reference.

var errAuthorizationInvalidFlags: OSStatus

The flags parameter is invalid.

var errAuthorizationToolEnvironmentError: OSStatus

The attempt to execute the tool failed to return a success or an error code.