Solaris Trusted Extensions Reference Manual

Trusted Extensions Library

bcleartoh(3TSOL)

NAME

btohex, bsltoh, bcleartoh, bsltoh_r, bcleartoh_r, h_alloc, h_free – convert binary label to hexadecimal

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bsltoh(const m_label_t *label);

char *bcleartoh(const m_label_t *clearance);

char *bsltoh_r(const m_label_t *label, char *hex);

char *bcleartoh_r(const m_label_t *clearance, char *hex);

char *h_alloc(const unsigned char type);

void h_free(char *hex);

Interface Level

The bsltoh(), bcleartoh(), bsltoh_r(), bcleartoh_r(), h_alloc(), and h_free() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

These functions convert binary labels into hexadecimal strings that represent the internal value.

bsltoh() and bsltoh_r() convert a binary sensitivity label into a string of the form:

[0xsensitivity_label_hexadecimal_value]

bcleartoh() and bcleartoh_r() convert a binary clearance into a string of the form:

0xclearance_hexadecimal_value

h_alloc() allocates memory for the hexadecimal value type for use by bsltoh_r() and bcleartoh_r().

Valid values for type are:

SUN_SL_ID: label is a binary sensitivity label.
SUN_CLR_ID: label is a binary clearance.

h_free() frees memory allocated by h_alloc().

Return Values

These functions return a pointer to a string that contains the result of the translation, or (char *)0 if the parameter is not of the required type.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

The functions bsltoh() and bcleartoh() share the same statically allocated string storage. They are not MT-Safe. Subsequent calls to any of these functions will overwrite that string with the newly translated string.

For multithreaded applications, the functions bsltoh_r() and bcleartoh_r() should be used.

SunOS 5.10 Last Revised 16 Mar 2006

bcleartoh_r(3TSOL)

NAME

btohex, bsltoh, bcleartoh, bsltoh_r, bcleartoh_r, h_alloc, h_free – convert binary label to hexadecimal

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bsltoh(const m_label_t *label);

char *bcleartoh(const m_label_t *clearance);

char *bsltoh_r(const m_label_t *label, char *hex);

char *bcleartoh_r(const m_label_t *clearance, char *hex);

char *h_alloc(const unsigned char type);

void h_free(char *hex);

Interface Level

The bsltoh(), bcleartoh(), bsltoh_r(), bcleartoh_r(), h_alloc(), and h_free() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

These functions convert binary labels into hexadecimal strings that represent the internal value.

bsltoh() and bsltoh_r() convert a binary sensitivity label into a string of the form:

[0xsensitivity_label_hexadecimal_value]

bcleartoh() and bcleartoh_r() convert a binary clearance into a string of the form:

0xclearance_hexadecimal_value

h_alloc() allocates memory for the hexadecimal value type for use by bsltoh_r() and bcleartoh_r().

Valid values for type are:

SUN_SL_ID: label is a binary sensitivity label.
SUN_CLR_ID: label is a binary clearance.

h_free() frees memory allocated by h_alloc().

Return Values

These functions return a pointer to a string that contains the result of the translation, or (char *)0 if the parameter is not of the required type.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

For multithreaded applications, the functions bsltoh_r() and bcleartoh_r() should be used.

SunOS 5.10 Last Revised 16 Mar 2006

bcleartos(3TSOL)

NAME

bltos, bsltos, bcleartos – translate binary labels to character coded labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int bsltos(const m_label_t *label, char **string, const int str_len, const int flags);

int bcleartos(const m_label_t *label, char **string, const int str_len, const int flags);

Interface Level

The bsltos() and bcleartos() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on labels that dominate the current process' sensitivity label.

These routines translate binary labels into strings controlled by the value of the flags parameter.

The generic form of an output character-coded label is:

CLASSIFICATION WORD1 WORD2 WORD3/WORD4 SUFFIX PREFIX WORD5/WORD6

Capital letters are used to display all CLASSIFICATION names and WORDs. The ` ' (space) character separates classifications and words from other words in all character-coded labels except where multiple words that require the same PREFIX or SUFFIX are present, in which case the multiple words are separated from each other by the `/' (slash) character.

string can point to either a pointer to pre-allocated memory, or the value (char *)0. If string points to a pointer to pre-allocated memory, then str_len indicates the size of that memory. If string points to the value (char *)0, memory is allocated using malloc() to contain the translated character-coded labels. The translated label is copied into allocated or pre-allocated memory.

flags is 0 (zero), or the logical sum of the following:

LONG_WORDS: Translate using long names of words defined in label.
SHORT_WORDS: Translate using short names of words defined in label. If no short name is defined in the label_encodings file for a word, the long name is used.
LONG_CLASSIFICATION: Translate using long name of classification defined in label.
SHORT_CLASSIFICATION: Translate using short name of classification defined in label.
ACCESS_RELATED: Translate only access-related entries defined in information label label.
VIEW_EXTERNAL: Translate ADMIN_LOW and ADMIN_HIGH labels to the lowest and highest labels defined in the label_encodings file.
VIEW_INTERNAL: Translate ADMIN_LOW and ADMIN_HIGH labels to the admin low name and admin high name strings specified in the label_encodings file. If no strings are specified, the strings “ADMIN_LOW” and “ADMIN_HIGH” are used.
NO_CLASSIFICATION: Do not translate classification defined in label.

bsltos() translates a binary sensitivity label into a string. The applicable flags are LONG_CLASSIFICATION or SHORT_CLASSIFICATION, LONG_WORDS or SHORT_WORDS, VIEW_EXTERNAL or VIEW_INTERNAL, and NO_CLASSIFICATION. A flags value 0 is equivalent to (SHORT_CLASSIFICATION | LONG_WORDS).

bcleartos() translates a binary clearance into a string. The applicable flags are LONG_CLASSIFICATION or SHORT_CLASSIFICATION, LONG_WORDS or SHORT_WORDS, VIEW_EXTERNAL or VIEW_INTERNAL, and NO_CLASSIFICATION. A flags value 0 is equivalent to (SHORT_CLASSIFICATION | LONG_WORDS). The translation of a clearance might not be the same as the translation of a sensitivity label. These functions use different label_encodings file tables that might contain different words and constraints.

Return Values

These routines return:

-1: If the label is not of the valid defined required type, if the label is not dominated by the process sensitivity label and the process does not have PRIV_SYS_TRANS_LABEL in its set of effective privileges, or the label_encodings file is inaccessible.
0: If memory cannot be allocated for the return string, or the pre-allocated return string memory is insufficient to hold the string. The value of the pre-allocated string is set to the NULL string (*string[0]='\\00';).
>0: If successful, the length of the character-coded label including the NULL terminator.

PROCESS ATTRIBUTES

If the VIEW_EXTERNAL or VIEW_INTERNAL flags are not specified, translation of ADMIN_LOW and ADMIN_HIGH labels is controlled by the label view process attribute flags. If no label view process attribute flags are defined, their translation is controlled by the label view configured in the label_encodings file. A value of External specifies that ADMIN_LOW and ADMIN_HIGH labels are mapped to the lowest and highest labels defined in the label_encodings file. A value of Internal specifies that the ADMIN_LOW and ADMIN_HIGH labels are translated to the admin low and admin high name strings specified in the label_encodings file. If no such names are specified, the strings “ADMIN_LOW” and “ADMIN_HIGH” are used.

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

If memory is allocated by these routines, the caller must free the memory with free() when the memory is no longer in use.

SunOS 5.10 Last Revised 31 May 2006

blcompare(3TSOL)

NAME

blcompare, blequal, bldominates, blstrictdom, blinrange – compare binary labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int blequal(const m_label_t *label1, const m_label_t *label2);

int bldominates(const m_label_t *label1, const m_label_t *label2);

int blstrictdom(const m_label_t *label1, const m_label_t *label2);

int blinrange(const m_label_t *label, const brange_t *range);

Description

These functions compare binary labels for meeting a particular condition.

blequal() compares two labels for equality.

bldominates() compares label label1 for dominance over label label2.

blstrictdom() compares label label1 for strict dominance over label label2.

blinrange() compares label label for dominance over range->lower_bound and range->upper_bound for dominance over level label.

Return Values

These functions return non-zero if their respective conditions are met, otherwise zero is returned.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface Stability	Stable

bldominates(3TSOL)

NAME

blcompare, blequal, bldominates, blstrictdom, blinrange – compare binary labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int blequal(const m_label_t *label1, const m_label_t *label2);

int bldominates(const m_label_t *label1, const m_label_t *label2);

int blstrictdom(const m_label_t *label1, const m_label_t *label2);

int blinrange(const m_label_t *label, const brange_t *range);

Description

These functions compare binary labels for meeting a particular condition.

blequal() compares two labels for equality.

bldominates() compares label label1 for dominance over label label2.

blstrictdom() compares label label1 for strict dominance over label label2.

blinrange() compares label label for dominance over range->lower_bound and range->upper_bound for dominance over level label.

Return Values

These functions return non-zero if their respective conditions are met, otherwise zero is returned.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface Stability	Stable

blequal(3TSOL)

NAME

blcompare, blequal, bldominates, blstrictdom, blinrange – compare binary labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int blequal(const m_label_t *label1, const m_label_t *label2);

int bldominates(const m_label_t *label1, const m_label_t *label2);

int blstrictdom(const m_label_t *label1, const m_label_t *label2);

int blinrange(const m_label_t *label, const brange_t *range);

Description

These functions compare binary labels for meeting a particular condition.

blequal() compares two labels for equality.

bldominates() compares label label1 for dominance over label label2.

blstrictdom() compares label label1 for strict dominance over label label2.

blinrange() compares label label for dominance over range->lower_bound and range->upper_bound for dominance over level label.

Return Values

These functions return non-zero if their respective conditions are met, otherwise zero is returned.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface Stability	Stable

blinrange(3TSOL)

NAME

blcompare, blequal, bldominates, blstrictdom, blinrange – compare binary labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int blequal(const m_label_t *label1, const m_label_t *label2);

int bldominates(const m_label_t *label1, const m_label_t *label2);

int blstrictdom(const m_label_t *label1, const m_label_t *label2);

int blinrange(const m_label_t *label, const brange_t *range);

Description

These functions compare binary labels for meeting a particular condition.

blequal() compares two labels for equality.

bldominates() compares label label1 for dominance over label label2.

blstrictdom() compares label label1 for strict dominance over label label2.

blinrange() compares label label for dominance over range->lower_bound and range->upper_bound for dominance over level label.

Return Values

These functions return non-zero if their respective conditions are met, otherwise zero is returned.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface Stability	Stable

blmaximum(3TSOL)

NAME | Synopsis | Description | Attributes | See Also

NAME

blminmax, blmaximum, blminimum – bound of two labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

void blmaximum(m_label_t *maximum_label, const m_label_t *bounding_label);

void blminimum(m_label_t *minimum_label, const m_label_t *bounding_label);

Description

blmaximum() replaces the contents of label maximum_label with the least upper bound of the labels maximum_label and bounding_label. The least upper bound is the greater of the classifications and all of the compartments of the two labels. This is the least label that dominates both of the original labels.

blminimum() replaces the contents of label minimum_label with the greatest lower bound of the labels minimum_label and bounding_label. The greatest lower bound is the lower of the classifications and only the compartments that are contained in both labels. This is the greatest label that is dominated by both of the original labels.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface	Stable

blminimum(3TSOL)

NAME | Synopsis | Description | Attributes | See Also

NAME

blminmax, blmaximum, blminimum – bound of two labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

void blmaximum(m_label_t *maximum_label, const m_label_t *bounding_label);

void blminimum(m_label_t *minimum_label, const m_label_t *bounding_label);

Description

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface	Stable

blminmax(3TSOL)

NAME | Synopsis | Description | Attributes | See Also

NAME

blminmax, blmaximum, blminimum – bound of two labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

void blmaximum(m_label_t *maximum_label, const m_label_t *bounding_label);

void blminimum(m_label_t *minimum_label, const m_label_t *bounding_label);

Description

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface	Stable

blstrictdom(3TSOL)

NAME

blcompare, blequal, bldominates, blstrictdom, blinrange – compare binary labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int blequal(const m_label_t *label1, const m_label_t *label2);

int bldominates(const m_label_t *label1, const m_label_t *label2);

int blstrictdom(const m_label_t *label1, const m_label_t *label2);

