---

Scenarios

There are three main scenarios that involve Authorization Services: simple self-restricted applications, factored applications, and installers.

In this section:

Simple, Self-Restricted Applications
Factored Applications
Installers

Simple, Self-Restricted Applications

A self-restricted application requires that certain features be accessible only by a specific group of users. In a simple self-restricted application, this separation of features is done within the main application. You use Authorization Services in this situation because this kind of fine-grain restriction cannot be controlled by BSD permissions.

Consider a grades-and-transcripts application that allows only registrars to create transcripts, while the rest of the application is available to both teachers and registrars. When a user attempts to create a transcript, the application uses Authorization Services to decide if that user may perform the operation.

Figure 1-4 shows a flow chart of a simple, self-restricting application. The application creates an authorization reference. The authorization reference refers to the authorization session with the Security Server. Immediately before performing any privileged operation, such as creating a transcript, the application requests authorization on behalf of the user. If required, the Security Server requests authentication of the user. If authorization succeeds, the privileged operation is performed. The application releases the authorization reference when it is no longer needed.

In most cases, it is beneficial to separate the privileged operations into a separate helper tool. See “Factored Applications” for more information on how to use Authorization Services with helper tools.

You can perform authorization without creating an authorization reference if you need to authorize just once—for example, when your application first starts up. To do so you use the result of the authorization call directly. Because in this case you did not create an authorization reference, you don’t have to release it. One-time authorization is described in more detail in the section “Authorizing.”

Factored Applications

A factored application is an application that delegates specific tasks to smaller, separate tools. These tools are sometimes referred to as helper tools. In a simple, self-restricted application, the privileged code is in the application itself, whereas in a factored application, the privileged code is in the helper tool.

An operation that your application performs might be restricted by the BSD security model. Such an application is a system-restricted application. For example, an application that requires restarting the Internet daemon (inetd) must have root privileges, but it runs with the privileges of the user that started it.

It is recommended that you factor both self-restricted applications and system-restricted applications. Factoring your application provides two benefits. The first is that it is easier to audit a factored application because the privileged operation is performed in a separate process by the helper tool. The second is that a factored application provides more security. In a nonfactored application, you not only have to trust that there are no security holes in your code but also no holes in all of the code that you link to.

Figure 1-5 shows a flow chart for the application part of a factored application while the flow chart for the helper tool is shown in Figure 1-6.

The application begins by creating an authorization reference and requesting preauthorization from the Security Server immediately before calling the helper tool. The application uses the results of preauthorization to determine if the user has the right to perform the privileged operations in the helper tool. Performing preauthorization ensures that resources and time aren’t wasted invoking a helper tool that the user does not have the right to use.

The application needs to pass the authorization reference to the helper tool. Because you cannot transfer an authorization reference itself between two processes, the application uses Authorization Services to create an external, transferable form of the authorization reference to send to its helper tool.

The helper tool uses Authorization Services to create an authorization reference from the external authorization reference. The helper tool requests authorization and uses the results to decide whether to continue with the privileged operation.

You must pass the authorization reference to your helper tool so that the authorization dialog can show your application’s path rather than the path to the helper tool and to allow the system to determine whether the authorization dialog should have keyboard focus.

You must perform authorization immediately before any privileged operation, even if the user has already successfully authorized. Rights can expire, thus it is your responsibility as a developer to ensure that the user is up to date on all required rights. Any application can modify the policy database to set the length of time a right is available (see “The Policy Database”).

Some system-supplied utilities use Authorization Services. For example, the authopen utility uses Authorization Services to open privileged files. If you call a utility like authopen, then it is unnecessary to write your own helper tool.

Some privileged operations require special permissions. For example, an application that restarts the Internet daemon must have root privileges. There are three possible ways to perform this operation, all with their own problems:

• Make the application run as root by calling itself with a special Authorization Services function.

• Set the setuid bit of the application and change its owner to root, and then use the special Authorization Services function.

• Factor out the operation that performs the privileged operation and put it in a separate setuid tool—a tool that has its setuid bit set—and set the setuid tool’s owner to root.

Both the first and second options are a security breach waiting to happen. When the privileged application runs, it calls a special function that Authorization Services provides—AuthorizationExecuteWithPrivileges (see “Calling a Helper Tool as Root” for more details). Calling this function executes any application or tool with root privileges, regardless of the owner of the application or tool. This is very dangerous since parts of the application can be easily replaced.

The second option is to set the setuid bit of the privileged application and change its owner to root. The setuid bit, when set, allows the process running it to masquerade as another user. Setting the setuid bit and owner of the application to a different user, such as root, makes it more difficult to replace. However, running code as root is very dangerous and should be done as seldom as possible. Setting the setuid bit on an entire application is especially dangerous because you are trusting that your entire application, and the code your application links to, is free of security holes.

The third scenario is by far the best. The application is split into an application that controls all of the graphical user interface elements and nonprivileged operations, and a helper tool that performs only the operations involved in restarting the Internet daemon. The helper tool’s setuid bit is set and the owner is set to root. The proper Authorization Services functions are used as described previously. Factoring and setting the setuid bit not only minimizes the risk but also makes it easier to audit your code for security holes.

One problem with the last scenario is that setuid bit settings are lost when a file is copied. Thus, if the user copies your setuid tool, the setuid bit is no longer set. It is possible to reset the setuid bit in the setuid tool itself. Figure 1-7 shows the flow chart of a setuid tool that repairs its own setuid bit. You may not want the user to be able to copy the application. If that is the case, you don’t need to worry about repairing the setuid bit, just let the user know that they need to reinstall the application.

When the self-repairing helper tool is run, it checks if the self-repair flag was passed. If the self-repair flag was not passed, then it reads in the external authorization reference that the application passed.

The self-repairing setuid tool then checks if it is running as root. If it is running as root, then authorization is performed and, based on the result, the privileged operation is performed. If the self-repairing setuid tool is not running as root, then it calls itself with the AuthorizationExecuteWithPrivileges function and passes itself the self-repair flag.

When the new self-repairing setuid tool process starts, it checks if the self-repair flag was passed. If the self-repair flag was passed, then the self-repairing setuid tool recovers the authorization reference and repairs the setuid bit. After the self-repairing setuid tool is running as root, it performs authorization and continues as a normal helper tool.

Installers

Not all installers require authorization—only those that need special privileges to copy files to restricted directories, make changes to restricted files, or set setuid bits.

An installer is a special case because unlike other applications, an installer is usually run only once. Due to the limited use, Authorization Services provides a function to invoke your installer to run with root privileges. It is up to the user to determine if the installer is from a trusted source.

Figure 1-8 shows a flow chart of an application using Authorization Services to call an installer. In this case, the application creates the authorization reference and performs preauthorization. If the user successfully preauthorizes, then you call the AuthorizationExecuteWithPrivileges function to execute your installer with root privileges.

Figure 1-9 shows a flow chart for the Authorization Services calls performed in the installer itself. Authorization should be performed before any privileged operation.

---