Trusted Solaris Developer's Guide

Programming Interface Declarations

The following programming interfaces are available for general label operations and accessing labels on processes and file system objects.

System Calls

These system calls get and set a file or process CMW label, or get the file system label range.

Caution -

Every process that sets a label on another process or file system object must set a valid label as defined in the label_encodings file, and must pass the correct binary form of the label. The text to binary translation functions correct the label as much as possible to ensure a correct binary label results from the translation. However, you might still use the bslvalid(3TSOL) routine to check that the label is valid. A correctly constructed binary label can be invalid for a given system or user and should be checked that it falls within the system or user accreditation range with the blinset(3TSOL) routine.

File CMW Label

These system calls get and set the file CMW label by the path name or file descriptor. Refer to the setcmwlabel(2) and getcmwlabel(2) man pages.

int setcmwlabel(const char *path,
	const bclabel_t *label, const setting_flag_t flag);
int getcmwlabel(const char *path, const bclabel_t *label);

int fsetcmwlabel(const int fd, const bclabel_t *label,
	const setting_flag_t flag);
int fgetcmwlabel(const int fd, bclabel_t *label);

int lsetcmwlabel(const int fd,
	const bclabel_t *label, const setting_flag_t flag);
int lgetcmwlabel(const int fd, bclabel_t *label);

Process CMW Label

These system calls get and set the process CMW label. Refer to the setcmwplabel(2) and getcmwplabel(2) man pages.

int setcmwplabel(const bclabel_t *label, const setting_flag_t flag);
int getcmwplabel(const bclabel_t *label);

File System Label Range

These system calls get the file system label range. Refer to the getcmwfsrange(2) man page.

int getcmwfsrange(char *path, brange_t *range);
int fgetcmwfsrange(int fd, brange_t *range);

Library Routines

These library routines access, initialize, compare, translate, and verify labels. Library routines also obtain information on label_encodings(4).

CMW Label Initialization

These routines initialize a CMW label to ADMIN_HIGH, ADMIN_LOW, or undefined (similar to NULL). Refer to the blmanifest(3TSOL) man page.

void bclhigh(bclabel_t *label);
void bcllow(bclabel_t *label);
void bclundef(bclabel_t *label);

CMW Label Portions

These routines access the sensitivity label portion of a CMW label. Refer to the blportion(3TSOL) man page.

void getcsl(bslabel_t *destination_label, const bclabel_t *source_label);
void setcsl(bclabel_t *destination_label, const bslabel_t *source_label);
bslabel_t *bcltosl(bclabel_t *label);

Sensitivity Label Initialization

These routines initialize a sensitivity label to ADMIN_HIGH, ADMIN_LOW, or undefined. Refer to the blmanifest(3TSOL) man page.

void bslhigh(bslabel_t *label);
void bsllow(bslabel_t *label);
void bslundef(bslabel_t *label);

Level Comparison

These routines compare two levels to see if level1 equals, dominates, or strictly dominates level2. A level is a classification and set of compartments in a sensitivity label or clearance.

A returned non-zero is true and 0 is false. Refer to the blcompare(3TSOL) man page.

int blequal(const blevel_t *level1, const blevel_t *level2);
int bldominates(const blevel_t *level1, const blevel_t *level2);
int blstrictdom(const blevel_t *level1, const blevel_t *level2);
int blinrange(const blevel_t *level, const brange_t *range);

Label Types

These routines check or set label type. A label can be a defined or undefined CMW label or sensitivity label. Refer to the bltype(3TSOL) man page.

int bltype(const void *label, const unsigned char type);
void setbltype(void *label, const unsigned char type);

Level Bounds

These routines compare two levels to find the sensitivity level that represents the greatest lower bound (blminimum(3TSOL)) or least upper bound (blmaximum(3TSOL)) of the range bounded by the two levels. A level is a classification and set of compartments in a sensitivity label or clearance. Refer to the blcompare(3TSOL) man page.

void blmaximum(blevel_t *maximum_label, const blevel_t *bounding_label);
void blminimum(blevel_t *minimum_label, const blevel_t *bounding_label);

Label Encodings File

The label_encodings file is a text file maintained by the system administrator that contains site-specific label definitions and constraints. This file is kept in /etc/security/tsol/label_encodings. See Trusted Solaris Label Administration and Compartmented Mode Workstation Labeling: Encodings Format for information on the label_encodings file.

These routines return information specified in the label_encodings file on maximum string lengths, version of label_encodings file in use, and text color name for the specified binary level.

Maximum string lengths. Refer to the labelinfo(3TSOL) man page.

int labelinfo(struct label_info *info);

Version in use. Refer to the labelvers(3TSOL) man page.

int labelvers(char **version, const int length);

Text color name for a binary level. Refer to the bltocolor(3TSOL) man page.

char bltocolor(const blevel_t *label);
char bltocolor_t(const blevel_t *label, const int size, char * color_name);

Valid Sensitivity Label

This routine checks whether the specified sensitivity label is valid for the system (is defined in the label_encodings file for the system). Refer to the blvalid(3TSOL) man page.

int bslvalid(const bslabel_t *senslabel);

Accreditation range

This routine checks whether the sensitivity label falls within the system accreditation range as set in the label_encodings file for the system. Refer to the blinset(3TSOL) man page.

int blinset(const blevel_t *senslabel, const set_id *id);

Binary Translation

These routines translate a binary CMW label or sensitivity label from binary to text and back again. When translating from a string to binary, the string can be text or hexadecimal when flag is NEW_LABEL or NO_CORRECTION. Refer to the bltos(3TSOL) and stobl(3TSOL) man pages.

Note -

See Chapter 14, Trusted X Window System for interfaces that translate binary labels to text, clip the final label according to a specified width, and use a font list for display in Motif-based graphical user interfaces (GUIs).

CMW Label and text

int bcltos(const bclabel_t *label,
	char **string,	const int length,
	const int flags);
int stobcl(const char *string,	
	bclabel_t *label,
	const int flags,
	int *error);

/* Translate and Clip string to length */
char *sbcltos(const bclabel_t *label,
	const int length);

/* Translate for inclusion on printer banner and header pages */
char *bcltobanner(const bclabel_t *label,
	struct banner_fields *fields,
	const int flags);

Binary Sensitivity Label and text

int bsltos(const bslabel_t *label,
	char **string,
	const int length,
	const int flags);
int stobsl(const char *string,
	bslabel_t *label,
	const int flags,
	int *error);

/* Translate and clip string to length */
char *sbsltos(const bslabel_t *label,
	const int length);

Binary and Hexadecimal Translation

These routines translate a binary CMW label or sensitivity label from binary to hexadecimal and back again. Refer to the btohex(3TSOL) and hextob(3TSOL) man pages.

Allocate and Free Memory for reentrant functions.

char h_alloc(const unsigned char id);
void h_free(char *hex);

Translate CMW label between binary and Hexadecimal.

char *bcltoh(const bclabel_t *label);
char *bcltoh_r(const bclabel_t *label, char *hex);
int htobcl(const char *hex, bclabel_t *label);

Translate sensitivity label between binary and Hexadecimal.

char *bsltoh(const bslabel_t *label);
char *bsltoh_r(const bslabel_t *label, char *hex);
int htobsl(const char *hex, bslabel_t *label);