int blinrange(const m_label_t *label, const brange_t *range);

Description

These functions compare binary labels for meeting a particular condition.

blequal() compares two labels for equality.

bldominates() compares label label1 for dominance over label label2.

blstrictdom() compares label label1 for strict dominance over label label2.

blinrange() compares label label for dominance over range->lower_bound and range->upper_bound for dominance over level label.

Return Values

These functions return non-zero if their respective conditions are met, otherwise zero is returned.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface Stability	Stable

bltocolor(3TSOL)

NAME

bltocolor, bltocolor_r – get character-coded color name of label

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bltocolor(const m_label_t *label);

char *bltocolor_r(const m_label_t *label, const int size, char *color_name);

Interface Level

The bltocolor() and bltocolor_r() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to get color names of labels that dominate the current process's sensitivity label.

bltocolor() and bltocolor_r() get the character-coded color name associated with the binary label label.

Return Values

bltocolor() returns a pointer to a statically allocated string that contains the character-coded color name specified for the label or returns (char *)0 if, for any reason, no character-coded color name is available for this binary label.

bltocolor_r() returns a pointer to the color_name string which contains the character-coded color name specified for the label or returns (char *)0 if, for any reason, no character-coded color name is available for this binary label. color_name must provide for a string of at least size characters.

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

The function bltocolor() returns a pointer to a statically allocated string. Subsequent calls to it will overwrite that string with a new character-coded color name. It is not MT-Safe.

For multithreaded applications the function bltocolor_r() should be used.

If label includes a specified word or words, the character-coded color name associated with the first word specified in the label encodings file is returned. Otherwise, if no character-coded color name is specified for label, the first character-coded color name specified in the label encodings file with the same classification as the binary label is returned.

SunOS 5.10 Last Revised 31 May 2006

bltocolor_r(3TSOL)

NAME

bltocolor, bltocolor_r – get character-coded color name of label

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bltocolor(const m_label_t *label);

char *bltocolor_r(const m_label_t *label, const int size, char *color_name);

Interface Level

The bltocolor() and bltocolor_r() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to get color names of labels that dominate the current process's sensitivity label.

bltocolor() and bltocolor_r() get the character-coded color name associated with the binary label label.

Return Values

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

The function bltocolor() returns a pointer to a statically allocated string. Subsequent calls to it will overwrite that string with a new character-coded color name. It is not MT-Safe.

For multithreaded applications the function bltocolor_r() should be used.

SunOS 5.10 Last Revised 31 May 2006

bltos(3TSOL)

NAME

bltos, bsltos, bcleartos – translate binary labels to character coded labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int bsltos(const m_label_t *label, char **string, const int str_len, const int flags);

int bcleartos(const m_label_t *label, char **string, const int str_len, const int flags);

Interface Level

The bsltos() and bcleartos() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on labels that dominate the current process' sensitivity label.

These routines translate binary labels into strings controlled by the value of the flags parameter.

The generic form of an output character-coded label is:

CLASSIFICATION WORD1 WORD2 WORD3/WORD4 SUFFIX PREFIX WORD5/WORD6

flags is 0 (zero), or the logical sum of the following:

LONG_WORDS: Translate using long names of words defined in label.
SHORT_WORDS: Translate using short names of words defined in label. If no short name is defined in the label_encodings file for a word, the long name is used.
LONG_CLASSIFICATION: Translate using long name of classification defined in label.
SHORT_CLASSIFICATION: Translate using short name of classification defined in label.
ACCESS_RELATED: Translate only access-related entries defined in information label label.
VIEW_EXTERNAL: Translate ADMIN_LOW and ADMIN_HIGH labels to the lowest and highest labels defined in the label_encodings file.
VIEW_INTERNAL: Translate ADMIN_LOW and ADMIN_HIGH labels to the admin low name and admin high name strings specified in the label_encodings file. If no strings are specified, the strings “ADMIN_LOW” and “ADMIN_HIGH” are used.
NO_CLASSIFICATION: Do not translate classification defined in label.

Return Values

These routines return:

-1: If the label is not of the valid defined required type, if the label is not dominated by the process sensitivity label and the process does not have PRIV_SYS_TRANS_LABEL in its set of effective privileges, or the label_encodings file is inaccessible.
0: If memory cannot be allocated for the return string, or the pre-allocated return string memory is insufficient to hold the string. The value of the pre-allocated string is set to the NULL string (*string[0]='\\00';).
>0: If successful, the length of the character-coded label including the NULL terminator.

PROCESS ATTRIBUTES

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

If memory is allocated by these routines, the caller must free the memory with free() when the memory is no longer in use.

SunOS 5.10 Last Revised 31 May 2006

bsltoh(3TSOL)

NAME

btohex, bsltoh, bcleartoh, bsltoh_r, bcleartoh_r, h_alloc, h_free – convert binary label to hexadecimal

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bsltoh(const m_label_t *label);

char *bcleartoh(const m_label_t *clearance);

char *bsltoh_r(const m_label_t *label, char *hex);

char *bcleartoh_r(const m_label_t *clearance, char *hex);

char *h_alloc(const unsigned char type);

void h_free(char *hex);

Interface Level

The bsltoh(), bcleartoh(), bsltoh_r(), bcleartoh_r(), h_alloc(), and h_free() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

These functions convert binary labels into hexadecimal strings that represent the internal value.

bsltoh() and bsltoh_r() convert a binary sensitivity label into a string of the form:

[0xsensitivity_label_hexadecimal_value]

bcleartoh() and bcleartoh_r() convert a binary clearance into a string of the form:

0xclearance_hexadecimal_value

h_alloc() allocates memory for the hexadecimal value type for use by bsltoh_r() and bcleartoh_r().

Valid values for type are:

SUN_SL_ID: label is a binary sensitivity label.
SUN_CLR_ID: label is a binary clearance.

h_free() frees memory allocated by h_alloc().

Return Values

These functions return a pointer to a string that contains the result of the translation, or (char *)0 if the parameter is not of the required type.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

For multithreaded applications, the functions bsltoh_r() and bcleartoh_r() should be used.

SunOS 5.10 Last Revised 16 Mar 2006

bsltoh_r(3TSOL)

NAME

btohex, bsltoh, bcleartoh, bsltoh_r, bcleartoh_r, h_alloc, h_free – convert binary label to hexadecimal

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bsltoh(const m_label_t *label);

char *bcleartoh(const m_label_t *clearance);

char *bsltoh_r(const m_label_t *label, char *hex);

char *bcleartoh_r(const m_label_t *clearance, char *hex);

char *h_alloc(const unsigned char type);

void h_free(char *hex);

Interface Level

The bsltoh(), bcleartoh(), bsltoh_r(), bcleartoh_r(), h_alloc(), and h_free() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

These functions convert binary labels into hexadecimal strings that represent the internal value.

bsltoh() and bsltoh_r() convert a binary sensitivity label into a string of the form:

[0xsensitivity_label_hexadecimal_value]

bcleartoh() and bcleartoh_r() convert a binary clearance into a string of the form:

0xclearance_hexadecimal_value

h_alloc() allocates memory for the hexadecimal value type for use by bsltoh_r() and bcleartoh_r().

Valid values for type are:

SUN_SL_ID: label is a binary sensitivity label.
SUN_CLR_ID: label is a binary clearance.

h_free() frees memory allocated by h_alloc().

Return Values

These functions return a pointer to a string that contains the result of the translation, or (char *)0 if the parameter is not of the required type.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

For multithreaded applications, the functions bsltoh_r() and bcleartoh_r() should be used.

SunOS 5.10 Last Revised 16 Mar 2006

bsltos(3TSOL)

NAME

bltos, bsltos, bcleartos – translate binary labels to character coded labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int bsltos(const m_label_t *label, char **string, const int str_len, const int flags);

int bcleartos(const m_label_t *label, char **string, const int str_len, const int flags);

Interface Level

The bsltos() and bcleartos() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on labels that dominate the current process' sensitivity label.

These routines translate binary labels into strings controlled by the value of the flags parameter.

The generic form of an output character-coded label is:

CLASSIFICATION WORD1 WORD2 WORD3/WORD4 SUFFIX PREFIX WORD5/WORD6

flags is 0 (zero), or the logical sum of the following:

LONG_WORDS: Translate using long names of words defined in label.
SHORT_WORDS: Translate using short names of words defined in label. If no short name is defined in the label_encodings file for a word, the long name is used.
LONG_CLASSIFICATION: Translate using long name of classification defined in label.
SHORT_CLASSIFICATION: Translate using short name of classification defined in label.
ACCESS_RELATED: Translate only access-related entries defined in information label label.
VIEW_EXTERNAL: Translate ADMIN_LOW and ADMIN_HIGH labels to the lowest and highest labels defined in the label_encodings file.
VIEW_INTERNAL: Translate ADMIN_LOW and ADMIN_HIGH labels to the admin low name and admin high name strings specified in the label_encodings file. If no strings are specified, the strings “ADMIN_LOW” and “ADMIN_HIGH” are used.
NO_CLASSIFICATION: Do not translate classification defined in label.

Return Values

These routines return:

-1: If the label is not of the valid defined required type, if the label is not dominated by the process sensitivity label and the process does not have PRIV_SYS_TRANS_LABEL in its set of effective privileges, or the label_encodings file is inaccessible.
0: If memory cannot be allocated for the return string, or the pre-allocated return string memory is insufficient to hold the string. The value of the pre-allocated string is set to the NULL string (*string[0]='\\00';).
>0: If successful, the length of the character-coded label including the NULL terminator.

PROCESS ATTRIBUTES

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

If memory is allocated by these routines, the caller must free the memory with free() when the memory is no longer in use.

SunOS 5.10 Last Revised 31 May 2006

btohex(3TSOL)

NAME

btohex, bsltoh, bcleartoh, bsltoh_r, bcleartoh_r, h_alloc, h_free – convert binary label to hexadecimal

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bsltoh(const m_label_t *label);

char *bcleartoh(const m_label_t *clearance);

char *bsltoh_r(const m_label_t *label, char *hex);

char *bcleartoh_r(const m_label_t *clearance, char *hex);

char *h_alloc(const unsigned char type);

void h_free(char *hex);

Interface Level

The bsltoh(), bcleartoh(), bsltoh_r(), bcleartoh_r(), h_alloc(), and h_free() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

These functions convert binary labels into hexadecimal strings that represent the internal value.

bsltoh() and bsltoh_r() convert a binary sensitivity label into a string of the form:

[0xsensitivity_label_hexadecimal_value]

bcleartoh() and bcleartoh_r() convert a binary clearance into a string of the form:

0xclearance_hexadecimal_value

h_alloc() allocates memory for the hexadecimal value type for use by bsltoh_r() and bcleartoh_r().

Valid values for type are:

SUN_SL_ID: label is a binary sensitivity label.
SUN_CLR_ID: label is a binary clearance.

h_free() frees memory allocated by h_alloc().

Return Values

These functions return a pointer to a string that contains the result of the translation, or (char *)0 if the parameter is not of the required type.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

For multithreaded applications, the functions bsltoh_r() and bcleartoh_r() should be used.

SunOS 5.10 Last Revised 16 Mar 2006

getdevicerange(3TSOL)

NAME

getdevicerange – get the label range of a device

Synopsis

cc [flag...] file... -lbsm -ltsol [library...]

#include <tsol/label.h>

blrange_t *getdevicerange(const char *device);

Description

The getdevicerange() function returns the label range of a user-allocatable device.

If label range is not specified for device, getdevicerange() returns the default values of ADMIN_LOW for the lower bound and ADMIN_HIGH for the upper bound of device.

From the command line, list_devices(1) can be used to see the label range of device.

Return Values

The getdevicerange() function returns NULL on failure and sets errno. On successful completion, it returns a pointer to a blrange_t structure which must be freed by the caller, as follows:

blrange_t *range;
      ...
      m_label_free(range->lower_bound);
      m_label_free(range->upper_bound);
      free(range);

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
Stability	Evolving
MT-Level	MT-Safe

Errors

The getdevicerange() function fails if:

EAGAIN: There is not enough memory available to allocate the required bytes. The application could try later.
ENOMEM: The physical limits of the system are exceeded by size bytes of memory which cannot be allocated.
ENOTSUP: Invalid upper or lower bound for device.

getpathbylabel(3TSOL)

