Deprecated Authorization Services Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.7

AuthorizationCopyPrivilegedReference

Retrieves the authorization reference passed by the AuthorizationExecuteWithPrivileges function. (Deprecated in OS X v10.7.)

OSStatus AuthorizationCopyPrivilegedReference (
   AuthorizationRef *authorization,
   AuthorizationFlags flags
);
Parameters
authorization

A pointer to an authorization reference. The Security Server allocates the authorization reference for you, so you do not need to call the function AuthorizationCreate. On return, it points to a copy of the authorization reference used in the call to the AuthorizationExecuteWithPrivileges function.

flags

Reserved options. Pass the kAuthorizationFlagDefaults constant.

Return Value

A result code. See “Authorization Services Result Codes.”

Discussion

This function retrieves the authorization reference you pass in the function AuthorizationExecuteWithPrivileges. The new process can use the authorization reference to verify authorizations obtained by the calling process.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
Authorization.h

AuthorizationExecuteWithPrivileges

Runs an executable tool with root privileges. (Deprecated in OS X v10.7.)

OSStatus AuthorizationExecuteWithPrivileges (
   AuthorizationRef authorization,
   const char *pathToTool,
   AuthorizationFlags options,
   char *const *arguments,
   FILE **communicationsPipe
);
Parameters
authorization

An authorization reference referring to the authorization session.

pathToTool

The full POSIX pathname of the tool to execute.

options

Reserved options. Pass the kAuthorizationFlagDefaults constant.

arguments

An argv-style vector of strings (array of null-terminated char * pointers ending with a NULL pointer) to send to the tool. (You do not need to pass the name of the command as the first argument.)

communicationsPipe

A pointer to a file structure. The Security Server creates the file, opens it for reading and writing, and connects it to the tool’s standard input and output. On return, you must close and dispose of this file using fclose when your communication is complete. Pass NULL if you do not need a communications channel.

Return Value

A result code. See “Authorization Services Result Codes.”

Discussion

This function enables you to execute the tool you specify in the pathToTool parameter as a separate, privileged process. The new process will run with root privileges regardless of the privileges of the invoking process. The new process can retrieve the authorization reference by calling the function AuthorizationCopyPrivilegedReference. The arguments you pass in the arguments parameter are relayed to the new process’s argv parameter. A set of file descriptors is linked to the new process’s standard input and output so that your process may communicate with the new process.

To check if the user is authorized to perform this operation, you should preauthorize the kAuthorizationRightExecute right. See AuthorizationItem for a description of what information is included in the authorization item for this right.

Special Considerations

You should use this function only to allow installers to run as root and to allow a setuid tool to repair its setuid bit if lost. This function works only if the Security Server establishes proper authorization.

This function poses a security concern because it will indiscriminately run any tool or application, severely increasing the security risk. You should avoid the use of this function if possible. One alternative is to split your code into two parts—the application and a setuid tool. The application invokes the setuid tool using standard methods. The setuid tool can then perform the privileged operations. If the tool loses its setuid bit, use the AuthorizationExecuteWithPrivileges function to repair it. Factoring your program minimizes the use of this function and reduces the risk of harm. Read Inside OS X: Performing Privileged Operations With Authorization Services.

Note that this function respects the setuid bit, if it is set. That is, if the tool you are executing has its setuid bit set and its owner set to foo, the tool will be executed with the user foo’s privileges, not root privileges. To ensure that your call to the AuthorizationExecuteWithPrivileges function works as intended, make sure the setuid bit of the tool you wish to execute is cleared before calling AuthorizationExecuteWithPrivileges to execute the tool.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
Authorization.h