man pages section 3: Library Functions

bcltobanner(3TSOL)

NAME

bcltobanner- translate binary CMW labels to character-coded labels for a printer banner page

SYNOPSIS

cc

flag

file

-ltsol

library

#include <tsol/label.h>

label

fields

flags

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.

bcltobanner() translates a binary CMW label, label, into various character-coded labels and strings for display on printer banner and trailer pages and at the top and bottom of the document body pages. The members of the fields structure are either string pointers, or the length of memory pre-allocated to a string pointer. The string pointers may contain either a pointer to pre-allocated memory, or the value (char *)0. If the string pointer contains a pointer to pre-allocated memory, then its associated length member indicates the size of that memory. If it contains the value (char *)0, memory is allocated using malloc() to contain the translated character-coded label or string. The translated string is copied into allocated or pre-allocated memory.

The structure banner_fields stores the folloiwng information:

struct banner_fields  {
char *header;            /* top and bottom banner/trailer page */
char *protect_as;        /* "protect as" banner page section */
char *ilabel;            /*  obsolete */
char *caveats;           /* ``caveats'' banner page section */
char *channels;          /* ``handling channels'' section */
                         /* lengths of pre-allocated string memory */
short header_len;        /* header */
short protect_as_len;    /* protect_as */
short short ilabel_len;  /* obsolete */
short caveats_len;       /* caveats */
short channels_len;      /* handling channels */
};

Members of the fields structure have the following meaning:

header: String to print at the top and bottom of banner and trailer pages
protect_as: String to print in the protect as warning of banner and trailer pages
ilabel: Obsolete string
caveats: String to print in caveats section of the banner and trailer pages
channels: String to print in channels section of the banner and trailer pages
header_len: Length of pre-allocated memory for header string
protect_as_len: Length of pre-allocated memory for protect_as string
ilabel_len: Obsolete string
caveats_len: Length of pre-allocated memory for caveats string
channels_len: Length of pre-allocated memory for channels string

The translation is controlled by the value of the flags parameter. flags may be either LONG_WORDS, SHORT_WORDS, or 0 (zero).

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.
0: A flags value 0 is equivalent to LONG_WORDS.

RETURN VALUES

bcltobanner() returns:

-1: If label is not a binary CMW label with a defined sensitivity label, or if its sensitivity label portion 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 if the label_encodings file is inaccessible.
0: If memory cannot be allocated for a string in the fields structure, or if one of the pre-allocated memories is insufficient to hold its string. The value of that pre-allocated string is set to the NULL string (fields-> string[0] = '\00';).
1: If successful.

EXAMPLES

Example 1 Banner Page Format

The string members of the fields structure are included in a printer banner page in the following manner:

			HEADER

This output must be protected as:
			PROTECT_AS
unless manually reviewed and downgraded.

			CAVEATS
			CHANNELS
			HEADER

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
MT-Level	MT-Safe

Trusted Solaris 8 4/01 Reference Manual

blcompare(3TSOL), blinset(3TSOL), blmanifest(3TSOL), blminmax(3TSOL), blportion(3TSOL), bltype(3TSOL), blvalid(3TSOL), btohex(3TSOL), hextob(3TSOL), labelinfo(3TSOL), labelvers(3TSOL), sbltos(3TSOL), label_encodings(4)

Trusted Solaris Developer's Guide, and Trusted Solaris administrator's document set

SunOS 5.8 Reference Manual

free(3C), malloc(3C), attributes(5)

NOTES

If memory is allocated by this routine, the caller must free memory with free() when the memory is no longer in use. ADMIN_LOW and ADMIN_HIGH labels are mapped differently than the other routines. If the label is ADMIN_LOW, the label is mapped into the minimum sensitivity label defined in the label_encodings file, and if the label is ADMIN_HIGH, the label is mapped into the maximum classification, and all compartments defined in the label_encodings file.

SunOS 5.8 Last Revised 24 May 2001