NAME

getpathbylabel – return the zone pathname

Synopsis

cc [flags...] file... -ltsol

#include <tsol/label.h>

char *getpathbylabel(const char *path, char *resolved_path, size_t bufsize,
     const m_label_t *sl);

Description

getpathbylabel() expands all symbolic links and resolves references to '/./', '/../', extra '/' characters, and stores the zone pathname in the buffer named by resolved_path. The bufsize argument specifies the size in bytes of this buffer. The resulting path will have no symbolic links components, nor any '/./', '/. ./'. This function can only be called from the global zone.

The zone pathname is relative to the sensitivity label sl. To specify a sensitivity label for a zone name which does not exist, the process must assert either the PRIV_FILE_UPGRADE_SL or PRIV_FILE_DOWNGRADE_SL privilege depending on whether the specified sensitivity label dominates or does not dominate the process sensitivity label.

Return Values

getpathbylabel() returns a pointer to the resolved_path on success. On failure, it returns NULL and sets errno to indicate the error.

Errors

EACCES: Search permission is denied for a component of the path prefix of path.
EFAULT: resolved_path extends outside the process's allocated address space or beyond bufsize bytes.
ELOOP: Too many symbolic links were encountered in translating path.
EINVAL: path or resolved_path was NULL, current zone is not the global zone, or sl is invalid.
EIO: An I/O error occurred while reading from or writing to the file system.
ENOENT: The named file does not exist.
ENAMETOOLONG: The length of the path argument exceeds PATH_MAX. A pathname component is longer than NAME_MAX (see sysconf(3C)) while _POSIX_NO_TRUNC is in effect (see pathconf(2)).

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	MT-Safe
Interface Stability	Stable

Warnings

getpathbylabel() indirectly invokes the readlink(2) system call, and hence inherits the possibility of hanging due to inaccessible file system resources.

SunOS 5.10 Last Revised 26 Jun 2006

getplabel(3TSOL)

NAME

getplabel – get process label

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int getplabel(m_label_t *label_p);

Description

getplabel() obtains the sensitivity label of the calling process.

Return Values

getplabel() returns:

0: On success.
-1: On failure, and sets errno to indicate the error. label_p is unchanged.

Errors

getplabel() fails (and label_p does not refer to a valid sensitivity label) if this condition is true:

EFAULT: label_p points to an invalid address.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface Stability	Stable

Notes

This function returns different values for system processes than ucred_getlabel(3C) returns.

SunOS 5.10 Last Revised 16 Mar 2006

getuserrange(3TSOL)

NAME

getuserrange – get the label range of a user

Synopsis

cc [flags...] file... -ltsol

#include <tsol/label.h>

m_range_t *getuserrange(const char *username);

Description

The getuserrange() function returns the label range of username. The lower bound in the range is used as the initial workspace label when a user logs into 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 label_encodings(4). Overriding values for individual users are specified in user_attr(4).

Return Values

The getuserrange() function returns NULL if the memory allocation fails. Otherwise, the function returns a structure which must be freed by the caller, as follows:

m_range_t  *range;
    ...
    m_label_free(range->lower_bound);
    m_label_free(range->upper_bound);
    free(range);

Errors

The getuserrange() function fails if:

ENOMEM: The physical limits of the system are exceeded by size bytes of memory which cannot be allocated.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	MT-Safe
Interface Stability	See NOTES below

Notes

The stability of this function is Stable for systems that implement the Defense Intelligence Agency (DIA) MAC policy of label_encodings(4). Other policies might exist in a future release of Trusted Extensions that might obsolete or supplement label_encodings(4).

SunOS 5.10 Last Revised 16 Mar 2006

getzoneidbylabel(3TSOL)

NAME

getzonelabelbyid, getzonelabelbyname, getzoneidbylabel – map between zones and labels

Synopsis

cc [flags...] file... -ltsol

#include <tsol/label.h>

m_label_t *getzonelabelbyid(zoneid_t zoneid);

m_label_t *getzonelabelbyname(const char *zonename);

zoneid_t *getzoneidbylabel(const m_label_t *label);

Description

The getzonelabelbyid() function returns the mandatory access control (MAC) label of zoneid.

The getzonelabelbyname() function returns the MAC label of the zone whose name is zonename.

The getzoneidbylabel() function returns the zone ID of the zone whose label is label.

All of these functions require that the specified zone's state is at least ZONE_IS_READY. The zone of the calling process must dominate the specified zone's label, or the calling process must be in the global zone.

Return Values

On successful completion, the getzonelabelbyid() and getzonelabelbyname() functions return a pointer to a sensitivity label that is allocated within these functions. To free the storage, use m_label_free(3TSOL). If the zone does not exist, NULL is returned.

On successful completion, the getzoneidbylabel() function returns the zone ID with the matching label. If there is no matching zone, the function returns -1.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	Safe
Interface Stability	Stable

Errors

The getzonelabelbyid() and getzonelabelbyname() functions fail if:

ENOENT: The specified zone does not exist.

The getzonelabelbyid() function fails if:

ENOENT: No zone corresponds to the specified label.

getzonelabelbyid(3TSOL)

NAME

getzonelabelbyid, getzonelabelbyname, getzoneidbylabel – map between zones and labels

Synopsis

cc [flags...] file... -ltsol

#include <tsol/label.h>

m_label_t *getzonelabelbyid(zoneid_t zoneid);

m_label_t *getzonelabelbyname(const char *zonename);

zoneid_t *getzoneidbylabel(const m_label_t *label);

Description

The getzonelabelbyid() function returns the mandatory access control (MAC) label of zoneid.

The getzonelabelbyname() function returns the MAC label of the zone whose name is zonename.

The getzoneidbylabel() function returns the zone ID of the zone whose label is label.

Return Values

On successful completion, the getzoneidbylabel() function returns the zone ID with the matching label. If there is no matching zone, the function returns -1.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	Safe
Interface Stability	Stable

Errors

The getzonelabelbyid() and getzonelabelbyname() functions fail if:

ENOENT: The specified zone does not exist.

The getzonelabelbyid() function fails if:

ENOENT: No zone corresponds to the specified label.

getzonelabelbyname(3TSOL)

NAME

getzonelabelbyid, getzonelabelbyname, getzoneidbylabel – map between zones and labels

Synopsis

cc [flags...] file... -ltsol

#include <tsol/label.h>

m_label_t *getzonelabelbyid(zoneid_t zoneid);

m_label_t *getzonelabelbyname(const char *zonename);

zoneid_t *getzoneidbylabel(const m_label_t *label);

Description

The getzonelabelbyid() function returns the mandatory access control (MAC) label of zoneid.

The getzonelabelbyname() function returns the MAC label of the zone whose name is zonename.

The getzoneidbylabel() function returns the zone ID of the zone whose label is label.

Return Values

On successful completion, the getzoneidbylabel() function returns the zone ID with the matching label. If there is no matching zone, the function returns -1.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	Safe
Interface Stability	Stable

Errors

The getzonelabelbyid() and getzonelabelbyname() functions fail if:

ENOENT: The specified zone does not exist.

The getzonelabelbyid() function fails if:

ENOENT: No zone corresponds to the specified label.

getzonerootbyid(3TSOL)

NAME

getzonerootbyid, getzonerootbylabel, getzonerootbyname – map between zone root pathnames and labels

Synopsis

cc [flags...] file... -ltsol

#include <tsol/label.h>

char *getzonerootbyid(zoneid_t zoneid);

char *getzonerootbylabel(const m_label_t *label);

char *getzonerootbyname(const char *zonename);

Description

The getzonerootbyid() function returns the root pathname of zoneid.

The getzonerootbylabel() function returns the root pathname of the zone whose label is label.

The getzonerootbyname() function returns the root pathname of zonename.

Return Values

On successful completion, the getzonerootbyid(), getzonerootbylabel(), and getzonerootbyname() functions return a pointer to a pathname that is allocated within these functions. To free the storage, use free(3C). On failure, these functions return NULL and set errno to indicate the error.

Errors

EINVAL: zoneid invalid, or zone not found or not ready.
EFAULT: Invalid argument; pointer location is invalid.
ENOMEM: Unable to allocate pathname.
ENOENT: Zone does not exist.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	Safe
Interface Stability	Stable

getzonerootbylabel(3TSOL)

NAME

getzonerootbyid, getzonerootbylabel, getzonerootbyname – map between zone root pathnames and labels

Synopsis

cc [flags...] file... -ltsol

#include <tsol/label.h>

char *getzonerootbyid(zoneid_t zoneid);

char *getzonerootbylabel(const m_label_t *label);

char *getzonerootbyname(const char *zonename);

Description

The getzonerootbyid() function returns the root pathname of zoneid.

The getzonerootbylabel() function returns the root pathname of the zone whose label is label.

The getzonerootbyname() function returns the root pathname of zonename.

Return Values

Errors

EINVAL: zoneid invalid, or zone not found or not ready.
EFAULT: Invalid argument; pointer location is invalid.
ENOMEM: Unable to allocate pathname.
ENOENT: Zone does not exist.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	Safe
Interface Stability	Stable

getzonerootbyname(3TSOL)

NAME

getzonerootbyid, getzonerootbylabel, getzonerootbyname – map between zone root pathnames and labels

Synopsis

cc [flags...] file... -ltsol

#include <tsol/label.h>

char *getzonerootbyid(zoneid_t zoneid);

char *getzonerootbylabel(const m_label_t *label);

char *getzonerootbyname(const char *zonename);

Description

The getzonerootbyid() function returns the root pathname of zoneid.

The getzonerootbylabel() function returns the root pathname of the zone whose label is label.

The getzonerootbyname() function returns the root pathname of zonename.

Return Values

Errors

EINVAL: zoneid invalid, or zone not found or not ready.
EFAULT: Invalid argument; pointer location is invalid.
ENOMEM: Unable to allocate pathname.
ENOENT: Zone does not exist.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	Safe
Interface Stability	Stable

h_alloc(3TSOL)

NAME

btohex, bsltoh, bcleartoh, bsltoh_r, bcleartoh_r, h_alloc, h_free – convert binary label to hexadecimal

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bsltoh(const m_label_t *label);

char *bcleartoh(const m_label_t *clearance);

char *bsltoh_r(const m_label_t *label, char *hex);

char *bcleartoh_r(const m_label_t *clearance, char *hex);

char *h_alloc(const unsigned char type);

void h_free(char *hex);

Interface Level

The bsltoh(), bcleartoh(), bsltoh_r(), bcleartoh_r(), h_alloc(), and h_free() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

These functions convert binary labels into hexadecimal strings that represent the internal value.

bsltoh() and bsltoh_r() convert a binary sensitivity label into a string of the form:

[0xsensitivity_label_hexadecimal_value]

bcleartoh() and bcleartoh_r() convert a binary clearance into a string of the form:

0xclearance_hexadecimal_value

h_alloc() allocates memory for the hexadecimal value type for use by bsltoh_r() and bcleartoh_r().

Valid values for type are:

SUN_SL_ID: label is a binary sensitivity label.
SUN_CLR_ID: label is a binary clearance.

h_free() frees memory allocated by h_alloc().

Return Values

These functions return a pointer to a string that contains the result of the translation, or (char *)0 if the parameter is not of the required type.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

For multithreaded applications, the functions bsltoh_r() and bcleartoh_r() should be used.

SunOS 5.10 Last Revised 16 Mar 2006

hextob(3TSOL)

NAME

hextob, htobsl, htobclear – convert hexadecimal string to binary label

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int htobsl(const char *s, m_label_t *label);

int htobclear(const char *s, m_label_t *clearance);

Interface Level

The htobsl() and htobclear() functions are obsolete. Use the str_to_label(3TSOL) function instead.

Description

These functions convert hexadecimal string representations of internal label values into binary labels.

htobsl() converts into a binary sensitivity label, a hexadecimal string of the form:

0xsensitivity_label_hexadecimal_value

htobclear() converts into a binary clearance, a hexadecimal string of the form:

0xclearance_hexadecimal_value

Return Values

These functions return non-zero if the conversion was successful, otherwise zero is returned.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

SunOS 5.10 Last Revised 31 May 2006

h_free(3TSOL)

NAME

btohex, bsltoh, bcleartoh, bsltoh_r, bcleartoh_r, h_alloc, h_free – convert binary label to hexadecimal

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *bsltoh(const m_label_t *label);

