openSolaris 2008 - Java Bindings - Solaris Trusted Extensions Developer's Guide

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 and the getdevicerange(3TSOL) man page.

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) and getdevicerange(3TSOL) man pages.

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 creating multilevel printer banner pages. 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 the caveats section of the banner page.