Java Bindings

The Java implementation of the Trusted Extensions label APIs is intended to be used to create label-aware applications. As a result, not all of the label APIs provided by Trusted Extensions are part of the Java implementation.

The Java classes and methods that are presented in this chapter mimic the following general label functionality shown in Label APIs:

• Detecting a Trusted Extensions system

• Accessing the process sensitivity label

• Allocating and freeing memory for label objects

• Obtaining and setting the label of a file

• Obtaining label range objects

• Accessing labels in zones

• Obtaining the remote host type

• Translating between labels and strings

• Comparing label objects

Detecting a Trusted Extensions System

These Java bindings do not include methods to determine whether a system is labeled. Rather, the library will fail to load if Trusted Extensions is not enabled.

Accessing the Process Sensitivity Label

These Java bindings do not include methods to obtain the label of a process. In Trusted Extensions, a process that runs in a labeled zone has the same label as the zone.

Allocating and Freeing Memory for Label Objects

These Java bindings take advantage of the Java “garbage-collection” functionality. As a result, you do not need to explicitly free the memory used by label objects as you do for the label APIs described in Obtaining and Setting the Label of a File.

Obtaining and Setting the Label of a File

These Java bindings use the Java File object to obtain and set file labels. Use the getFileLabel static factory to obtain the label from the file's File object. To set a file label to another specified label, use the setFileLabel method on the file's File object.

In addition to obtaining the sensitivity label of a file, the getSocketPeer static factory enables you to obtain the sensitivity label for the peer endpoint of a socket.

The getFileLabel static factory and the setFileLabel method correspond to the getlabel() system call and the setflabel() routine, respectively. For more information, see Obtaining and Setting the Label of a File and the getlabel(2) and setflabel(3TSOL) man pages.

The following descriptions include the prototype declarations for the static factories and the method:

public static SensitivityLabel getFileLabel(java.io.File file)

The getFileLabel static factory obtains the label of a Java File object that is specified by file.

public static SensitivityLabel getSocketPeer(java.net.Socket socket)

The getSocketPeer static factory obtains a sensitivity label object from the specified socket, socket.

The following code fragment obtains the sensitivity label object of the socket, s:

SensitivityLabel sl = SolarisLabel.getSocketPeer(s);

The following example code shows how to create a server socket on port 9090 and then obtain the sensitivity label of the peer end of the accepted connection. This code example also outputs the internal and human-readable forms, the color, and the root path of the obtained socket peer label.

import java.io.*;
import java.net.*;
import solarismac.*;

public class ServerSocketTest
{

    public static void main (String args[]) {

        System.out.println("ServerSocketTest Start");

        CreateListner();

        System.out.println("ServerSocketTest End");

    }