char *bcleartoh(const m_label_t *clearance);

char *bsltoh_r(const m_label_t *label, char *hex);

char *bcleartoh_r(const m_label_t *clearance, char *hex);

char *h_alloc(const unsigned char type);

void h_free(char *hex);

Interface Level

The bsltoh(), bcleartoh(), bsltoh_r(), bcleartoh_r(), h_alloc(), and h_free() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

These functions convert binary labels into hexadecimal strings that represent the internal value.

bsltoh() and bsltoh_r() convert a binary sensitivity label into a string of the form:

[0xsensitivity_label_hexadecimal_value]

bcleartoh() and bcleartoh_r() convert a binary clearance into a string of the form:

0xclearance_hexadecimal_value

h_alloc() allocates memory for the hexadecimal value type for use by bsltoh_r() and bcleartoh_r().

Valid values for type are:

SUN_SL_ID: label is a binary sensitivity label.
SUN_CLR_ID: label is a binary clearance.

h_free() frees memory allocated by h_alloc().

Return Values

These functions return a pointer to a string that contains the result of the translation, or (char *)0 if the parameter is not of the required type.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe with exceptions

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

For multithreaded applications, the functions bsltoh_r() and bcleartoh_r() should be used.

SunOS 5.10 Last Revised 16 Mar 2006

htobclear(3TSOL)

NAME

hextob, htobsl, htobclear – convert hexadecimal string to binary label

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int htobsl(const char *s, m_label_t *label);

int htobclear(const char *s, m_label_t *clearance);

Interface Level

The htobsl() and htobclear() functions are obsolete. Use the str_to_label(3TSOL) function instead.

Description

These functions convert hexadecimal string representations of internal label values into binary labels.

htobsl() converts into a binary sensitivity label, a hexadecimal string of the form:

0xsensitivity_label_hexadecimal_value

htobclear() converts into a binary clearance, a hexadecimal string of the form:

0xclearance_hexadecimal_value

Return Values

These functions return non-zero if the conversion was successful, otherwise zero is returned.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

SunOS 5.10 Last Revised 31 May 2006

htobsl(3TSOL)

NAME

hextob, htobsl, htobclear – convert hexadecimal string to binary label

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int htobsl(const char *s, m_label_t *label);

int htobclear(const char *s, m_label_t *clearance);

Interface Level

The htobsl() and htobclear() functions are obsolete. Use the str_to_label(3TSOL) function instead.

Description

These functions convert hexadecimal string representations of internal label values into binary labels.

htobsl() converts into a binary sensitivity label, a hexadecimal string of the form:

0xsensitivity_label_hexadecimal_value

htobclear() converts into a binary clearance, a hexadecimal string of the form:

0xclearance_hexadecimal_value

Return Values

These functions return non-zero if the conversion was successful, otherwise zero is returned.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

SunOS 5.10 Last Revised 31 May 2006

labelbuilder(3TSOL)

NAME

labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set, tsol_lbuild_destroy – create a Motif-based user interface for interactively building a valid label or clearance

Synopsis

cc [flag...] file... -ltsol -lDtTsol [library...]

#include <Dt/ModLabel.h>

ModLabelData *tsol_lbuild_create(Widget widget void (*event_handler)() ok_callback
     lbuild_attributes extended_operation,  ...., NULL);

void *tsol_lbuild_get(ModLabelData *data, lbuild_attributes extended_operation);

void tsol_lbuild_set(ModLabelData *data lbuild_attributes extended_operation,  ....,
     NULL);

void tsol_lbuild_destroy(ModLabelData *data);

Description

The label builder user interface prompts the end user for information and generates a valid sensitivity label or clearance from the user input based on specifications in the label_encodings(4) file on the system where the application runs. The end user can build the label or clearance by typing a text value or by interactively choosing options.

Application-specific functionality is implemented in the callback for the OK pushbutton. This callback is passed to the tsol_lbuild_create() call where it is mapped to the OK pushbutton widget.

When choosing options, the label builder shows the user only those classifications (and related compartments and markings) dominated by the workspace sensitivity label unless the executable has the PRIV_SYS_TRANS_LABEL privilege in its effective set.

If the end user does not have the authorization to upgrade or downgrade labels, or if the user-built label is out of the user's accreditation range, the OK and Reset pushbuttons are grayed. There are no privileges to override these restrictions.

tsol_lbuild_create() creates the graphical user interface and returns a pointer variable of type ModLabeldata* that contains information on the user interface. This information is a combination of values passed in the tsol_lbuild_create() input parameter list, default values for information not provided, and information on the widgets used by the label builder to create the user interface. All information except the widget information should be accessed with the tsol_lbuild_get() and tsol_lbuild_set() routines.

The widget information is accessed directly by referencing the following fields of the ModLabelData structure.

lbuild_dialog: The label builder dialog box.
ok: The OK pushbutton.
cancel: The Cancel pushbutton.
reset: The Reset pushbutton.
help: The Help pushbutton.

The tsol_lbuild_create() parameter list takes the following values:

widget: The widget from which the dialog box is created. Any Motif widget can be passed.
ok_callback: A callback function that implements the behavior of the OK pushbutton on the dialog box.
..., NULL: A NULL terminated list of extended operations and value pairs that define the characteristics and behavior of the label builder dialog box.

tsol_lbuild_destroy() destroys the ModLabelData structure returned by tsol_lbuild_create().

tsol_lbuild_get() and tsol_lbuild_set() access the information stored in the ModLabelData structure returned by tsol_lbuild_create().

The following extended operations can be passed to tsol_lbuild_create() to build the user interface, to tsol_lbuild_get() to retrieve information on the user interface, and to tsol_lbuild_set() to change the user interface information. All extended operations are valid for tsol_lbuild_get(), but the *WORK* operations are not valid for tsol_lbuild_set() or tsol_lbuild_create() because these values are set from input supplied by the end user. These exceptions are noted in the descriptions.

LBUILD_MODE

Create a user interface to build a sensitivity label or a clearance. Value is LBUILD_MODE_SL by default.

LBUILD_MODE_SL: Build a sensitivity label.
LBUILD_MODE_CLR: Build a clearance.

LBUILD_VALUE_SL

The starting sensitivity label. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_SL.

LBUILD_VALUE_CLR

The starting clearance. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_CLR.

LBUILD_USERFIELD

A character string prompt that displays at the top of the label builder dialog box. Value is NULL by default.

LBUILD_SHOW

Show or hide the label builder dialog box. Value is FALSE by default.

TRUE: Show the label builder dialog box.
FALSE: Hide the label builder dialog box.

LBUILD_TITLE

A character string title that appears at the top of the label builder dialog box. Value is NULL by default.

LBUILD_WORK_SL

Not valid for tsol_lbuild_set() or tsol_lbuild_create(). The sensitivity label the end user is building. Value is updated to the end user's input when the end user selects the Update pushbutton or interactively chooses an option.

LBUILD_WORK_CLR

Not valid for tsol_lbuild_set() or tsol_lbuild_create(). The clearance the end user is building. Value is updated to the end user's input when the end user selects the Update pushbutton or interactively chooses an option.

LBUILD_X

The X position in pixels of the top-left corner of the label builder dialog box in relation to the top-left corner of the screen. By default the label builder dialog box is positioned in the middle of the screen.

LBUILD_Y

The Y position in pixels of the top-left corner of the label builder dialog box in relation to the top-left corner of the screen. By default the label builder dialog box is positioned in the middle of the screen.

LBUILD_LOWER_BOUND

The lowest classification (and related compartments and markings) available to the user as radio buttons for interactively building a label or clearance. This value is the user's minimum label.

LBUILD_UPPER_BOUND

The highest classification (and related compartments and markings) available to the user as radio buttons for interactively building a label or clearance. A supplied value should be within the user's accreditation range. If no value is specified, the value is the user's workspace sensitivity label, or if the executable has the PRIV_SYS_TRANS_LABEL privilege, the value is the user's clearance.

LBUILD_CHECK_AR

Check that the user-built label entered in the Update With field is within the user's accreditation range. A value of 1 means check, and a value of 0 means do not check. If checking is on and the label is out of range, an error message is raised to the end user.

LBUILD_VIEW

Use the internal or external label representation. Value is LBUILD_VIEW_EXTERNAL by default.

LBUILD_VIEW_INTERNAL: Use the internal names for the highest and lowest labels in the system: ADMIN_HIGH and ADMIN_LOW.
LBUILD_VIEW_EXTERNAL: Promote an ADMIN_LOW label to the next highest label, and demote an ADMIN_HIGH label to the next lowest label.

Return Values

The tsol_lbuild_get() returns -1 if it is unable to get the value.

The tsol_lbuild_create() routine returns a variable of type ModLabelData that contains the information provided in the tsol_lbuild_create() input parameter list, default values for information not provided, and information on the widgets used by the label builder to create the user interface.

Examples

Example 1 To Create a Label Builder

(ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
     LBUILD_MODE, LBUILD_MODE_SL,
     LBUILD_TITLE, "Setting Sensitivity Label", 
     LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
     LBUILD_X, 200,
     LBUILD_Y, 200,
     LBUILD_USERFIELD, "Pathname:",
     LBUILD_SHOW, FALSE,
  NULL);

Example 2 To Query the Mode and Display the Label Builder

These examples call the tsol_lbuild_get() routine to query the mode being used, and call the tsol_lbuild_set() routine so the label builder dialog box displays.

mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );

tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE, NULL);

Example 3 To Destroy the ModLabelData Variable

This example destroys the ModLabelData variable returned in the call to tsol_lbuild_create().

tsol_lbuild_destroy(lbldata);

Files

/usr/dt/include/Dt/ModLabel.h: Header file for label builder functions
/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe

labelclipping(3TSOL)

NAME

labelclipping, Xbsltos, Xbcleartos – translate a binary label and clip to the specified width

Synopsis

cc [flag...] file... -ltsol -lDtTsol [library...]

#include <Dt/label_clipping.h>

XmString Xbsltos(Display *display, const m_label_t *senslabel, Dimension width,
     const XmFontList fontlist, const int flags);

XmString Xbcleartos(Display *display, const m_label_t *clearance,
     Dimension width, const XmFontList fontlist, const int flags);

Interface Level

The labelclipping functions, Xbsltos() and Xbcleartos(), are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to translate labels or clearances that dominate the current process' sensitivity label.

display: The structure controlling the connection to an X Window System display.
senslabel: The sensitivity label to be translated.
clearance: The clearance to be translated.
width: The width of the translated label or clearance in pixels. If the specified width is shorter than the full label, the label is clipped and the presence of clipped letters is indicated by an arrow. In this example, letters have been clipped to the right of: TS<-. See the sbltos(3TSOL) man page for more information on the clipped indicator. If the specified width is equal to the display width (display), the label is not truncated, but word-wrapped using a width of half the display width.
fontlist: A list of fonts and character sets where each font is associated with a character set.
flags: The value of flags indicates which words in the label_encodings(4) file are used for the translation. See the bltos(3TSOL) man page for a description of the flag values: LONG_WORDS, SHORT_WORDS, LONG_CLASSIFICATION, SHORT_CLASSIFICATION, ALL_ENTRIES, ACCESS_RELATED, VIEW_EXTERNAL, VIEW_INTERNAL, NO_CLASSIFICATION. BRACKETED is an additional flag that can be used with Xbsltos() only. It encloses the sensitivity label in square brackets as follows: [C].

Return Values

These interfaces return a compound string that represents the character-coded form of the sensitivity label or clearance that is translated. The compound string uses the language and fonts specified in fontlist and is clipped to width. These interfaces return NULL if the label or clearance is not a valid, required type as defined in the label_encodings(4) file, or not dominated by the process' sensitivity label and the PRIV_SYS_TRANS_LABEL privilege is not asserted.

Files

/usr/dt/include/Dt/label_clipping.h: Header file for label clipping functions
/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Examples

Example 1 To Translate and Clip a Clearance

This example translates a clearance to text using the long words specified in the label_encodings(4) file, a font list, and clips the translated clearance to a width of 72 pixels.

