Manual Pages for UNIX Operating System command usage for man stobclear

Trusted Extensions Library Functions                 stobl(3TSOL)



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

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


     #include 

     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);


DESCRIPTION
     The stobsl() and stobclear() functions translate  character-
     coded  labels into binary labels. They also modify an exist-
     ing binary label by incrementing or decrementing it to  pro-
     duce a new binary label relative to its existing value.


     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  sensi-
     tivity label.


     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.






SunOS 5.11          Last change: 20 Jul 2007                    1






Trusted Extensions Library Functions                 stobl(3TSOL)



     The stobsl() and stobclear() functions also translate  hexa-
     decimal   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.


     The flags argument can take the following values:

     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.



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


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


     The flags argument can be either  NEW_LABEL,  NO_CORRECTION,
     or  0 (zero). Unless NO_CORRECTION is specified, this trans-
     lation forces the label to dominate the minimum  classifica-
     tion,  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.


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





SunOS 5.11          Last change: 20 Jul 2007                    2






Trusted Extensions Library Functions                 stobl(3TSOL)



     The flags argument can be either  NEW_LABEL,  NO_CORRECTION,
     or  0 (zero). Unless NO_CORRECTION is specified, this trans-
     lation forces the label to dominate the minimum  classifica-
     tion,  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 clear-
     ance  might  not  be the same as the translation of a sensi-
     tivity 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. Otherwise they return
     0 and the value of the error argument indicates the 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  attri-
     butes:







SunOS 5.11          Last change: 20 Jul 2007                    3






Trusted Extensions Library Functions                 stobl(3TSOL)



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Obsolete                    |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|



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

SEE ALSO
     blcompare(3TSOL),       hextob(3TSOL),        libtsol(3LIB),
     str_to_label(3TSOL), attributes(5)

NOTES
     The functionality described on this manual page is available
     only if the system is configured with 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 specifica-
     tion  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.11          Last change: 20 Jul 2007                    4