The Solaris Trusted Extensions software (Trusted Extensions) provides application programming interfaces (APIs) that enable you to write applications that access and handle labels. This chapter summarizes the API functionality and introduces you to the Trusted Extensions security policy.For Trusted Extensions term definitions, see the glossary in the Solaris Trusted Extensions User’s Guide.For examples of how the Trusted Extensions APIs are used in the Solaris Operating System (Solaris OS), see the Solaris source code. Go to the Open Solaris web site and click Source Browser in the left navigation bar. Use the Source Browser to search through the Solaris source code.This chapter covers the following topics:Understanding Labels Trusted Extensions APIs Trusted Extensions Security Policy The Solaris Trusted Extensions software provides a set of policies and services to extend the security features of the Solaris OS. These extensions provide access control that is based on label relationships.Trusted Extensions APIsSolaris examplesAPIsexamples of Trusted Extensions in SolarisSolarisexamples of Trusted Extensions APIsexamples of Trusted Extensions APIs in Solarissecurity policydefinition oftermsdefinitions ofdefinitions of termsLabels control access to data and maintain the classification of data. The labels are attributes that are interpreted by the system security policy. The system security policy is the set of rules that is enforced by system software to protect information that is being processed on the system. The term security policy can refer to the policy itself or to the implementation of the policy. For more information, see Trusted Extensions Security Policy.This section includes overview information about label types, ranges, components, and relationships.The Trusted Extensions software defines two types of labels: sensitivity labels and clearance labels. A sensitivity label indicates the security level of an entity and is usually referred to as a label. A clearance label defines the upper boundary of a label range and is usually referred to as a clearance.sensitivity labelslabelstypessensitivitysensitivity labelsAPIsintroduction tolabel APIsintroduction tocompartmentslabel componentclassificationslabel componentlabelscomponents ofThe Trusted Extensions software uses zones to contain classified information at various levels. Each level is associated with its own zone that has a sensitivity label. The sensitivity label specifies the sensitivity of the information in that zone and is applied to all of the subjects and objects in that zone. A label might be something like CONFIDENTIAL, SECRET, or TOP SECRET. A subject is an active entity, such as a process, that causes information to flow among objects or changes a system's state. An object is a passive entity that contains or receives data, such as a file or device. All processes that run in a zone, all files that are contained in a zone, and so on, have the same sensitivity label as their zone. All processes and objects have a sensitivity label that is used in mandatory access control (MAC) decisions. By default, sensitivity labels are visible in the windowing system. labelstypesclearanceclearance labelsclearancessessionclearancesusercompartmentsclearance componentclassificationsclearance componentThe security administrator assigns a clearance to each user. A clearance is a label that defines the upper boundary of a label range. For example, if you have a clearance of SECRET, you can access information that is classified at this level or lower, but not information that is classified at a higher level. A user clearance is assigned by the security administrator. It is the highest label at which a user can access files and initiate processes during a session. In other words, a user clearance is the upper boundary of a user's account label range. At login, a user selects his session clearance. The session clearance determines which labels a user can access. The session clearance sets the least upper bound at which the user can access files and initiate processes during that login session. The session clearance is dominated by the user clearance. label ranges The security administrator defines label ranges and label sets to enforce mandatory access control (MAC) policy. A label range is a set of labels that is bounded at the upper end by a clearance or a limit and at the lower end by a minimum label. A label limit is the upper bound of a label range. A label set contains one or more discrete labels that might be disjoint from one another. Labels in a label set do not dominate one another. A label contains a hierarchical classification and a set of zero or more nonhierarchical compartments. A classification is also referred to as a level or a security level. A classification represents a single level within a hierarchy of labels, for example, TOP SECRET or UNCLASSIFIED. A compartment is associated with a classification and represents a distinct, nonhierarchical area of information in a system, such as private information for a human resources (HR) group or a sales group. A compartment limits access only to users who need to know the information in a particular area. For example, a user with a SECRET classification only has access to the secret information that is specified by the associated list of compartments, not to any other secret information. The classification and compartments together represent the label of the zone and the resources within that zone.The textual format of a classification is specified in the label_encodings file and appears similar to this:CLASSIFICATIONS: name= CONFIDENTIAL; sname= C; value= 4; initial compartments= 4-5 190-239; name= REGISTERED; sname= REG; value= 6; initial compartments= 4-5 190-239;The textual format of a compartment is specified in the label_encodings file and appears similar to this:WORDS: name= HR; minclass= C; compartments= 0;For more information about label definitions and label formats, see Solaris Trusted Extensions Label Administration and Compartmented Mode Workstation Labeling: Encodings Format. For information about the label APIs, see Chapter 2, Labels and Clearances. Comparing labels means that the label of a process is compared to the label of a target, which might be a sensitivity label or a clearance label. Based on the result of the comparison, the process is either granted access or denied access to the object. Access is granted only when the label of the process dominates the label of the target. Label relationships and dominance are described later in this section. For examples, see Determining the Relationship Between Two Labels.relationships between labelslabelsrelationshipslabelsdefinition ofprocess clearanceslabels definedA security level is a numerical classification. A label indicates the security level of an entity and might include zero or more compartments. An entity is something that can be labeled, such as a process, zone, file, or device.Labels are of the following types and relate to each other in these ways:clearancesequal labelsequal labelscompartmentsequalclassificationsequalEqual – When one label is equal to another label, both of these statements are true:The label's classification is numerically equal to the other label's classification. The label has exactly the same compartments as the other label. clearancesdominant labelsdominant labelscompartmentsdominantclassificationsdominantDominant – When one label dominates another label, both of these statements are true:The label's classification is numerically greater than or equal to the other label's classification. The label has exactly the same compartments as the other label. clearancesstrictly dominant labelsstrictly dominant labelscompartmentsstrictly dominantclassificationsstrictly dominantStrictly dominant – When one label strictly dominates another label, both of these statements are true:The label's classification is numerically greater than or equal to the other label's classification. The label has all the compartments that the other label has and at least one other compartment. clearancesdisjoint labelsdisjoint labelscompartmentsdisjointclassificationsdisjointDisjoint – When one label is disjoint with another label, both of these statements are true:The labels are not equal. Neither label dominates the other label. The label_encodings file is used to specify the classifications and compartments for labels. See the label_encodings4 man page.labelsdominantdominant labelsWhen any type of label has a security level that is equal to or greater than the security level of a second label, the first label is said to dominate the second label. This comparison of security levels is based on classifications and compartments in the labels. The classification of the dominant label must be equal to or greater than the classification of the second label. Additionally, the dominant label must include all the compartments in the second label. Two equal labels are said to dominate each other.In the following sample excerpt of the label_encodings file, the REGISTERED (REG) label dominates the CONFIDENTIAL (C) label. The comparison is based on the value of each label's value keyword. The value of the REG label's value keyword is numerically greater than or equal to the value of the C label's value keyword. Both labels dominate the PUBLIC (P) label.The value of the initial compartments keyword shows the list of compartments that are initially associated with the classification. Each number in the initial compartments keyword is a compartment bit, each of which represents a particular compartment.CLASSIFICATIONS: name= PUBLIC; sname= P; value= 1; name= CONFIDENTIAL; sname= C; value= 4; initial compartments= 4-5 190-239; name= REGISTERED; sname= REG; value= 6; initial compartments= 4-5 190-239;The following label_encodings excerpt shows that the REG HR label (Human Resources) dominates the REG label. The REG HR label has the REGISTERED classification and the HR compartment. The compartments keyword for the HR compartment sets the 0 compartment bit, so the REG HR classification has compartments 0, 4–5, and 190–239 set, which is more than the compartments set by the REG classification.CLASSIFICATIONS: name= REGISTERED; sname= REG; value= 6; initial compartments= 4-5 190-239; ... WORDS: name= HR; minclass= C; compartments= 0;labelsstrictly dominantSometimes, strict dominance is required to access an object. In the previous examples, the REG label strictly dominates the P label, and the REG HR label strictly dominates the REG label. When comparing labels, a REG label dominates another REG label.labelsdisjointLabels that do not dominate each other are said to be disjoint. A disjoint label might be used to separate departments in a company. In the following example, the REG HR label (Human Resources) is defined as being disjoint from the REG Sales label. These labels are disjoint because each compartment sets a different compartment bit.CLASSIFICATIONS: name= REGISTERED; sname= REG; value= 6; initial compartments= 4-5 190-239; ... WORDS: name= HR; minclass= C; compartments= 0; name= Sales; minclass= C; compartments= 1;For information about label APIs, see Sensitivity Label APIs. This section introduces the three Trusted Extensions APIs that are described in this book:Label APIs Trusted X Window System APIs Label Builder APIs X Window SystemTrusted X Window SystemAPIssecurity APIs from Solaris OSIn addition to these Trusted Extensions APIs, you can use the security APIs that are available with the Solaris OS. An application that runs on Trusted Extensions might require the manipulation of other security attributes. For example, the user and profile databases contain information about users, roles, authorizations, and profiles. These databases can restrict who can run a program. Privileges are coded into various Solaris programs and can also be coded into third-party applications.For more information about these Solaris OS security APIs, see Developing Privileged Applications, in Solaris Security for Developers Guide.The Solaris OS provides discretionary access control (DAC), in which the owner of the data determines who is permitted access to the data. The Trusted Extensions software provides additional access control, which is called mandatory access control (MAC). In MAC, ordinary users cannot specify or override the security policy. The security administrator sets the security policy.Applications use Trusted Extensions APIs to obtain labels for hosts, zones, users, and roles. Where the security policy permits, the APIs enable you to set labels on user processes or on role processes. Setting a label on a zone or on a host is an administrative procedure, not a programmatic procedure.You can write applications to customize window labels. The Trusted Extensions software provides Motif based programming interfaces for adding a basic label-building user interface to an application. The label-building interface enables a user to interactively build valid sensitivity labels and valid clearances.The label APIs operate on opaque labels. In an opaque label, the internal structure of the label is not exposed. Using an opaque label enables existing programs that are created with the APIs to function even if the internal structure of the label changes. For example, you cannot use the label APIs to locate particular bits in a label. The label APIs enable you to obtain labels and to set labels. You can only set labels if you are permitted to do so by the security policy.Labels, label ranges, and a label limit determine who can access information on a system that is configured with Trusted Extensions.The label APIs are used to access, convert, and perform comparisons for labels, label ranges and limits, and the relationship between labels. A label can dominate another label, or a label can be disjoint from another label.The label_encodings file defines the sensitivity labels, clearance labels, label ranges, and label relationships that pertain to your Trusted Extensions environment. This file also controls the appearance of labels. The security administrator is responsible for creating and maintaining the label_encodings file. See the label_encodings4 man page.The label of a process is determined by the zone in which the process executes.label rangesoverviewAll objects are associated with a label or sometimes with a label range. An object can be accessed at a particular label within the defined label range. The objects that are associated with a label range include the following:All users and all roles All hosts with which communications are permitted Zone interfaces and network interfaces Allocatable devices, such as tape drives, diskette drives, CD-ROM devices, and audio devices Other devices that are not allocatable, such as printers and workstationsWorkstation access is controlled by the label range that is set for the frame buffer or video display device. The security administrator sets this range by using the Device Manager GUI. By default, devices have a range from ADMIN_LOW to ADMIN_HIGH. For more information about labels, see Label Types.MAC compares the label of the process that is running an application with the label or the label range of any object that the process tries to access. MAC permits a process to read down to a lower label and permits a process to write to an equal label.Label[Process] >= Label[Object]A process bound to a multilevel port (MLP) can listen for requests at multiple labels and send replies to the originator of the request. In Trusted Extensions, such replies are write-equal.Label[Process] = Label[Object] APIssensitivity label Sensitivity label APIs can be used to do the following:Obtain a process label Initialize labels Find the greatest lower bound or the least upper bound between two labels Compare labels for dominance and equality Check and set label types Convert labels to a readable format Obtain information from the label_encodings file Check that a sensitivity label is valid and within the system range For a description of these APIs, see Chapter 2, Labels and Clearances. APIsclearance label Users, devices, and network interfaces have label ranges. The upper bound of the range is effectively the clearance. If the upper bound of the range and the lower bound of the range are equal, the range is a single label.Clearance label APIs can be used to do the following:Find the greatest lower bound or the least upper bound between two labels Compare labels for dominance and equality Convert clearances between the internal format and the hexadecimal format For a description of these APIs, see Chapter 2, Labels and Clearances. APIslabel range labelsranges A label range is used to set limits on the following:The labels at which hosts can send and receive information The labels at which processes acting on behalf of users and roles can work on the system The labels at which users can allocate devicesThis use of a label range restricts the labels at which files can be written to storage media on these devices. Label ranges are assigned administratively. Label ranges can apply to users, roles, hosts, zones, network interfaces, printers, and other objects.You can use the following methods to obtain information about label ranges:getuserrange obtains the user's label range. getdevicerange obtains the label range of a device. tninfo -t template-name shows the label range of a template that is associated with a network interface. For a description of these APIs, see Chapter 2, Labels and Clearances. APIsTrusted X Window System label APIswindows Trusted X Window Systemdescription of The Trusted X Window System, Version 11, server starts at login. The server handles the workstation windowing system by using a trusted interprocess communication (IPC) path. Windows, properties, selections, and ToolTalk sessions are created at multiple sensitivity labels as separate and distinct objects. The creation of distinct objects at multiple sensitivity labels is called polyinstantiation. Applications that are created with Motif widgets, Xt Intrinsics, Xlib, and desktop interfaces run within the constraints of the security policy. These constraints are enforced by extensions to the X11 protocols.Chapter 6, Trusted X Window System describes the programming interfaces that can access the security attribute information described in Trusted Extensions Security Policy. These programming interfaces can also be used to translate the labels and clearances to text. The text can be constrained by a specified width and font list for display in the Trusted X Window System.security attributesTrusted X Window Systemcontrast with SolarisTrusted X Window Systemsecurity attributescontrast with SolarisThe Trusted X Window System stores the following security attributes:Audit IDGroup IDInternet addressProcess IDSensitivity labelSession IDTrusted Path flagTrusted Path windowUser IDX Window Server owner IDX Window Server clearanceX Window Server minimum label Trusted Path windowdefinition ofTrusted X Window SystemTrusted Path windowThe Trusted Path flag identifies a window as a Trusted Path window. The Trusted Path window protects the system from being accessed by untrusted programs. This window is always the topmost window, such as the screen stripe or login window.Appendix B, Solaris Trusted Extensions API Reference lists the extensions that you can use to create an X11 trusted IPC path. label APIswindows Label Builderdescription of The Trusted Extensions software provides a label builder API that enables you to create a graphical user interface (GUI) for your application. The GUI takes user input and builds a valid label from that input.A system that is configured with Solaris Trusted Extensions provides Motif based programming interfaces for adding a basic label-building user interface to an application. The label-building interface enables a user to interactively build valid sensitivity labels and valid clearances. For information about these programming interfaces, see Chapter 7, Label Builder APIs. Sensitivity labels control access to data and maintain the classification of data. All processes and objects have a sensitivity label that is used in MAC decisions. The labels are attributes that are interpreted by the system security policy. The system security policy is the set of rules that is enforced by system software to protect information being processed on the system.The following sections describe how the Trusted Extensions security policy affects multilevel operations, zones, and labels.multilevel operationssecurity policy for security policymultilevel operations global zonecontrolling multilevel operations processesmultilevel initiated in global zone When you create an operation that runs at multiple security levels, you must consider the following issues:Write-down policy in the global zone Default security attributes Default network policy Multilevel ports MAC-exempt sockets Operations that run at multiple security levels are controlled by the global zone because only processes in the global zone can initiate processes at specified labels.security policywrite-down in global zone global zonemounts in zonesmounts and the global zone processeswriting down from global zone file_dac_search privilegeoverriding access to parent directory of zone's root directory privilegesfile_dac_search The ability of a subject, such as a process, to write an object whose label it dominates is referred to as writing down. The write-down policy in the global zone is specified administratively. Because global zone processes run at the ADMIN_HIGH label, certain file systems that are associated with other labels can be mounted read-write in the global zone. However, these special file system mounts must be administratively specified in automount maps, and they must be mounted by the global zone automounter. These mounts must have mount points within the zone path of the zone that has the same label as the exported file system. However, these mount points must not be visible from within the labeled zone.For example, if the PUBLIC zone has a zone path of /zone/public, a writable mount point of /zone/public/home/mydir is permitted. However, a writable mount point of /zone/public/root/home/mydir is not permitted because it can be accessed by the labeled zone and not by the global zone. No cross-zone NFS mounts are permitted, which means that the NFS-mounted files can only be accessed by processes that run in the zone that mounted the file system. Global zone processes can write down to such files, subject to the standard discretionary access control (DAC) policy.Local file systems associated with zones are protected from access by global zone processes by DAC, which uses file permissions and access control lists (ACLs). The parent directory of each zone's root (/) directory is only accessible by root processes or by processes that assert the file_dac_search privilege.In general, the ability to write down from the global zone is restricted. Typically, writing down is used only when a file is reclassified by using the setflabel interface or when privileged users drag and drop files between File Manager applications in different zones. Default security attributes are assigned to messages that arrive on Trusted Extensions hosts from other host types. The attributes are assigned according to settings in the network database files. For information about host types, their supported security attributes, and network database file defaults, see Solaris Trusted Extensions Administrator’s Procedures. security policynetwork network security policydefault For network operations that send or receive data, the default policy is that the local process and the remote peer must have the same label. This policy applies to all zones, including the global zone, whose network label is ADMIN_LOW. However, the default network policy is more flexible than the policy for mounting file systems. Trusted Extensions provides administrative interfaces and programmatic interfaces for overriding the default network policy. For example, a system administrator can create an MLP in the global zone or in a labeled zone to enable listening at different labels. multilevel portsdescription of zonesmultilevel ports processesbinding to multilevel ports SO_RECVUCRED option Use extreme caution when using a multilevel port to violate MAC policy. When you must use this mechanism, ensure that your server application enforces MAC policy. privilegesnet_bindmlpMultilevel ports (MLPs) are listed in the tnzonecfg administrative database. Processes within the zone can bind to MLPs if these processes assert the net_bindmlp privilege. If the port number is less than 1024, the net_privaddr privilege must also be asserted. Such bindings allow a process to accept connections at all labels that are associated with the IP addresses to which the process is bound. The labels that are associated with a network interface are specified in the tnrhdb database and the tnrhtp database. The labels can be specified by a range, by a set of explicit enumerated labels, or by a combination of both.When a privileged process that is bound to an MLP receives a TCP request, the reply is automatically sent with the label of the requester. For UDP datagrams, the reply is sent with the label that is specified by the SO_RECVUCRED option.networkssecurity attributessecurity attributeslabels from remote hostsThe privileged process can implement a more restrictive MAC policy by comparing the label of the request to other parameters. For example, a web server could compare the label of the requesting process with the label of the file specified in the URL. The remote label can be determined by using the getpeerucred function, which returns the credentials of the remote peer. If the peer is running in a zone on the same host, the ucred_get library routine returns a full set of credentials. Regardless of whether the peer is local or remote, the label of the peer is accessible from the ucred data structure by using the ucred_getlabel function. This label can be compared with other labels by using functions such as bldominates.A zone can have single-level ports and multilevel ports. See Multilevel Port Information. socketsexempt from MAC MAC (mandatory access control)making socket exempt from SO_MAC_EXEMPT option net_mac_aware privilege privilegesnet_mac_aware setpflags system call The Trusted Extensions software provides an explicit socket option, SO_MAC_EXEMPT, to specify that the socket can be used to communicate with an endpoint at a lower label.The SO_MAC_EXEMPT socket option must never be used unintentionally. Use extreme caution when using this socket option to disable MAC policy. When you must use this mechanism, ensure that your client application enforces MAC policy. The Trusted Extensions software restricts the use of the SO_MAC_EXEMPT option in these ways:To explicitly set the socket option, a process must assert the net_mac_aware privilege. To further restrict the use of this socket option, the net_mac_aware privilege can be removed from the limit set for ordinary users. See the user_attr4 man page for details.privilegesnet_mac_awareSometimes, explicitly setting the socket option is not practical, such as when the socket is managed by a library. In such circumstances, the socket option can be set implicitly. The setpflags system call enables you to set the NET_MAC_AWARE process flag. Setting this process flag also requires the net_mac_aware privilege. All sockets that are opened while the process flag is enabled automatically have the SO_MAC_EXEMPT socket option set. See the setpflags2 and getpflags2 man pages.For applications that cannot be modified or recompiled, use the ppriv -M command to pass the net_mac_aware process flag to the application. In this case, all sockets that are opened by the application have the SO_MAC_EXEMPT option set. However, child processes of the application do not have this process flag or the related privilege.Whenever you can, scrutinize and modify the source code of an application when you need to use the SO_MAC_EXEMPT socket option. If you cannot make such modifications to the code or if a safer method is not available to you, you may use the ppriv -M command.The SO_MAC_EXEMPT socket option has been used sparingly by the Solaris OS. This option has been used by the NFS client. An NFS client might need to communicate with an NFS server that runs at a different label on an untrusted operating system. The NFS client enforces MAC policy to ensure that inappropriate requests are not granted.In the Solaris OS, both the NFS server and client code include and enforce MAC policy so that communications between the Solaris client or server and an untrusted client or server has MAC policy enabled. To enable an untrusted host to communicate with a system that runs Trusted Extensions, the untrusted host must have an entry in the tnrhdb database. For more information, see Configuring Trusted Network Databases (Task Map) in Solaris Trusted Extensions Administrator’s Procedures.For examples of how the Trusted Extensions APIs are used in the Solaris OS, see the Solaris source code. Go to the Open Solaris web site and click Source Browser in the left navigation bar. Use the Source Browser to search through the Solaris source code. zonesin Trusted Extensions zoneslabeled All objects on a system configured with Trusted Extensions are associated with a zone. Such zones are called labeled zones. A labeled zone is a non-global zone and is accessible to ordinary users. A user who is cleared at more than one label is permitted access to a zone at each of those labels.The global zone is a special zone that contains files and processes that control the security policy of the system. Files in the global zone can only be accessed by roles and by privileged processes.security policyglobal zone labelsin global zone global zonelabels in ADMIN_LOW label ADMIN_HIGH label labelsADMIN_HIGH labelsADMIN_LOW The global zone is assigned a range of labels. The range is from ADMIN_LOW to ADMIN_HIGH. ADMIN_HIGH and ADMIN_LOW are administrative labels.Objects in the global zone that are shared with other zones are assigned the ADMIN_LOW label. For example, files in the /usr, /sbin, and /lib directories are assigned the ADMIN_LOW label. These directories and their contents are shared by all zones. These files and directories are typically installed from packages and are generally not modified, except during packaging or patching procedures. To modify ADMIN_LOW files, a process must typically be run by superuser or by someone who has all privileges.Information that is private to the global zone is assigned the label ADMIN_HIGH. For example, all processes in the global zone and all administrative files in the /etc directory are assigned the ADMIN_HIGH label. Home directories that are associated with roles are assigned the ADMIN_HIGH label. Multilevel information that is associated with users is also assigned the ADMIN_HIGH label. See Multilevel Operations. Access to the global zone is restricted. Only system services and administrative roles can execute processes in the global zone. non-global zones labeled zones processesin labeled zones Non-global zones are called labeled zones. Each labeled zone has a unique label. All objects within a labeled zone have the same label. For example, all processes that run in a labeled zone have the same label. All files that are writable in a labeled zone have the same label. A user who is cleared for more than one label has access to a labeled zone at each label.APIsfor zone labels and zone pathslabel APIsfor zone labels and zone pathszonesAPIs for zone labels and zone pathsTrusted Extensions defines a set of label APIs for zones. These APIs obtain the labels that are associated with labeled zones and the path names within those zones:getpathbylabel getzoneidbylabel getzonelabelbyid getzonelabelbyname getzonerootbyid getzonerootbylabel getzonerootbyname For more information about these APIs, see Accessing Labels in Zones.privilegesfile_upgrade_slprivilegesfile_downgrade_slThe label of a file is based on the label of the zone or of the host that owns the file. Therefore, when you relabel a file, the file must be moved to the appropriate labeled zone or to the appropriate labeled host. This process of relabeling a file is also referred to as reclassifying a file. The setflabel library routine can relabel a file by moving the file. To relabel a file, a process must assert the file_upgrade_sl privilege or the file_downgrade_sl privilege. See the getlabel2 and setflabel3TSOL man pages.For more information about setting privileges, see Developing Privileged Applications, in Solaris Security for Developers Guide.