xmstr = Xbcleartos(XtDisplay(topLevel), 
&clearance, 72, fontlist, LONG_WORDS

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe

label_to_str(3TSOL)

NAME

label_to_str – convert labels to human readable strings

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int label_to_str(const m_label_t *label, char **string, 
    const m_label_str_t conversion_type, uint_t flags);

Description

label_to_str() is a simple function to convert various mandatory label types to human readable strings.

label is the mandatory label to convert. string points to memory that is allocated by label_to_str() that contains the converted string. The caller is responsible for calling free(3C) to free allocated memory.

The calling process must have mandatory read access to the resulting human readable string. Or the calling process must have the sys_trans_label privilege.

The conversion_type parameter controls the type of label conversion. Not all types of conversion are valid for all types of label:

M_LABEL: Converts label to a human readable string based on its type.
M_INTERNAL: Converts label to an internal text representation that is safe for storing in a public object. Internal conversions can later be parsed to their same value.
M_COLOR: Converts label to a string that represents the color name that the administrator has associated with the label.
PRINTER_TOP_BOTTOM: Converts label to a human readable string that is appropriate for use as the top and bottom label of banner and trailer pages in the Defense Intelligence Agency (DIA) encodings printed output schema.
PRINTER_LABEL: Converts label to a human readable string that is appropriate for use as the banner page downgrade warning in the DIA encodings printed output schema.
PRINTER_CAVEATS: Converts label to a human readable string that is appropriate for use as the banner page caveats section in the DIA encodings printed output schema.
PRINTER_CHANNELS: Converts label to a human readable string that is appropriate for use as the banner page handling channels in the DIA encodings printed output schema.

The flags parameter provides a hint to the label conversion:

DEF_NAMES: The default names are preferred.
SHORT_NAMES: Short names are preferred where defined.
LONG_NAMES: Long names are preferred.

Return Values

Upon successful completion, the label_to_str() function returns zero (0). Otherwise, -1 is returned, errno is set to indicate the error and the string pointer is set to NULL.

Errors

The label_to_str() function fails if:

EINVAL: Invalid parameter.
ENOTSUP: The system does not support label translations.
ENOMEM: The physical limits of the system are exceeded by size bytes of memory which cannot be allocated.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe
Interface Stability	See `NOTES` and `WARNINGS` below

Notes

label_to_str() is Stable. Conversion types that are relative to the DIA encodings schema are Standard. Standard is specified in label_encodings(4). The returned string is Undefined and is dependent on the specific label_encodings file. The conversion type INTERNAL is Unstable, but is always accepted as input to str_to_label(3TSOL).

Warnings

A number of these conversions rely on the DIA label encodings schema. They might not be valid for other label schemata.

SunOS 5.10 Last Revised 28 Feb 2007

m_label(3TSOL)

NAME

m_label, m_label_alloc, m_label_dup, m_label_free – m_label functions

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

m_label_t *m_label_alloc(const m_label_type_t label_type);

int m_label_dup(m_label_t **dst, const m_label_t *src);

void m_label_free(m_label_t *label);

Description

The m_label_alloc() function allocates resources for a new label. label_type defines the type for a newly allocated label. The label type can be:

MAC_LABEL: A Mandatory Access Control (MAC) label.
USER_CLEAR: A user clearance.

The m_label_dup() function allocates resources for a new dst label. The function returns a pointer to the allocated label, which is an exact copy of the src label. The caller is responsible for freeing the allocated resources by calling m_label_free().

The m_label_free() function frees resources that are associated with the previously allocated label.

Return Values

Upon successful completion, the m_label_alloc() function returns a pointer to the newly allocated label. Otherwise, m_label_alloc() returns NULL and errno is set to indicate the error.

Upon successful completion, the m_label_dup() function returns zero (0). Otherwise, -1 is returned and errno is set to indicate the error.

Errors

EINVAL: Invalid parameter.
ENOMEM: The physical limits of the system are exceeded by size bytes of memory which cannot be allocated.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	Safe
Interface Stability	Stable

m_label_alloc(3TSOL)

NAME

m_label, m_label_alloc, m_label_dup, m_label_free – m_label functions

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

m_label_t *m_label_alloc(const m_label_type_t label_type);

int m_label_dup(m_label_t **dst, const m_label_t *src);

void m_label_free(m_label_t *label);

Description

The m_label_alloc() function allocates resources for a new label. label_type defines the type for a newly allocated label. The label type can be:

MAC_LABEL: A Mandatory Access Control (MAC) label.
USER_CLEAR: A user clearance.

The m_label_free() function frees resources that are associated with the previously allocated label.

Return Values

Upon successful completion, the m_label_alloc() function returns a pointer to the newly allocated label. Otherwise, m_label_alloc() returns NULL and errno is set to indicate the error.

Upon successful completion, the m_label_dup() function returns zero (0). Otherwise, -1 is returned and errno is set to indicate the error.

Errors

EINVAL: Invalid parameter.
ENOMEM: The physical limits of the system are exceeded by size bytes of memory which cannot be allocated.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	Safe
Interface Stability	Stable

m_label_dup(3TSOL)

NAME

m_label, m_label_alloc, m_label_dup, m_label_free – m_label functions

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

m_label_t *m_label_alloc(const m_label_type_t label_type);

int m_label_dup(m_label_t **dst, const m_label_t *src);

void m_label_free(m_label_t *label);

Description

The m_label_alloc() function allocates resources for a new label. label_type defines the type for a newly allocated label. The label type can be:

MAC_LABEL: A Mandatory Access Control (MAC) label.
USER_CLEAR: A user clearance.

The m_label_free() function frees resources that are associated with the previously allocated label.

Return Values

Upon successful completion, the m_label_alloc() function returns a pointer to the newly allocated label. Otherwise, m_label_alloc() returns NULL and errno is set to indicate the error.

Upon successful completion, the m_label_dup() function returns zero (0). Otherwise, -1 is returned and errno is set to indicate the error.

Errors

EINVAL: Invalid parameter.
ENOMEM: The physical limits of the system are exceeded by size bytes of memory which cannot be allocated.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	Safe
Interface Stability	Stable

m_label_free(3TSOL)

NAME

m_label, m_label_alloc, m_label_dup, m_label_free – m_label functions

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

m_label_t *m_label_alloc(const m_label_type_t label_type);

int m_label_dup(m_label_t **dst, const m_label_t *src);

void m_label_free(m_label_t *label);

Description

The m_label_alloc() function allocates resources for a new label. label_type defines the type for a newly allocated label. The label type can be:

MAC_LABEL: A Mandatory Access Control (MAC) label.
USER_CLEAR: A user clearance.

The m_label_free() function frees resources that are associated with the previously allocated label.

Return Values

Upon successful completion, the m_label_alloc() function returns a pointer to the newly allocated label. Otherwise, m_label_alloc() returns NULL and errno is set to indicate the error.

Upon successful completion, the m_label_dup() function returns zero (0). Otherwise, -1 is returned and errno is set to indicate the error.

Errors

EINVAL: Invalid parameter.
ENOMEM: The physical limits of the system are exceeded by size bytes of memory which cannot be allocated.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	Safe
Interface Stability	Stable

sbcleartos(3TSOL)

NAME

sbltos, sbsltos, sbcleartos – translate binary labels to canonical character-coded labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *sbsltos(const m_label_t *label, const int len);

char *sbcleartos(const m_label_t *clearance, const int len);

Interface Level

The sbsltos() and sbcleartos() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on labels that dominate the current process's sensitivity label.

These functions translate binary labels into canonical strings that are clipped to the number of printable characters specified in len. Clipping is required if the number of characters of the translated string is greater than len. Clipping is done by truncating the label on the right to two characters less than the specified number of characters. A clipped indicator, “<-”, is appended to sensitivity labels and clearances. The character-coded label begins with a classification name separated with a single space character from the list of words making up the remainder of the label. The binary labels must be of the proper defined type and dominated by the process's sensitivity label. A len of 0 (zero) returns the entire string with no clipping.

sbsltos() translates a binary sensitivity label into a clipped string using the long form of the words and the short form of the classification name. If len is less than the minimum number of characters (three), the translation fails.

sbcleartos() translates a binary clearance into a clipped string using the long form of the words and the short form of the classification name. If len is less than the minimum number of characters (three), the translation fails. The translation of a clearance might not be the same as the translation of a sensitivity label. These functions use different tables of the label_encodings file which might contain different words and constraints.

Return Values

These routines return a pointer to a statically allocated string that contains the result of the translation, or (char *)0 if the translation fails for any reason.

Examples

`sbsltos()`

Assume that a sensitivity label is:

UN TOP/MIDDLE/LOWER DRAWER

When clipped to ten characters it is:

UN TOP/M<-

`sbcleartos()`

Assume that a clearance is:

UN TOP/MIDDLE/LOWER DRAWER

When clipped to ten characters it is:

UN TOP/M<-

PROCESS ATTRIBUTES

If the VIEW_EXTERNAL or VIEW_INTERNAL flags are not specified, translation of ADMIN_LOW and ADMIN_HIGH labels is controlled by the label view process attribute flags. If no label view process attribute flags are defined, their translation is controlled by the label view configured in the label_encodings file. A value of External specifies that ADMIN_LOW and ADMIN_HIGH labels are mapped to the lowest and highest labels defined in the label_encodings file. A value of Internal specifies that the ADMIN_LOW and ADMIN_HIGH labels are translated to the admin low name and admin high name strings specified in the label_encodings file. If no such names are specified, the strings “ADMIN_LOW” and “ADMIN_HIGH” are used.

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability	Obsolete
MT-Level	Unsafe

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

Warnings

All these functions share the same statically allocated string storage. They are not MT-Safe. Subsequent calls to any of these functions will overwrite that string with the newly translated string.

SunOS 5.10 Last Revised 31 May 2006

sbltos(3TSOL)

NAME

sbltos, sbsltos, sbcleartos – translate binary labels to canonical character-coded labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *sbsltos(const m_label_t *label, const int len);

char *sbcleartos(const m_label_t *clearance, const int len);

Interface Level

The sbsltos() and sbcleartos() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on labels that dominate the current process's sensitivity label.

Return Values

These routines return a pointer to a statically allocated string that contains the result of the translation, or (char *)0 if the translation fails for any reason.

Examples

`sbsltos()`

Assume that a sensitivity label is:

UN TOP/MIDDLE/LOWER DRAWER

When clipped to ten characters it is:

UN TOP/M<-

`sbcleartos()`

Assume that a clearance is:

UN TOP/MIDDLE/LOWER DRAWER

When clipped to ten characters it is:

UN TOP/M<-

PROCESS ATTRIBUTES

If the VIEW_EXTERNAL or VIEW_INTERNAL flags are not specified, translation of ADMIN_LOW and ADMIN_HIGH labels is controlled by the label view process attribute flags. If no label view process attribute flags are defined, their translation is controlled by the label view configured in the label_encodings file. A value of External specifies that ADMIN_LOW and ADMIN_HIGH labels are mapped to the lowest and highest labels defined in the label_encodings file. A value of Internal specifies that the ADMIN_LOW and ADMIN_HIGH labels are translated to the admin low name and admin high name strings specified in the label_encodings file. If no such names are specified, the strings “ADMIN_LOW” and “ADMIN_HIGH” are used.

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability	Obsolete
MT-Level	Unsafe

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

Warnings

All these functions share the same statically allocated string storage. They are not MT-Safe. Subsequent calls to any of these functions will overwrite that string with the newly translated string.

SunOS 5.10 Last Revised 31 May 2006

sbsltos(3TSOL)

NAME

sbltos, sbsltos, sbcleartos – translate binary labels to canonical character-coded labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

char *sbsltos(const m_label_t *label, const int len);

char *sbcleartos(const m_label_t *clearance, const int len);

Interface Level

The sbsltos() and sbcleartos() functions are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on labels that dominate the current process's sensitivity label.

Return Values

These routines return a pointer to a statically allocated string that contains the result of the translation, or (char *)0 if the translation fails for any reason.

Examples

`sbsltos()`

Assume that a sensitivity label is:

UN TOP/MIDDLE/LOWER DRAWER

When clipped to ten characters it is:

UN TOP/M<-

`sbcleartos()`

Assume that a clearance is:

UN TOP/MIDDLE/LOWER DRAWER

When clipped to ten characters it is:

UN TOP/M<-

PROCESS ATTRIBUTES

If the VIEW_EXTERNAL or VIEW_INTERNAL flags are not specified, translation of ADMIN_LOW and ADMIN_HIGH labels is controlled by the label view process attribute flags. If no label view process attribute flags are defined, their translation is controlled by the label view configured in the label_encodings file. A value of External specifies that ADMIN_LOW and ADMIN_HIGH labels are mapped to the lowest and highest labels defined in the label_encodings file. A value of Internal specifies that the ADMIN_LOW and ADMIN_HIGH labels are translated to the admin low name and admin high name strings specified in the label_encodings file. If no such names are specified, the strings “ADMIN_LOW” and “ADMIN_HIGH” are used.

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability	Obsolete
MT-Level	Unsafe

Notes

These functions are obsolete and retained for ease of porting. They might be removed in a future Solaris Trusted Extensions release.

Warnings

All these functions share the same statically allocated string storage. They are not MT-Safe. Subsequent calls to any of these functions will overwrite that string with the newly translated string.

SunOS 5.10 Last Revised 31 May 2006

setflabel(3TSOL)

NAME

setflabel – move file to zone with corresponding sensitivity label

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int setflabel(const char *path, const m_label_t *label_p);

Description

The file that is named by path is relabeled by moving it to a new pathname relative to the root directory of the zone corresponding to label_p. If the source and destination file systems are loopback mounted from the same underlying file system, the file is renamed. Otherwise, the file is copied and removed from the source directory.

The following policy checks are enforced by this function:

If the sensitivity label of label_p equals the existing sensitivity label, then the file is not moved.
If the corresponding directory does not exist in the destination zone, or if the directory exists, but has a different label than label_p, the file is not moved. Also, if the file already exists in the destination directory, the file is not moved.
If the sensitivity label of the existing file is not equal to the calling process label and the caller is not in the global zone, then the file is not moved. If the caller is in the global zone, the existing file label must be in a labeled zone (not ADMIN_LOW or ADMIN_HIGH).
If the calling process does not have write access to both the source and destination directories, then the calling process must have PRIV_FILE_DAC_WRITE in its set of effective privileges.
If the sensitivity label of label_p provides read only access to the existing sensitivity label (an upgrade), then the user must have the solaris.label.file.upgrade authorization. In addition, if the current zone is a labeled zone, then it must have been assigned the privilege PRIV_FILE_UPGRADE_SL when the zone was configured.
If the sensitivity label of label_p does not provide access to the existing sensitivity label (a downgrade), then the calling user must have the solaris.label.file.downgrade authorization. In addition, if the current zone is a labeled zone, then it must have been assigned the privilege PRIV_FILE_DOWNGRADE_SL when the zone was configured.
If the calling process is not in the global zone, and the user does not have the solaris.label.range authorization, then label_p must be within the user's label range and within the system accreditation range.
If the existing file is in use (not tranquil) it is not moved. This tranquility check does not cover race conditions nor remote file access.

Additional policy constraints can be implemented by customizing the shell script /etc/security/tsol/relabel. See the comments in this file.

Return Values

setflabel() returns:

0: On success.
-1: On failure, and sets errno to indicate the error.

Errors

setflabel() fails and the file is unchanged if any of these conditions prevails:

EACCES

Search permission is denied for a component of the path prefix of path.

The calling process does not have mandatory write access to the final component of path because the sensitivity label of the final component of path does not dominate the sensitivity label of the calling process and the calling process does not have PRIV_FILE_MAC_WRITE in its set of effective privileges.

EBUSY

There is an open file descriptor reference to the final component of path.

ECONNREFUSED

A connection to the label daemon could not be established.

EEXIST

A file with the same name exists in the destination directory.

EINVAL

Improper parameters were received by the label daemon.

EISDIR

The existing file is a directory.

ELOOP

Too many symbolic links were encountered in translating path.

EMLINK

The existing file is hardlinked to another file.

ENAMETOOLONG

The length of the path argument exceeds PATH_MAX.

ENOENT

The file referred to by path does not exist.

EROFS

The file system is read-only or its label is ADMIN_LOW or ADMIN_HIGH.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcslr
MT-Level	MT-Safe
Interface Stability	Stable

stobclear(3TSOL)

NAME

stobl, stobsl, stobclear – translate character-coded labels to binary labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int stobsl(const char *string, m_label_t *label, const int flags, int *error);

int stobclear(const char *string, m_label_t *clearance, const int flags,
     int *error);

Interface Level

The stobsl() and stobclear() functions are obsolete. Use the str_to_label(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on character-coded labels that dominate the process's sensitivity label.

The stobl functions translate character-coded labels into binary labels. They also modify an existing binary label by incrementing or decrementing it to produce a new binary label relative to its existing value.

The generic form of an input character-coded label string is:

[  +  ] classification name ] [ [  + | - ] word ...

Leading and trailing white space is ignored. Fields are separated by white space, a `/' (slash), or a `,' (comma). Case is irrelevant. If string starts with + or -, string is interpreted a modification to an existing label. If string starts with a classification name followed by a + or -, the new classification is used and the rest of the old label is retained and modified as specified by string. + modifies an existing label by adding words. - modifies an existing label by removing words. To the maximum extent possible, errors in string are corrected in the resulting binary label label.

The stobl functions also translate hexadecimal label representations into binary labels (see hextob(3TSOL)) when the string starts with 0x and either NEW_LABEL or NO_CORRECTION is specified in flags.

flags can be the following:

NEW_LABEL: label contents is not used, is formatted as a label of the relevant type, and is assumed to be ADMIN_LOW for modification changes. If NEW_LABEL is not present, label is validated as a defined label of the correct type dominated by the process's sensitivity label.
NO_CORRECTION: No corrections are made if there are errors in the character-coded label string. string must be complete and contain all the label components that are required by the label_encodings file. The NO_CORRECTION flag implies the NEW_LABEL flag.
0 (zero): The default action is taken.

error is a return parameter that is set only if the function is unsuccessful.

stobsl() translates the character-coded sensitivity label string into a binary sensitivity label and places the result in the return parameter label.

flags can be either NEW_LABEL, NO_CORRECTION, or 0 (zero). Unless NO_CORRECTION is specified, this translation forces the label to dominate the minimum classification, and initial compartments set that is specified in the label_encodings file and corrects the label to include other label components required by the label_encodings file, but not present in string.

stobclear() translates the character-coded clearance string into a binary clearance and places the result in the return parameter clearance.

flags can be either NEW_LABEL, NO_CORRECTION, or 0 (zero). Unless NO_CORRECTION is specified, this translation forces the label to dominate the minimum classification, and initial compartments set that is specified in the label_encodings file and corrects the label to include other label components that are required by the label_encodings file, but not present in string. The translation of a clearance might not be the same as the translation of a sensitivity label. These functions use different tables of the label_encodings file that might contain different words and constraints.

Return Values

These functions return:

1: If the translation was successful and a valid binary label was returned.
0: If an error occurred. error indicates the type of error.

Errors

When these functions return zero, error contains one of the following values:

-1: Unable to access the label_encodings file.
0: The label label is not valid for this translation and the NEW_LABEL or NO_CORRECTION flag was not specified, or the label label is not dominated by the process's sensitivity label and the process does not have PRIV_SYS_TRANS_LABEL in its set of effective privileges.
>0: The character-coded label string is in error. error is a one-based index into string indicating where the translation error occurred.

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe

Notes

These functions are obsolete and are retained for ease of porting. They might be removed in a future release of Solaris Trusted Extensions.

In addition to the ADMIN_LOW name and ADMIN_HIGH name strings defined in the label_encodings file, the strings “ADMIN_LOW” and “ADMIN_HIGH” are always accepted as character-coded labels to be translated to the appropriate ADMIN_LOW and ADMIN_HIGH label, respectively.

Modifying an existing ADMIN_LOW label acts as the specification of a NEW_LABEL and forces the label to start at the minimum label that is specified in the label_encodings file.

Modifying an existing ADMIN_HIGH label is treated as an attempt to change a label that represents the highest defined classification and all the defined compartments that are specified in the label_encodings file.

The NO_CORRECTION flag is used when the character-coded label must be complete and accurate so that translation to and from the binary form results in an equivalent character-coded label.

SunOS 5.10 Last Revised 16 March 2006

stobl(3TSOL)

NAME

stobl, stobsl, stobclear – translate character-coded labels to binary labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int stobsl(const char *string, m_label_t *label, const int flags, int *error);

int stobclear(const char *string, m_label_t *clearance, const int flags,
     int *error);

Interface Level

The stobsl() and stobclear() functions are obsolete. Use the str_to_label(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on character-coded labels that dominate the process's sensitivity label.

The generic form of an input character-coded label string is:

[  +  ] classification name ] [ [  + | - ] word ...

flags can be the following:

NEW_LABEL: label contents is not used, is formatted as a label of the relevant type, and is assumed to be ADMIN_LOW for modification changes. If NEW_LABEL is not present, label is validated as a defined label of the correct type dominated by the process's sensitivity label.
NO_CORRECTION: No corrections are made if there are errors in the character-coded label string. string must be complete and contain all the label components that are required by the label_encodings file. The NO_CORRECTION flag implies the NEW_LABEL flag.
0 (zero): The default action is taken.

error is a return parameter that is set only if the function is unsuccessful.

stobsl() translates the character-coded sensitivity label string into a binary sensitivity label and places the result in the return parameter label.

stobclear() translates the character-coded clearance string into a binary clearance and places the result in the return parameter clearance.

Return Values

These functions return:

1: If the translation was successful and a valid binary label was returned.
0: If an error occurred. error indicates the type of error.

Errors

When these functions return zero, error contains one of the following values:

-1: Unable to access the label_encodings file.
0: The label label is not valid for this translation and the NEW_LABEL or NO_CORRECTION flag was not specified, or the label label is not dominated by the process's sensitivity label and the process does not have PRIV_SYS_TRANS_LABEL in its set of effective privileges.
>0: The character-coded label string is in error. error is a one-based index into string indicating where the translation error occurred.

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe

Notes

These functions are obsolete and are retained for ease of porting. They might be removed in a future release of Solaris Trusted Extensions.

Modifying an existing ADMIN_LOW label acts as the specification of a NEW_LABEL and forces the label to start at the minimum label that is specified in the label_encodings file.

The NO_CORRECTION flag is used when the character-coded label must be complete and accurate so that translation to and from the binary form results in an equivalent character-coded label.

SunOS 5.10 Last Revised 16 March 2006

stobsl(3TSOL)

NAME

stobl, stobsl, stobclear – translate character-coded labels to binary labels

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int stobsl(const char *string, m_label_t *label, const int flags, int *error);

int stobclear(const char *string, m_label_t *clearance, const int flags,
     int *error);

Interface Level

The stobsl() and stobclear() functions are obsolete. Use the str_to_label(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to perform label translation on character-coded labels that dominate the process's sensitivity label.

The generic form of an input character-coded label string is:

[  +  ] classification name ] [ [  + | - ] word ...

flags can be the following:

NEW_LABEL: label contents is not used, is formatted as a label of the relevant type, and is assumed to be ADMIN_LOW for modification changes. If NEW_LABEL is not present, label is validated as a defined label of the correct type dominated by the process's sensitivity label.
NO_CORRECTION: No corrections are made if there are errors in the character-coded label string. string must be complete and contain all the label components that are required by the label_encodings file. The NO_CORRECTION flag implies the NEW_LABEL flag.
0 (zero): The default action is taken.

error is a return parameter that is set only if the function is unsuccessful.

stobsl() translates the character-coded sensitivity label string into a binary sensitivity label and places the result in the return parameter label.

stobclear() translates the character-coded clearance string into a binary clearance and places the result in the return parameter clearance.

Return Values

These functions return:

1: If the translation was successful and a valid binary label was returned.
0: If an error occurred. error indicates the type of error.

Errors

When these functions return zero, error contains one of the following values:

-1: Unable to access the label_encodings file.
0: The label label is not valid for this translation and the NEW_LABEL or NO_CORRECTION flag was not specified, or the label label is not dominated by the process's sensitivity label and the process does not have PRIV_SYS_TRANS_LABEL in its set of effective privileges.
>0: The character-coded label string is in error. error is a one-based index into string indicating where the translation error occurred.

Files

/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
Stability Level	Obsolete
MT-Level	MT-Safe

Notes

These functions are obsolete and are retained for ease of porting. They might be removed in a future release of Solaris Trusted Extensions.

Modifying an existing ADMIN_LOW label acts as the specification of a NEW_LABEL and forces the label to start at the minimum label that is specified in the label_encodings file.

The NO_CORRECTION flag is used when the character-coded label must be complete and accurate so that translation to and from the binary form results in an equivalent character-coded label.

SunOS 5.10 Last Revised 16 March 2006

str_to_label(3TSOL)

NAME

str_to_label – parse human readable strings to label

Synopsis

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int str_to_label(const char *string, m_label_t **label, 
    const m_label_type_t label_type, uint_t flags, int *error);

Description

str_to_label() is a simple function to parse human readable strings into labels of the requested type.

string is the string to parse. If string is the result of a label_to_str() conversion of type M_INTERNAL, flags are ignored, and any previously parsed label is replaced.

If *label is NULL, str_to_label() allocates resources for label and initializes the label to the label_type that was requested before parsing string.

If *label is not NULL, the label is a pointer to a mandatory label that is the result of a previously parsed label and label_type is ignored. The type that is used for parsing is derived from label for any type-sensitive operations.

If flags is L_MODIFY_EXISTING, the parsed string can be used to modify this label.

If flags is L_NO_CORRECTION, the previously parsed label is replaced and the parsing algorithm does not attempt to infer missing elements from string to compose a valid label.

If flags is L_DEFAULT, the previously parsed label is replaced and the parsing algorithm makes a best effort to imply a valid label from the elements of string.

The caller is responsible for freeing the allocated resources by calling the m_label_free() function. label_type defines the type for a newly allocated label. The label type can be:

MAC_LABEL: The string should be translated as a Mandatory Access Control (MAC) label.
USER_CLEAR: The string should be translated as a label that represents the least upper bound of the labels that the user is allowed to access.

If error is NULL, do not return additional error information for EINVAL. The calling process must have mandatory read access to label and human readable string. Or the calling process must have the sys_trans_label privilege.

The manifest constants ADMIN_HIGH and ADMIN_LOW are the human readable strings that correspond to the Trusted Extensions policy admin_high and admin_low label values. See labels(5).

Return Values

Upon successful completion, the str_to_label() function returns zero (0). Otherwise, -1 is returned, errno is set to indicate the error, and error provides additional information for EINVAL. Otherwise, error is a zero-based index to the string parse failure point.

Errors

The str_to_label() function fails if:

EINVAL: Invalid parameter. M_BAD_STRING indicates that string could not be parsed. M_BAD_LABEL indicates that the label passed in was in error.
ENOTSUP: The system does not support label translations.
ENOMEM: The physical limits of the system are exceeded by size bytes of memory which cannot be allocated.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe
Interface Stability	See `NOTES` and `WARNINGS` below

Notes

str_to_label() is Stable. Parsing types that are relative to Defense Intelligence Agency (DIA) encodings schema are Standard. Standard is specified in label_encodings(4).

Warnings

A number of the parsing rules rely on the DIA label encodings schema. The rules might not be valid for other label schemata.

SunOS 5.10 Last Revised 31 May 2006

tsol_getrhtype(3TSOL)

NAME

tsol_getrhtype – get trusted network host type

Synopsis

cc [flag...] file... -ltsnet [library...]

#include <libtsnet.h>

tsol_host_type_t tsol_getrhtype(char *hostname);

Description

The tsol_getrhtype() function queries the kernel-level network information to determine the host type that is associated with the specified hostname. The hostname can be a regular hostname, an IP address, or a network wildcard address.

Return Values

The returned value will be one of the enumerated types that is defined in the tsol_host_type_t typedef. Currently these types are UNLABELED and SUN_CIPSO.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsl
MT-Level	MT-Safe

Files

/etc/security/tsol/tnrhdb: Trusted network remote-host database

tsol_lbuild_create(3TSOL)

NAME

labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set, tsol_lbuild_destroy – create a Motif-based user interface for interactively building a valid label or clearance

Synopsis

cc [flag...] file... -ltsol -lDtTsol [library...]

#include <Dt/ModLabel.h>

ModLabelData *tsol_lbuild_create(Widget widget void (*event_handler)() ok_callback
     lbuild_attributes extended_operation,  ...., NULL);

void *tsol_lbuild_get(ModLabelData *data, lbuild_attributes extended_operation);

void tsol_lbuild_set(ModLabelData *data lbuild_attributes extended_operation,  ....,
     NULL);

void tsol_lbuild_destroy(ModLabelData *data);

Description

Application-specific functionality is implemented in the callback for the OK pushbutton. This callback is passed to the tsol_lbuild_create() call where it is mapped to the OK pushbutton widget.

The widget information is accessed directly by referencing the following fields of the ModLabelData structure.

lbuild_dialog: The label builder dialog box.
ok: The OK pushbutton.
cancel: The Cancel pushbutton.
reset: The Reset pushbutton.
help: The Help pushbutton.

The tsol_lbuild_create() parameter list takes the following values:

widget: The widget from which the dialog box is created. Any Motif widget can be passed.
ok_callback: A callback function that implements the behavior of the OK pushbutton on the dialog box.
..., NULL: A NULL terminated list of extended operations and value pairs that define the characteristics and behavior of the label builder dialog box.

tsol_lbuild_destroy() destroys the ModLabelData structure returned by tsol_lbuild_create().

tsol_lbuild_get() and tsol_lbuild_set() access the information stored in the ModLabelData structure returned by tsol_lbuild_create().

LBUILD_MODE

Create a user interface to build a sensitivity label or a clearance. Value is LBUILD_MODE_SL by default.

LBUILD_MODE_SL: Build a sensitivity label.
LBUILD_MODE_CLR: Build a clearance.

LBUILD_VALUE_SL

The starting sensitivity label. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_SL.

LBUILD_VALUE_CLR

The starting clearance. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_CLR.

LBUILD_USERFIELD

A character string prompt that displays at the top of the label builder dialog box. Value is NULL by default.

LBUILD_SHOW

Show or hide the label builder dialog box. Value is FALSE by default.

TRUE: Show the label builder dialog box.
FALSE: Hide the label builder dialog box.

LBUILD_TITLE

A character string title that appears at the top of the label builder dialog box. Value is NULL by default.

LBUILD_WORK_SL

LBUILD_WORK_CLR

LBUILD_X

LBUILD_Y

LBUILD_LOWER_BOUND

The lowest classification (and related compartments and markings) available to the user as radio buttons for interactively building a label or clearance. This value is the user's minimum label.

LBUILD_UPPER_BOUND

LBUILD_CHECK_AR

LBUILD_VIEW

Use the internal or external label representation. Value is LBUILD_VIEW_EXTERNAL by default.

LBUILD_VIEW_INTERNAL: Use the internal names for the highest and lowest labels in the system: ADMIN_HIGH and ADMIN_LOW.
LBUILD_VIEW_EXTERNAL: Promote an ADMIN_LOW label to the next highest label, and demote an ADMIN_HIGH label to the next lowest label.

Return Values

The tsol_lbuild_get() returns -1 if it is unable to get the value.

Examples

Example 1 To Create a Label Builder

(ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
     LBUILD_MODE, LBUILD_MODE_SL,
     LBUILD_TITLE, "Setting Sensitivity Label", 
     LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
     LBUILD_X, 200,
     LBUILD_Y, 200,
     LBUILD_USERFIELD, "Pathname:",
     LBUILD_SHOW, FALSE,
  NULL);

Example 2 To Query the Mode and Display the Label Builder

These examples call the tsol_lbuild_get() routine to query the mode being used, and call the tsol_lbuild_set() routine so the label builder dialog box displays.

mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );

tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE, NULL);

Example 3 To Destroy the ModLabelData Variable

This example destroys the ModLabelData variable returned in the call to tsol_lbuild_create().

tsol_lbuild_destroy(lbldata);

Files

/usr/dt/include/Dt/ModLabel.h: Header file for label builder functions
/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe

tsol_lbuild_destroy(3TSOL)

NAME

labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set, tsol_lbuild_destroy – create a Motif-based user interface for interactively building a valid label or clearance

Synopsis

cc [flag...] file... -ltsol -lDtTsol [library...]

#include <Dt/ModLabel.h>

ModLabelData *tsol_lbuild_create(Widget widget void (*event_handler)() ok_callback
     lbuild_attributes extended_operation,  ...., NULL);

void *tsol_lbuild_get(ModLabelData *data, lbuild_attributes extended_operation);

void tsol_lbuild_set(ModLabelData *data lbuild_attributes extended_operation,  ....,
     NULL);

void tsol_lbuild_destroy(ModLabelData *data);

Description

Application-specific functionality is implemented in the callback for the OK pushbutton. This callback is passed to the tsol_lbuild_create() call where it is mapped to the OK pushbutton widget.

The widget information is accessed directly by referencing the following fields of the ModLabelData structure.

lbuild_dialog: The label builder dialog box.
ok: The OK pushbutton.
cancel: The Cancel pushbutton.
reset: The Reset pushbutton.
help: The Help pushbutton.

The tsol_lbuild_create() parameter list takes the following values:

widget: The widget from which the dialog box is created. Any Motif widget can be passed.
ok_callback: A callback function that implements the behavior of the OK pushbutton on the dialog box.
..., NULL: A NULL terminated list of extended operations and value pairs that define the characteristics and behavior of the label builder dialog box.

tsol_lbuild_destroy() destroys the ModLabelData structure returned by tsol_lbuild_create().

tsol_lbuild_get() and tsol_lbuild_set() access the information stored in the ModLabelData structure returned by tsol_lbuild_create().

LBUILD_MODE

Create a user interface to build a sensitivity label or a clearance. Value is LBUILD_MODE_SL by default.

LBUILD_MODE_SL: Build a sensitivity label.
LBUILD_MODE_CLR: Build a clearance.

LBUILD_VALUE_SL

The starting sensitivity label. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_SL.

LBUILD_VALUE_CLR

The starting clearance. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_CLR.

LBUILD_USERFIELD

A character string prompt that displays at the top of the label builder dialog box. Value is NULL by default.

LBUILD_SHOW

Show or hide the label builder dialog box. Value is FALSE by default.

TRUE: Show the label builder dialog box.
FALSE: Hide the label builder dialog box.

LBUILD_TITLE

A character string title that appears at the top of the label builder dialog box. Value is NULL by default.

LBUILD_WORK_SL

LBUILD_WORK_CLR

LBUILD_X

LBUILD_Y

LBUILD_LOWER_BOUND

The lowest classification (and related compartments and markings) available to the user as radio buttons for interactively building a label or clearance. This value is the user's minimum label.

LBUILD_UPPER_BOUND

LBUILD_CHECK_AR

LBUILD_VIEW

Use the internal or external label representation. Value is LBUILD_VIEW_EXTERNAL by default.

LBUILD_VIEW_INTERNAL: Use the internal names for the highest and lowest labels in the system: ADMIN_HIGH and ADMIN_LOW.
LBUILD_VIEW_EXTERNAL: Promote an ADMIN_LOW label to the next highest label, and demote an ADMIN_HIGH label to the next lowest label.

Return Values

The tsol_lbuild_get() returns -1 if it is unable to get the value.

Examples

Example 1 To Create a Label Builder

(ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
     LBUILD_MODE, LBUILD_MODE_SL,
     LBUILD_TITLE, "Setting Sensitivity Label", 
     LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
     LBUILD_X, 200,
     LBUILD_Y, 200,
     LBUILD_USERFIELD, "Pathname:",
     LBUILD_SHOW, FALSE,
  NULL);

Example 2 To Query the Mode and Display the Label Builder

These examples call the tsol_lbuild_get() routine to query the mode being used, and call the tsol_lbuild_set() routine so the label builder dialog box displays.

mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );

tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE, NULL);

