sandbox_create, sandbox_destroy, sandbox_labelfile, sandbox_labelosm, sandbox_enter, sandbox_exit, sandbox_getname, sandbox_getattrs, sandbox_getparents, sandbox_getchildren - sandbox operations
cc [flag...] file... -lsandbox [library...]
#include <sandbox.h>
int sandbox_create(const char *sandboxname, char *classname,
const char *parent_sandbox, const char *username,
const char *password, const char *homedir, char *groups, int flags);
int sandbox_destroy(const char *sandboxname, int flags);
int sandbox_labelfile(const char *dir, const char *sandboxname, char
*compartments);
int sandbox_labelosm(int shmid, const char *sandboxname, char
*compartments);
int sandbox_enter(const char *sandboxname,
char *compartments, int flags);
int sandbox_exit();
char *sandbox_getname();
struct sandbox *sandbox_getattrs(const char *sandboxname);
int sandbox_getparents(char ***list);
int sandbox_getchildren(char *parent, char ***list);
Sandboxes are uniquely named sets of process attributes that can be used to specify security isolation and resource management requirements. Each sandbox specification consists of a project name, a label, and a set of user attributes. For more information, see the sandboxing(7) man page.
The sandbox_create() function creates a new sandbox. The label of the sandbox is automatically generated, using classname and parent_sandbox as qualifiers. To specify a parent sandbox, set parent_sandbox to NULL. If classname is also NULL, then the sandbox is assigned a uniquely numbered classification name. If an explicit classname is specified, then the classification name must not have been assigned to any other parent sandbox. Parent sandboxes are assigned a compartment using the default prefix appended by All, for example, SandboxAll. If additional compartment names are defined in the label_encodings file, then they are also assigned to parent sandboxes.
If parent_sandbox is not NULL then the classification of parent_sandbox is used for the label, and classname is ignored. Each child sandbox is assigned a numbered compartment name that is unique from its siblings.
The name specified in sandboxname also specifies the project. If the project does not already exist then it is created. If the account specified in username does not exist, and SANDBOX_CREATE_USER is set in flags, then a new account is created. The new user ID is computed from the product of the classification number and the compartment number, and also from a fixed offset. When creating a new project, the project ID is set to the user ID, and the user ID is added to the project.
The sandbox's label is assigned to the user when, a user does not have an explicit clearance. Else, the user's clearance is set to the least upper bound of the existing clearance and the label of the sandbox.
If groups is not NULL then the comma separated list of group names are assigned to the account specified by username. The first group name in the list is assigned as the primary group. All the groups must previously exist.
When creating a new account, the password specified in password is applied. The account is marked as expired, so a new password must be supplied when the account is initially authenticated. The home directory is created using the pathname specified in homedir. If homedir is NULL, the default home directory pathname is used. The new home directory is recursively labeled with the sandbox's label if, the parent_sandbox is not NULL and the SANDBOX_CREATE_LABELDIR is set in flags.
Pre-existing files or directories in ZFS filesystems may be labeled by using the sandbox_labelfile() function. Directories are labeled recursively including all subdirectories and files. Shared memory segments may be labeled using the sandbox_labelosm() function. If compartment is NULL the label associated with the sandboxname is used. If compartment is not NULL then each of the specified compartments are either added to or removed from that label depending on whether it is preceded by a plus "+" or minus "-" sign.
The sandbox_destroy() function removes the sandbox specified in sandboxname and the associated project. Parent sandboxes cannot be removed till all their children are removed. If SANDBOX_DESTROY_USER is set in flags then the user account is also removed.
If the user's clearance dominates the target sandbox's label, then the sandboxes may be entered through the PAM-based services like ssh(1). Users with a higher clearance can reduce their process clearance to the sandbox's label by using the sandbox(1) or plabel(1).
The sandbox_enter() function allows a process running in a parent sandbox to enter the child sandbox specified in sandboxname. Unlike PAM-based services which apply the authenticated user's credentials to a newly executed process, the sandbox_enter() function applies the requested attributes to the calling process. The project and clearance of the process are set to that of the target sandbox. If compartments is not NULL then each of the specified compartments are either added to or removed from the process clearance depending on whether it is preceded by a plus "+" or minus "-" sign. If the SANDBOX_ENTER_PERMANENT is set in flags the process is permanently bound to the target sandbox. Otherwise the sandbox_exit() function can be used to revert the process to its parent sandbox. If SANDBOX_ENTER_PERMANENT and SANDBOX_ENTER_SETUID are both set in flags then the credentials associated with the sandbox's username, including the user ID, primary and supplementary groups are applied to the current process. In addition, if SANDBOX_ENTER_CHDIR is set then the current directory is changed to that of the user.
The sandbox_getname() function returns the name of the current sandbox, or NULL if the process is not in a sandbox. The caller is responsible to free the name.
The sandbox_getattrs() function returns a pointer to a sandbox structure containing the attributes of sandboxname which can be freed using free(sandbox). The sandbox structure is defined in <sandbox.h>:
struct sandbox {
char name[MAXSBOXNAME];
char parent[MAXSBOXNAME];
char class[MAXSBOXNAME];
char comps[MAXSBOXNAME];
char hexlabel[MAXSBOXCOMPS];
char username[MAXSBOXNAME];
uid_t uid;
boolean_t hasChildren;
};
The sandbox_getparents() function returns a null terminated array of all parent sandbox names. The caller is responsible to free all the names in the list, and the list array.
The sandbox_getchildren() function returns a null terminated array of all child sandbox names belonging to sandboxname. The caller is responsible to free all the names in the list, and the list array.
Apart from the functions mentioned previously, most of the functions return 0 if successful, and -1 if an error occurs. The error code is set in errno, with the following descriptions:
The sandbox attributes are unreadable.
Unable to connect to the door server. User account updates require a connection to the rad:local service. Other sandboxing operations require a connection to the labeld:clearance service.
A parameter in the calling arguments is not valid.
The device associated with the ZFS filesystem is unavailable.
The specified pathname does not exist.
The filesystem does not support labeling.
Insufficient process privileges.
Dynamic memory allocation failure.
Insufficient process clearance.
The specified sandbox already exists.
All available classifications or compartments have been used.
The parent sandbox cannot be destroyed because it has child sandboxes.
See attributes(7) for descriptions of the following attributes:
|
plabel(1), sandbox(1), projmod(8), sandboxadm(8), getlabel(2), setclearance(3TSOL), setflabel(3TSOL), setproject(3PROJECT), label_to_str(3TSOL), str_to_label(3TSOL), libtsol(3LIB), label_encodings(5), attributes(7), clearance(7), labels(7), resource-controls(7)