    /*
     * Listen for connections on port then print the peer connection label.
     * You can use telnet host 9090 to create a client connection.
     */
    private static void CreateListner() {
        int port = 9090;

        ServerSocket acceptSocket;
        Socket s;
        try {
            System.out.println("Creating ServerSocket on port " + port);

            acceptSocket = new ServerSocket(port);

            System.out.println("ServerSocket created, waiting for connection");

            s = acceptSocket.accept();

            /*
             * Get the Sensitivity Label for the peer end of the socket.
             */
            SensitivityLabel socksl = SolarisLabel.getSocketPeer(s);

            System.out.println("Client connected...");
            System.out.println(" toInternal: " + socksl.toInternal());
            System.out.println(" toText: " + socksl.toText());
            System.out.println(" toString: " + socksl.toString());
            System.out.println(" toColor: " + socksl.toColor());
            System.out.println(" toRootPath: " + socksl.toRootPath());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

public static void setFileLabel(java.io.File file, SensitivityLabel label)

The setFileLabel method changes the sensitivity label of the specified file to the specified label. When the sensitivity label of a file changes, the file is moved to the zone that corresponds to the new label. The file is moved to a new path name that is relative to the root of the other zone.

For example, if you use the setFileLabel method to change the label of the file /zone/internal/documents/designdoc.odt from INTERNAL to RESTRICTED, the new path of the file will be /zone/restricted/documents/designdoc.odt. Note that if the destination directory does not exist, the file is not moved.

The following code fragment shows how you might change the label of the file:

SolarisLabel.setFileLabel(new File("/zone/internal/documents/designdoc.odt"),
    SolarisLabel.getSensitivityLabel("RESTRICTED"));

When you change the sensitivity label of a file, the original file is deleted. The only exception occurs when the source and destination file systems are loopback-mounted from the same underlying file system. In this case, the file is renamed.

The Java virtual machine must be running with the appropriate privilege (file_upgrade_sl or file_downgrade_sl) to relabel a file.

For more information about setting privileges, see Developing Privileged Applications, in Solaris Security for Developers Guide. See also the setflabel(3TSOL) man page.

Obtaining Label Range Objects

The getLabelRange static factory creates a label range object. The getUserRange and getDeviceRange static factories obtain label range objects for a user and a device, respectively. The getUpper and getLower methods are used to obtain the upper and lower labels of the range, respectively. In addition, the inRange method determines whether the specified label is in a range. For more information about the inRange method, see Comparing Label Objects.

The getUserRange and getDeviceRange static factories correspond to the getuserrange() and getdevicerange() routines. For more information, see Obtaining Label Ranges.

The following constructor and method descriptions include the prototype declaration for each constructor:

public static Range getDeviceRange(java.lang.String device)

The getDeviceRange static factory obtains the label range of a user-allocatable device. If no label range is specified for the device, the default range has an upper bound of ADMIN_HIGH and a lower bound of ADMIN_LOW.

You can use the list_devices command to show the label range for a device. See the list_devices(1) man page.

public static <L extends SolarisLabel,U extends SolarisLabel> Range getLabelRange(L lower, U upper)

The getLabelRange static factory creates a label range. The static factory takes the lower bound value in the range and the upper bound, or clearance, as parameters. An exception is thrown if upper does not dominate lower.

public L getLower()

The getLower method returns the lower portion of the range.

public U getUpper()

The getUpper method returns the upper portion of the range.

public static Range getUserRange(java.lang.String user)

The getUserRange static factory obtains the label range of the specified user. The lower bound in the range is used as the initial workspace label when a user logs in to a multilevel desktop. The upper bound, or clearance, is used as an upper limit to the available labels that a user can assign to labeled workspaces.

The default value for a user's label range is specified in the label_encodings file. The value can be overridden by the user_attr file.

For more information, see the getuserrange(3TSOL) man page.

Accessing Labels in Zones

The following description includes the prototype declaration for the method:

public final java.lang.String toRootPath()

This method returns the root path name of the zone for the specified sensitivity label.

The following code excerpt shows how to obtain the root path for the PUBLIC sensitivity label:

SensitivityLabel sl = SolarisLabel.getSensitivityLabel("PUBLIC");
System.out.println("toRootPath: " + sl.toRootPath();

This method throws a java.io.IOException if an invalid label is specified or if no zone is configured for the specified label.

This method mimics the getzonerootbylabel() routine. See the getzonerootbylabel(3TSOL) man page. See also Accessing Labels in Zones.

Obtaining the Remote Host Type

The Java implementation of the Trusted Extensions label APIs does not include interfaces for obtaining the remote host type.

Translating Between Labels and Strings

The SolarisLabel abstract class includes methods for translating between labels and strings, which are inherited by its subclasses.

These methods translate the internal representation of a label (m_label_t) to String objects.

You can use the toInternal method to translate a label into a string that hides the classification name. This format is suitable for storing labels in public objects.

The running Java virtual machine must dominate the label to be translated, or it must have the sys_trans_label privilege. See the label_to_str(3TSOL) man page.

Some of the label values are based on data in the label_encodings file.

The following methods mimic the label_to_str() routine. See the label_to_str(3TSOL) man page.

public final java.lang.String toColor()

This method returns the color of the SolarisLabel object. The value is suitable for use by HTML.

public final java.lang.String toInternal()

This method returns the internal representation of the label that is safe for storing in a public object. An internal conversion can later be parsed to its same value. This is the same as using the toString method.

These two methods differ in the way that they handle errors. If the toInternal method encounters an error, it returns a java.io.IOException. However, if the toString method encounters an error, it returns a null.

public java.lang.String toString()

This method returns the internal hexadecimal version of the label in string form, which is the same as using the toInternal method.

These two methods differ in the way that they handle errors. If the toString method encounters an error, it returns a null. However, if the toInternal method encounters an error, it returns a java.io.IOException.

public java.lang.String toText()

This method returns a human-readable text string of the SolarisLabel object.

public java.lang.String toTextLong()

This method returns the long human-readable text string of the SolarisLabel object.

public java.lang.String toTextShort()

This method returns the short human-readable text string of the SolarisLabel object.

The following methods perform label translations that are suitable for output. These methods mimic some of the functionality of the label_to_str() routine. See the label_to_str(3TSOL) and m_label(3TSOL) man pages.

public java.lang.String toCaveats()

This method returns a human-readable text string that is suitable for output.

This method is only available for SensitivityLabel objects, not for ClearanceLabel objects.

public java.lang.String toChannels()

This method returns a human-readable text string that is suitable for output.

This method is only available for SensitivityLabel objects, not for ClearanceLabel objects.

public java.lang.String toFooter()

This method returns a human-readable text string that is appropriate for use as the sensitivity label.

This method is only available for SensitivityLabel objects, not for ClearanceLabel objects.

public java.lang.String toHeader()

This method returns a human-readable text string that is appropriate for use as the sensitivity label.

This method is only available for SensitivityLabel objects, not for ClearanceLabel objects.

public java.lang.String toProtectAs()

This method returns a human-readable text string that is suitable for output.

This method is only available for SensitivityLabel objects, not for ClearanceLabel objects.

Methods such as toText, toInternal, and toColor do not translate from a string to a label. To translate a string to a sensitivity label or to a clearance label, you must call the getSensitivityLabel or getClearanceLabel static factories, respectively. The following static factories mimic the str_to_label() routine. See the str_to_label(3TSOL) and m_label(3TSOL) man pages.

public static ClearanceLabel getClearanceLabel(java.lang.String label)

This static factory creates a clearance label from the specified string. The following examples create new clearance labels based on a label name and the internal hexadecimal name of a label:

ClearanceLabel cl = SolarisLabel.getClearanceLabel("PUBLIC");
ClearanceLabel cl = SolarisLabel.getClearanceLabel("0x0002-08-08");

public static SensitivityLabel getSensitivityLabel(java.lang.String label)

This static factory creates a sensitivity label from the specified string. The following examples create new sensitivity labels based on a label name and the internal hexadecimal name of a label:

SensitivityLabel sl = SolarisLabel.getSensitivityLabel("PUBLIC");
SensitivityLabel sl = SolarisLabel.getSensitivityLabel("0x0002-08-08");

Comparing Label Objects

The following equals, dominates, and strictlyDominates methods are used to compare labels, and correspond to the blequal(), bldominate(), and blstrictdom() routines. The inRange method is used to determine whether a label is within a specified label range, and corresponds to the blinrange() routine. In these methods, a label refers to a classification and a set of compartments in a sensitivity label or in a clearance label. For more information, see Comparing Labels and the blcompare(3TSOL) man page.

public boolean dominates(SolarisLabel label)

The dominates method compares two labels to determine whether one label dominates the other.

The following example code shows how you can make the comparison. The CNF : INTERNAL label is being compared to check its dominance over the PUBLIC label.

SensitivityLabel sl = SolarisLabel.getSensitivityLabel("CNF : INTERNAL");
boolean isDominant = sl.dominates(SolarisLabel.getSensitivityLabel("PUBLIC"));

public boolean equals(java.lang.Object obj)

The equals method compares two labels to determine whether they are equal.

The following example code shows how you can make the comparison:

SensitivityLabel sl = SolarisLabel.getSensitivityLabel("CNF : INTERNAL");
boolean isSame = sl.equals(SolarisLabel.getSensitivityLabel("PUBLIC"));

public boolean Range inRange(SensitivityLabel label)

The inRange method determines whether the specified label is within the range. This method belongs to the Range class.

The following code fragment shows how you can verify that a file is within a user's clearance range:

import solarismac.*;
import java.io.*;

public class Example1
{
    public static void main (String args[]) {

        try {
        Range range;

            range = Range.getUserRange("jweeks");
            SensitivityLabel fsl =
                SolarisLabel.getFileLabel(new File("/etc/passwd"));
            boolean isInRange;

            isInRange = Range.inRange(fsl);

            if (isInRange)
                System.out.println("File is within user's range");
            else
                System.out.println("File is not within user's range");

        }
        catch (Exception e) {
            e.PrintStackTrace();
        }
    }
}

public boolean strictlyDominates(SolarisLabel label)

The strictlyDominates method compares two labels to determine whether one label strictly dominates the other. When a label strictly dominates another, it dominates the other label, but is not equal to the other label.

The following example code shows how you can make the comparison. The CNF : INTERNAL label is being compared to check its strict dominance over the PUBLIC label.

SensitivityLabel sl = SolarisLabel.getSensitivityLabel("CNF : INTERNAL");
boolean isStrictlyDominant =
    sl.strictlyDominates(SolarisLabel.getSensitivityLabel("PUBLIC"));

For more information about label relationships, see Label Relationships.

The getMaximum and getMinimum methods are used to determine the least upper bound and the greatest lower bound of the specified label range, respectively. These methods mirror the functionality of the blmaximum() and blminimum() routines. For more information, see Comparing Labels and the blminmax(3TSOL) man page.

For instance, use the getMaximum method to determine the label to use when creating a new labeled object that combines information from two other labeled objects. The label of the new object will dominate both of the original labeled objects. Each method is defined by the ClearanceLabel and SensitivityLabel subclasses.

public ClearanceLabel getMaximum(ClearanceLabel bounding)

The getMaximum method creates a new clearance label object that is the lowest label that can dominate two label objects you specify. The resulting object is the least upper bound of the range. getMaximum returns an object in the internal form of the clearance label.

public ClearanceLabel getMinimum(ClearanceLabel bounding)

The getMinimum method creates a new clearance label object that is the highest label that is dominated by two labels you specify. The resulting object is the greatest lower bound of the range. getMinimum returns an object in the internal form of the clearance label.

public SensitivityLabel getMaximum(SensitivityLabel bounding)

The getMaximum method creates a new sensitivity label object that is the lowest label that can dominate two label objects you specify. The resulting object is the least upper bound of the range. getMaximum returns an object in the internal form of the sensitivity label.

public SensitivityLabel getMinimum(SensitivityLabel bounding)

The getMinimum method creates a new sensitivity label object that is the highest label that is dominated by two labels you specify. The resulting object is the greatest lower bound of the range. getMinimum returns an object in the internal form of the sensitivity label.

The following table shows label input and output from the getMaximum and getMinimum methods.

Table 8-1 Using the getMinimum and getMaximum Methods