Example 3 To Destroy the ModLabelData Variable

This example destroys the ModLabelData variable returned in the call to tsol_lbuild_create().

tsol_lbuild_destroy(lbldata);

Files

/usr/dt/include/Dt/ModLabel.h: Header file for label builder functions
/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe

tsol_lbuild_get(3TSOL)

NAME

labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set, tsol_lbuild_destroy – create a Motif-based user interface for interactively building a valid label or clearance

Synopsis

cc [flag...] file... -ltsol -lDtTsol [library...]

#include <Dt/ModLabel.h>

ModLabelData *tsol_lbuild_create(Widget widget void (*event_handler)() ok_callback
     lbuild_attributes extended_operation,  ...., NULL);

void *tsol_lbuild_get(ModLabelData *data, lbuild_attributes extended_operation);

void tsol_lbuild_set(ModLabelData *data lbuild_attributes extended_operation,  ....,
     NULL);

void tsol_lbuild_destroy(ModLabelData *data);

Description

Application-specific functionality is implemented in the callback for the OK pushbutton. This callback is passed to the tsol_lbuild_create() call where it is mapped to the OK pushbutton widget.

The widget information is accessed directly by referencing the following fields of the ModLabelData structure.

lbuild_dialog: The label builder dialog box.
ok: The OK pushbutton.
cancel: The Cancel pushbutton.
reset: The Reset pushbutton.
help: The Help pushbutton.

