This chapter describes an experimental set of Java classes and methods that mirror the label application programming interfaces (APIs) that are provided with the Solaris Trusted Extensions software. The Java implementation of the Trusted Extensions label APIs is intended to be used to create label-aware applications. As a result, all of the label APIs provided by Trusted Extensions are not part of the Java implementation.The presentation of these experimental Java APIs (Java bindings) demonstrate how the Solaris Trusted Extensions features can be expanded into the Java development environment.These experimental Java bindings are not a supported part of the Solaris Trusted Extensions software. This chapter covers the following topics:Java Bindings Overview Structure of the Experimental Java Label Interfaces Java Bindings The Java language is an untapped resource for creating label-aware applications that run in secure, multilevel arenas. These experimental Java bindings provide a foundation on which to develop more applications, such as system audit log generation and system resource controls.Adding platform services to the Java environment will enable Java applications to handle sensitive multilevel data.Solaris Trusted Extensions provides label services through the label daemon, labeld. This daemon is available to processes that run in the global zone and in labeled zones.The Java bindings described in this chapter are Java Native Interface (JNI) implementations of some of the Solaris Trusted Extensions label APIs. The experimental JNI code calls the Solaris Trusted Extensions label library functions to extend some of the label functionality to the Java language. Constructors and methods in these Java classes call private JNI interfaces, written in C, that in turn call the Trusted Extensions APIs. For example, the SolarisLabel.dominates method calls a private JNI interface written in C that calls the bldominates routine. These experimental Java bindings have been developed using Java 2 Platform, Standard Edition 5.0. For more information about JNI, see Java Native Interface Documentation.You can download this experimental code from the Solaris Trusted Extensions project page of the OpenSolaris web site. Java bindingsclasses The JNI implementation of the Trusted Extensions label APIs introduces several label-related classes that relate to each other in this way:SolarisLabel abstract classClearanceLabel subclass SensitivityLabel subclass Range class SolarisLabel abstract classdescription of Java bindingsSolarisLabel abstract class The SolarisLabel abstract class provides the foundation for common and native methods related to Solaris Trusted Extensions labels. The SensitivityLabel and ClearanceLabel subclasses inherit members from this abstract class. Static factories for creating sensitivity labels and clearance labels are also provided by the abstract class.Static factories and methods throw exceptions when errors are encountered to ensure that no mandatory access control-related errors occur silently.SolarisLabel abstract classmethods and static factoriesThis abstract class defines the following general-purpose methods that are used to compare labels and to translate labels to strings:dominates equals setFileLabel strictlyDominates toColor toInternal toRootPath toString toText toTextLong toTextShort The equals, dominates, and strictlyDominates methods are analogous to the blequal, bldominates, and blstrictdom label APIs currently available with Solaris Trusted Extensions. The setFileLabel method is analogous to the setflabel routine currently available with Solaris Trusted Extensions.The rest of the methods (such as toText, toInternal, and toColor) are related in function to the label_to_str routine that is currently available with Solaris Trusted Extensions. These methods enable you to translate a label to a particular type of string. Depending on the label relationship of the process and the object, you might need privileges in your effective set to translate a label to a human-readable form. For instance, the Java Virtual Machine (JVM) process must be running with the sys_trans_label privilege to translate labels that it does not dominate.The SolarisLabel abstract class also includes the following static factories:getClearanceLabel getFileLabel getSensitivityLabel getSocketPeer The string that you pass as a label to getSensitivityLabel or getClearanceLabel can be in one of the following forms:Human-readable form of the label, such as PUBLIC Internal form of the label, such as 0x0002-08-08 Only the internal form of the label is suitable for storage and for transmission over a network connection, as the internal form does not reveal the actual label. For more information, see Readable Versions of Labels.The ClearanceLabel and SensitivityLabel subclasses extend the SolarisLabel abstract class. These subclasses each inherit the common methods provided by the SolarisLabel abstract class.ClearanceLabel subclass Java bindingsClearanceLabel subclass The ClearanceLabel subclass extends the SolarisLabel abstract class and defines the getMaximum and getMinimum methods, which return the ClearanceLabel object that represents the least upper bound and the greatest lower bound, respectively. SensitivityLabel subclassdescription of Java bindingsSensitivityLabel subclass The SensitivityLabel subclass extends the SolarisLabel abstract class and defines the getMaximum and getMinimum methods, which return the SensitivityLabel object that represents the least upper bound and the greatest lower bound, respectively.SensitivityLabel subclassmethodsThe SensitivityLabel subclass introduces the following methods that provide information suitable for labeled printer banner pages:toCaveats toChannels toFooter toHeader toProtectAs Range classdescription of Java bindingsRange class The Range class represents a Java version of a Solaris Trusted Extensions label range.Range classmethods and static factoriesThis class defines the following general-purpose methods that are used to obtain the upper and lower labels in a label range and to determine whether a label is within a specified label range:getLower getUpper inRange The Range class also includes the following static factories that create range objects:getDeviceRange getLabelRange getUserRange The getDeviceRange and getUserRange static factories create range objects based on the range for the specified device and the specified user, respectively. The getLabelRange static factory enables you to create a label range where you specify the upper and lower bounds for the range. 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 Trusted Extensions system, detecting 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. 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. 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. getFileLabel static factorydeclaration Java static factoriesgetFileLabel getSocketPeer static factorydeclaration Java static factoriesgetSocketPeer setFileLabel methoddeclaration Java methodssetFileLabel 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 getlabel2 and setflabel3TSOL man pages.The following descriptions include the prototype declarations for the static factories and the method:public static SensitivityLabel getFileLabel(java.io.File file)Java static factoriesgetFileLabelgetFileLabel static factorydeclarationThe 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);code examplesobtain socket peer labelcode examplesgetSocketPeer static factoryobtaining socket peer labelgetSocketPeer static factorycode exampleThe 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)labelsobjectsThe 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 setflabel3TSOL man page. getUserRange static factorydeclaration getDeviceRange static factorydeclaration getLabelRange static factorydeclaration Java static factoriesgetUserRange Java static factoriesgetDeviceRange Java static factoriesgetLabelRange getUpper methoddeclaration getLower methoddeclaration Java methodsgetUpper Java methodsgetLower 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 getdevicerange3TSOL 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_devices1 and getdevicerange3TSOL 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 getuserrange3TSOL man page. The following description includes the prototype declaration for the method:public final java.lang.String toRootPath()Java methodstoRootPathtoRootPath methoddeclarationThis 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 getzonerootbylabel3TSOL man page. See also Accessing Labels in Zones. The Java implementation of the Trusted Extensions label APIs does not include interfaces for obtaining the remote host type. 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_str3TSOL 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_str3TSOL man page.public final java.lang.String toColor()Java methodstoColortoColor methoddeclarationThis method returns the color of the SolarisLabel object. The value is suitable for use by HTML. public final java.lang.String toInternal()Java methodstoInternaltoInternal methoddeclarationThis 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()Java methodstoStringtoString methoddeclarationThis 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()Java methodstoTexttoText methoddeclarationThis method returns a human-readable text string of the SolarisLabel object. public java.lang.String toTextLong()Java methodstoTextLongtoTextLong methoddeclarationThis method returns the long human-readable text string of the SolarisLabel object. public java.lang.String toTextShort()Java methodstoTextShorttoTextShort methoddeclarationThis 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_str3TSOL and m_label3TSOL man pages.public java.lang.String toCaveats()Java methodstoCaveatstoCaveats methoddeclarationThis method returns a human-readable text string that is suitable for the caveats section of the banner page.This method is only available for SensitivityLabel objects, not for ClearanceLabel objects. public java.lang.String toChannels()Java methodstoChannelstoChannels methoddeclarationThis method returns a human-readable text string that is suitable for the handling channels section of the banner page.This method is only available for SensitivityLabel objects, not for ClearanceLabel objects. public java.lang.String toFooter()Java methodstoFootertoFooter methoddeclarationThis method returns a human-readable text string that is appropriate for use as the sensitivity label. This sensitivity label appears at the bottom of banner and trailing pages.This method is only available for SensitivityLabel objects, not for ClearanceLabel objects. public java.lang.String toHeader()Java methodstoHeadertoHeader methoddeclarationThis method returns a human-readable text string that is appropriate for use as the sensitivity label. This sensitivity label appears at the top of banner and trailing pages.This method is only available for SensitivityLabel objects, not for ClearanceLabel objects. public java.lang.String toProtectAs()Java methodstoProtectAstoProtectAs methoddeclarationThis method returns a human-readable text string that is suitable for the page downgrade section of the banner page.This method is only available for SensitivityLabel objects, not for ClearanceLabel objects. SensitivityLabel subclasscode example printer banner pagelabel translation code examplesprinter banner code exampleslabel_encodings filecreating printer banner toHeader methodcode example toFooter methodcode example toProtectAs methodcode example toCaveats methodcode example toChannels methodcode example getSensitivityLabel static factorycode example The following example code shows how to use the Java bindings to create a banner page similar to the one described in Obtaining Printer Banner Information.import solarismac.*; import java.io.*; /* * Banner page example */ public class PrintTest1 { public static void main (String args[]) { try { // Pick a valid label using the label_encodings.example SensitivityLabel sl = SolarisLabel.getSensitivityLabel("TOP SECRET A B SA"); // "Protect as classification" System.out.println(sl.toHeader()); System.out.println(); // "Protect as classification plus compartments" System.out.println("This output must be protected as:"); System.out.println(sl.toProtectAs()); System.out.println("unless manually reviewed and downgraded."); System.out.println(); // Handling instructions specified in PRINTER BANNERS System.out.println(sl.toCaveats()); System.out.println(); // Handling instructions specified in CHANNELS System.out.println(sl.toChannels()); System.out.println(); // "Protect as classification" System.out.println(sl.toFooter()); System.out.println(); } catch (Exception e) { e.printStackTrace(); } } }For a process label of TOP SECRET A B SA, the text output might be the following: TOP SECRET This output must be protected as: TOP SECRET A B SA unless manually reviewed and downgraded. (FULL SA NAME) HANDLE VIA (CH B)/(CH A) CHANNELS JOINTLY TOP SECRET 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_label3TSOL and m_label3TSOL man pages.public static ClearanceLabel getClearanceLabel(java.lang.String label)Java static factoriesgetClearanceLabelgetClearanceLabel static factorydeclarationThis 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)Java static factoriesgetSensitivityLabelgetSensitivityLabel static factorydeclarationThis 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"); dominates methoddeclaration equals methoddeclaration strictlyDominates methoddeclaration inRange methoddeclaration Java methodsinRange Java methodsdominates Java methodsequals Java methodsstrictlyDominates 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 blcompare3TSOL 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)inRange methoddeclarationJava methodsinRangeThe 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.getMinimum methoddeclarationgetMaximum methoddeclarationJava methodsgetMaximumJava methodsgetMinimumThe 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 blminmax3TSOL 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)getMaximum methoddeclarationJava methodsgetMaximumThe 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)getMinimum methoddeclarationJava methodsgetMinimumThe 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)getMaximum methoddeclarationJava methodsgetMaximumThe 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)getMinimum methoddeclarationJava methodsgetMinimumThe 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.Input Labels getMinimum Output getMaximum Output SECRET A BTOP SECRET A B SA SB CC SECRET A B TOP SECRET A B SA SB CC SECRET A BTOP SECRET A SA CC SECRET A TOP SECRET A B SA CC SECRET A BTOP SECRET SECRET TOP SECRET A B SECRET ATOP SECRET B SECRET TOP SECRET A B