get_peer_label() Label-Aware Function

The get_peer_label() function in the lp/lib/lp/tx.c file implements the logic of multilevel printing in Trusted Extensions. The following sections describe this function and step you through its implementation.

In Trusted Extensions software, much of the logic for handling labels in the printing service is in the get_peer_label() function. This function obtains the credential of the remote process in a ucred_t data structure and extracts the label from the credential.

The following shows the get_peer_label() code.

int
get_peer_label(int fd, char **slabel)
{
    if (is_system_labeled()) {
        ucred_t *uc = NULL;
        m_label_t *sl;
        char *pslabel = NULL; /* peer's slabel */

        if ((fd < 0) || (slabel == NULL)) {
            errno = EINVAL;
            return (-1);
        }
    
        if (getpeerucred(fd, &uc) == -1)
            return (-1);
    
        sl = ucred_getlabel(uc);
        if (label_to_str(sl, &pslabel, M_INTERNAL, DEF_NAMES) != 0)
            syslog(LOG_WARNING, "label_to_str(): %m");
        ucred_free(uc);
    
        if (pslabel != NULL) {
            syslog(LOG_DEBUG, "get_peer_label(%d, %s): becomes %s",
                fd, (*slabel ? *slabel : "NULL"), pslabel);
            if (*slabel != NULL)
                free(*slabel);
            *slabel = strdup(pslabel);
        }
    }
    
    return (0);
}

Determining Whether the Printing Service Is Running in a Labeled Environment

The printing service is designed to work in labeled and unlabeled environments. Therefore, the printing application must determine when the label of a remote host should be requested and whether the label should be applied. The printing process first checks its own environment. Is the process running in a label-aware environment?

Note that the application does not first determine whether the remote request is labeled. Instead, the printing application determines if its own environment is labeled. If the application is not running on a labeled host, the MAC policy prevents the printing application from receiving labeled requests.

The printing service uses the is_system_labeled() function to determine whether the process is running in a labeled environment. For information about this function, see the is_system_labeled(3C) man page.

This code excerpt shows how to determine whether the application is running in a labeled environment:

if (is_system_labeled()) {
    ucred_t *uc = NULL;
    m_label_t *sl;
    char *pslabel = NULL; /* peer's slabel */

    if ((fd < 0) || (slabel == NULL)) {
        errno = EINVAL;
        return (-1);
    }

If the printing adapter process is running on a system configured with Trusted Extensions, the is_system_labeled() function obtains the ucred_t credential abstraction from the remote process. The ucred_t data structure for the remote process and the peer's label are then set to NULL. The functions that return values for the credential and the peer's label fill the data structures. These data structures are discussed in the following sections.

See get_peer_label() Label-Aware Function to view the source of the entire get_peer_label() routine.

Understanding the Remote Host Credential

The Oracle Solaris OS network API provides an abstraction of a process's credentials. This credentials data is available through a network connection. The credentials are represented by the ucred_t data structure. This structure can include the label of a process.

The ucred API provides functions for obtaining the ucred_t data structure from a remote process. This API also provides functions for extracting the label from the ucred_t data structure.

Obtaining the Credential and Remote Host Label

Obtaining the label of a remote process is a two-step procedure. First, you must obtain the credential. Then, you must obtain the label from this credential.

The credential is in the ucred_t data structure of the remote process. The label is in the m_label_t data structure in the credential. After obtaining the credential of the remote process, you extract the label information from that credential.

The getpeerucred() function obtains the ucred_t credential data structure from the remote process. The ucred_getlabel() function extracts the label from the ucred_t data structure. In the get_peer_label() function, the two-step procedure is coded as follows:

if (getpeerucred(fd, &uc) == -1)
    return (-1);

sl = ucred_getlabel(uc);

See get_peer_label() Label-Aware Function to view the source of the entire get_peer_label() routine.

For information about the two functions, see the getpeerucred(3C) and ucred_getlabel(3C) man pages.

In addition to obtaining a remote host's label, you can obtain a remote host's type. To obtain the remote host type, use the tsol_getrhtype() routine. See Obtaining the Remote Host Type.

Using the label_to_str() Function

After obtaining the credential and remote host label, an application can call label_to_str() to convert the label data structure into a string. The string form of the label data structure can be used by the application.

Note that in the Trusted Extensions printing service, the label is returned as a string. The get_peer_label() function returns the string that is obtained by calling label_to_str() on the m_label_t data structure. This string value is returned in the slabel parameter of the get_peer_label() function, char** slabel.

The following code excerpt shows how the label_to_str() function is used:

sl = ucred_getlabel(uc);
if (label_to_str(sl, &pslabel, M_INTERNAL, DEF_NAMES) != 0)
    syslog(LOG_WARNING, "label_to_str(): %m");
ucred_free(uc);

if (pslabel != NULL) {
    syslog(LOG_DEBUG, "get_peer_label(%d, %s): becomes %s",
        fd, (*slabel ? *slabel : "NULL"), pslabel);
    if (*slabel != NULL)
        free(*slabel);
    *slabel = strdup(pslabel);
}

See get_peer_label() Label-Aware Function to view the source of the entire get_peer_label() routine.

Handling Memory Management

As shown in get_peer_label() Label-Aware Function, labels are often dynamically allocated. The functions str_to_label(), label_to_str(), getdevicerange(), and other functions allocate memory that must be freed by the caller. The following man pages for these functions describe the memory allocation requirements:

• label_to_str(3TSOL)

• m_label(3TSOL)

• str_to_label(3TSOL)

Using the Returned Label String

The get_peer_label() function extracts the label from a remote host and returns that label as a string. The printing application, as is typical of label-aware applications, uses the label for the following purposes:

• To make sure that information associated with a label is clearly marked with the correct label. The banner and trailer pages, as well as the header and footer, are marked with the label of the document being printed.

• To validate that the label of a resource permits a given operation to be performed by another labeled resource. That is, the label of the requesting process permits this printer to accept a request from that requesting process. This permission is based on the range of labels that this printer is assigned.