The tsol_lbuild_create() parameter list takes the following values:

widget: The widget from which the dialog box is created. Any Motif widget can be passed.
ok_callback: A callback function that implements the behavior of the OK pushbutton on the dialog box.
..., NULL: A NULL terminated list of extended operations and value pairs that define the characteristics and behavior of the label builder dialog box.

tsol_lbuild_destroy() destroys the ModLabelData structure returned by tsol_lbuild_create().

tsol_lbuild_get() and tsol_lbuild_set() access the information stored in the ModLabelData structure returned by tsol_lbuild_create().

LBUILD_MODE

Create a user interface to build a sensitivity label or a clearance. Value is LBUILD_MODE_SL by default.

LBUILD_MODE_SL: Build a sensitivity label.
LBUILD_MODE_CLR: Build a clearance.

LBUILD_VALUE_SL

The starting sensitivity label. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_SL.

LBUILD_VALUE_CLR

The starting clearance. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_CLR.

LBUILD_USERFIELD

A character string prompt that displays at the top of the label builder dialog box. Value is NULL by default.

LBUILD_SHOW

Show or hide the label builder dialog box. Value is FALSE by default.

TRUE: Show the label builder dialog box.
FALSE: Hide the label builder dialog box.

LBUILD_TITLE

A character string title that appears at the top of the label builder dialog box. Value is NULL by default.

LBUILD_WORK_SL

LBUILD_WORK_CLR

LBUILD_X

LBUILD_Y

LBUILD_LOWER_BOUND

The lowest classification (and related compartments and markings) available to the user as radio buttons for interactively building a label or clearance. This value is the user's minimum label.

LBUILD_UPPER_BOUND

LBUILD_CHECK_AR

LBUILD_VIEW

Use the internal or external label representation. Value is LBUILD_VIEW_EXTERNAL by default.

LBUILD_VIEW_INTERNAL: Use the internal names for the highest and lowest labels in the system: ADMIN_HIGH and ADMIN_LOW.
LBUILD_VIEW_EXTERNAL: Promote an ADMIN_LOW label to the next highest label, and demote an ADMIN_HIGH label to the next lowest label.

Return Values

The tsol_lbuild_get() returns -1 if it is unable to get the value.

Examples

Example 1 To Create a Label Builder

(ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
     LBUILD_MODE, LBUILD_MODE_SL,
     LBUILD_TITLE, "Setting Sensitivity Label", 
     LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
     LBUILD_X, 200,
     LBUILD_Y, 200,
     LBUILD_USERFIELD, "Pathname:",
     LBUILD_SHOW, FALSE,
  NULL);

Example 2 To Query the Mode and Display the Label Builder

These examples call the tsol_lbuild_get() routine to query the mode being used, and call the tsol_lbuild_set() routine so the label builder dialog box displays.

mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );

tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE, NULL);

Example 3 To Destroy the ModLabelData Variable

This example destroys the ModLabelData variable returned in the call to tsol_lbuild_create().

tsol_lbuild_destroy(lbldata);

Files

/usr/dt/include/Dt/ModLabel.h: Header file for label builder functions
/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe

tsol_lbuild_set(3TSOL)

NAME

labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set, tsol_lbuild_destroy – create a Motif-based user interface for interactively building a valid label or clearance

Synopsis

cc [flag...] file... -ltsol -lDtTsol [library...]

#include <Dt/ModLabel.h>

ModLabelData *tsol_lbuild_create(Widget widget void (*event_handler)() ok_callback
     lbuild_attributes extended_operation,  ...., NULL);

void *tsol_lbuild_get(ModLabelData *data, lbuild_attributes extended_operation);

void tsol_lbuild_set(ModLabelData *data lbuild_attributes extended_operation,  ....,
     NULL);

void tsol_lbuild_destroy(ModLabelData *data);

Description

Application-specific functionality is implemented in the callback for the OK pushbutton. This callback is passed to the tsol_lbuild_create() call where it is mapped to the OK pushbutton widget.

The widget information is accessed directly by referencing the following fields of the ModLabelData structure.

lbuild_dialog: The label builder dialog box.
ok: The OK pushbutton.
cancel: The Cancel pushbutton.
reset: The Reset pushbutton.
help: The Help pushbutton.

The tsol_lbuild_create() parameter list takes the following values:

widget: The widget from which the dialog box is created. Any Motif widget can be passed.
ok_callback: A callback function that implements the behavior of the OK pushbutton on the dialog box.
..., NULL: A NULL terminated list of extended operations and value pairs that define the characteristics and behavior of the label builder dialog box.

tsol_lbuild_destroy() destroys the ModLabelData structure returned by tsol_lbuild_create().

tsol_lbuild_get() and tsol_lbuild_set() access the information stored in the ModLabelData structure returned by tsol_lbuild_create().

LBUILD_MODE

Create a user interface to build a sensitivity label or a clearance. Value is LBUILD_MODE_SL by default.

LBUILD_MODE_SL: Build a sensitivity label.
LBUILD_MODE_CLR: Build a clearance.

LBUILD_VALUE_SL

The starting sensitivity label. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_SL.

LBUILD_VALUE_CLR

The starting clearance. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_CLR.

LBUILD_USERFIELD

A character string prompt that displays at the top of the label builder dialog box. Value is NULL by default.

LBUILD_SHOW

Show or hide the label builder dialog box. Value is FALSE by default.

TRUE: Show the label builder dialog box.
FALSE: Hide the label builder dialog box.

LBUILD_TITLE

A character string title that appears at the top of the label builder dialog box. Value is NULL by default.

LBUILD_WORK_SL

LBUILD_WORK_CLR

LBUILD_X

LBUILD_Y

LBUILD_LOWER_BOUND

The lowest classification (and related compartments and markings) available to the user as radio buttons for interactively building a label or clearance. This value is the user's minimum label.

LBUILD_UPPER_BOUND

LBUILD_CHECK_AR

LBUILD_VIEW

Use the internal or external label representation. Value is LBUILD_VIEW_EXTERNAL by default.

LBUILD_VIEW_INTERNAL: Use the internal names for the highest and lowest labels in the system: ADMIN_HIGH and ADMIN_LOW.
LBUILD_VIEW_EXTERNAL: Promote an ADMIN_LOW label to the next highest label, and demote an ADMIN_HIGH label to the next lowest label.

Return Values

The tsol_lbuild_get() returns -1 if it is unable to get the value.

Examples

Example 1 To Create a Label Builder

(ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
     LBUILD_MODE, LBUILD_MODE_SL,
     LBUILD_TITLE, "Setting Sensitivity Label", 
     LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
     LBUILD_X, 200,
     LBUILD_Y, 200,
     LBUILD_USERFIELD, "Pathname:",
     LBUILD_SHOW, FALSE,
  NULL);

Example 2 To Query the Mode and Display the Label Builder

These examples call the tsol_lbuild_get() routine to query the mode being used, and call the tsol_lbuild_set() routine so the label builder dialog box displays.

mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );

tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE, NULL);

Example 3 To Destroy the ModLabelData Variable

This example destroys the ModLabelData variable returned in the call to tsol_lbuild_create().

tsol_lbuild_destroy(lbldata);

Files

/usr/dt/include/Dt/ModLabel.h: Header file for label builder functions
/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe

Xbcleartos(3TSOL)

NAME

labelclipping, Xbsltos, Xbcleartos – translate a binary label and clip to the specified width

Synopsis

cc [flag...] file... -ltsol -lDtTsol [library...]

#include <Dt/label_clipping.h>

XmString Xbsltos(Display *display, const m_label_t *senslabel, Dimension width,
     const XmFontList fontlist, const int flags);

XmString Xbcleartos(Display *display, const m_label_t *clearance,
     Dimension width, const XmFontList fontlist, const int flags);

Interface Level

The labelclipping functions, Xbsltos() and Xbcleartos(), are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to translate labels or clearances that dominate the current process' sensitivity label.

display: The structure controlling the connection to an X Window System display.
senslabel: The sensitivity label to be translated.
clearance: The clearance to be translated.
width: The width of the translated label or clearance in pixels. If the specified width is shorter than the full label, the label is clipped and the presence of clipped letters is indicated by an arrow. In this example, letters have been clipped to the right of: TS<-. See the sbltos(3TSOL) man page for more information on the clipped indicator. If the specified width is equal to the display width (display), the label is not truncated, but word-wrapped using a width of half the display width.
fontlist: A list of fonts and character sets where each font is associated with a character set.
flags: The value of flags indicates which words in the label_encodings(4) file are used for the translation. See the bltos(3TSOL) man page for a description of the flag values: LONG_WORDS, SHORT_WORDS, LONG_CLASSIFICATION, SHORT_CLASSIFICATION, ALL_ENTRIES, ACCESS_RELATED, VIEW_EXTERNAL, VIEW_INTERNAL, NO_CLASSIFICATION. BRACKETED is an additional flag that can be used with Xbsltos() only. It encloses the sensitivity label in square brackets as follows: [C].

Return Values

Files

/usr/dt/include/Dt/label_clipping.h: Header file for label clipping functions
/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Examples

Example 1 To Translate and Clip a Clearance

This example translates a clearance to text using the long words specified in the label_encodings(4) file, a font list, and clips the translated clearance to a width of 72 pixels.

xmstr = Xbcleartos(XtDisplay(topLevel), 
&clearance, 72, fontlist, LONG_WORDS

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe

Xbsltos(3TSOL)

NAME

labelclipping, Xbsltos, Xbcleartos – translate a binary label and clip to the specified width

Synopsis

cc [flag...] file... -ltsol -lDtTsol [library...]

#include <Dt/label_clipping.h>

XmString Xbsltos(Display *display, const m_label_t *senslabel, Dimension width,
     const XmFontList fontlist, const int flags);

XmString Xbcleartos(Display *display, const m_label_t *clearance,
     Dimension width, const XmFontList fontlist, const int flags);

Interface Level

The labelclipping functions, Xbsltos() and Xbcleartos(), are obsolete. Use the label_to_str(3TSOL) function instead.

Description

The calling process must have PRIV_SYS_TRANS_LABEL in its set of effective privileges to translate labels or clearances that dominate the current process' sensitivity label.

display: The structure controlling the connection to an X Window System display.
senslabel: The sensitivity label to be translated.
clearance: The clearance to be translated.
width: The width of the translated label or clearance in pixels. If the specified width is shorter than the full label, the label is clipped and the presence of clipped letters is indicated by an arrow. In this example, letters have been clipped to the right of: TS<-. See the sbltos(3TSOL) man page for more information on the clipped indicator. If the specified width is equal to the display width (display), the label is not truncated, but word-wrapped using a width of half the display width.
fontlist: A list of fonts and character sets where each font is associated with a character set.
flags: The value of flags indicates which words in the label_encodings(4) file are used for the translation. See the bltos(3TSOL) man page for a description of the flag values: LONG_WORDS, SHORT_WORDS, LONG_CLASSIFICATION, SHORT_CLASSIFICATION, ALL_ENTRIES, ACCESS_RELATED, VIEW_EXTERNAL, VIEW_INTERNAL, NO_CLASSIFICATION. BRACKETED is an additional flag that can be used with Xbsltos() only. It encloses the sensitivity label in square brackets as follows: [C].

Return Values

Files

/usr/dt/include/Dt/label_clipping.h: Header file for label clipping functions
/etc/security/tsol/label_encodings: The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

Examples

Example 1 To Translate and Clip a Clearance

This example translates a clearance to text using the long words specified in the label_encodings(4) file, a font list, and clips the translated clearance to a width of 72 pixels.

xmstr = Xbcleartos(XtDisplay(topLevel), 
&clearance, 72, fontlist, LONG_WORDS

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe