usr/src/man/man3tsol/str_to_label.3tsol

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH STR_TO_LABEL 3TSOL "Jun 15, 2009"
   7 .SH NAME
   8 str_to_label \- parse human readable strings to label
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [\fIflag\fR...] \fIfile\fR... \fB-ltsol\fR [\fIlibrary\fR...]
  13 .fi
  14
  15 .LP
  16 .nf
  17 #include <tsol/label.h>
  18
  19 \fBint\fR \fBstr_to_label\fR(\fBconst char *\fR\fIstring\fR, \fBm_label_t **\fR\fIlabel\fR,
  20     \fBconst m_label_type_t\fR \fIlabel_type\fR, \fBuint_t\fR \fIflags\fR, \fBint *\fR\fIerror\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBstr_to_label()\fR function is a simple function to parse human readable
  27 strings into labels of the requested type.
  28 .sp
  29 .LP
  30 The \fIstring\fR argument is the string to parse. If \fIstring\fR is the result
  31 of a \fBlabel_to_str()\fR conversion of type \fBM_INTERNAL\fR, \fIflags\fR are
  32 ignored, and any previously parsed label is replaced.
  33 .sp
  34 .LP
  35 If *\fIlabel\fR is \fINULL\fR, \fBstr_to_label()\fR allocates resources for
  36 \fIlabel\fR and initializes the label to the \fIlabel_type\fR that was
  37 requested before parsing \fIstring\fR.
  38 .sp
  39 .LP
  40 If *\fIlabel\fR is not \fINULL\fR, the label is a pointer to a mandatory label
  41 that is the result of a previously parsed label and \fIlabel_type\fR is
  42 ignored. The type that is used for parsing is derived from \fIlabel\fR for any
  43 type-sensitive operations.
  44 .sp
  45 .LP
  46 If \fIflags\fR is \fBL_MODIFY_EXISTING\fR, the parsed string can be used to
  47 modify this label.
  48 .sp
  49 .LP
  50 If \fIflags\fR is \fBL_NO_CORRECTION\fR, the previously parsed label is
  51 replaced and the parsing algorithm does not attempt to infer missing elements
  52 from string to compose a valid label.
  53 .sp
  54 .LP
  55 If \fIflags\fR is \fBL_DEFAULT\fR, the previously parsed label is replaced and
  56 the parsing algorithm makes a best effort to imply a valid label from the
  57 elements of \fIstring\fR.
  58 .sp
  59 .LP
  60 If \fIflags\fR contains \fBL_CHECK_AR\fR logically OR-ed with another value,
  61 the resulting label will be checked to ensure that it is within the
  62 "Accreditation Range" of the DIA encodings schema. This flag is interpreted
  63 only for \fBMAC_LABEL\fR label types.
  64 .sp
  65 .LP
  66 The caller is responsible for freeing the allocated resources by calling the
  67 \fBm_label_free()\fR function. \fIlabel_type\fR defines the type for a newly
  68 allocated label. The label type can be:
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBMAC_LABEL\fR\fR
  73 .ad
  74 .RS 14n
  75 The string should be translated as a Mandatory Access Control (MAC) label.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBUSER_CLEAR\fR\fR
  82 .ad
  83 .RS 14n
  84 The string should be translated as a label that represents the least upper
  85 bound of the labels that the user is allowed to access.
  86 .RE
  87
  88 .sp
  89 .LP
  90 If \fIerror\fR is \fINULL\fR, do not return additional error information for
  91 \fBEINVAL\fR. The calling process must have mandatory read access to
  92 \fIlabel\fR and human readable \fIstring\fR. Or the calling process must have
  93 the \fBsys_trans_label\fR privilege.
  94 .sp
  95 .LP
  96 The manifest constants \fBADMIN_HIGH\fR and \fBADMIN_LOW\fR are the human
  97 readable strings that correspond to the Trusted Extensions policy
  98 \fBadmin_high\fR and \fBadmin_low\fR label values. See \fBlabels\fR(5).
  99 .SH RETURN VALUES
 100 .sp
 101 .LP
 102 Upon successful completion, the \fBstr_to_label()\fR function returns 0.
 103 Otherwise, \fB-1\fR is returned, \fIerrno\fR is set to indicate the error, and
 104 \fIerror\fR provides additional information for \fBEINVAL\fR. Otherwise,
 105 \fIerror\fR is a zero-based index to the string parse failure point.
 106 .SH ERRORS
 107 .sp
 108 .LP
 109 The \fBstr_to_label()\fR function will fail if:
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBEINVAL\fR\fR
 114 .ad
 115 .RS 11n
 116 Invalid parameter. \fBM_BAD_STRING\fR indicates that \fIstring\fR could not be
 117 parsed. \fBM_BAD_LABEL\fR indicates that the label passed in was in error.
 118 \fBM_OUTSIDE_AR\fR indicates that the resulting label is not within the
 119 "Accreditation Range" specified in the DIA encodings schema.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBENOTSUP\fR\fR
 126 .ad
 127 .RS 11n
 128 The system does not support label translations.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBENOMEM\fR\fR
 135 .ad
 136 .RS 11n
 137 The physical limits of the system are exceeded by size bytes of memory which
 138 cannot be allocated.
 139 .RE
 140
 141 .SH ATTRIBUTES
 142 .sp
 143 .LP
 144 See \fBattributes\fR(5) for descriptions of the following attributes:
 145 .sp
 146
 147 .sp
 148 .TS
 149 box;
 150 c | c
 151 l | l .
 152 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 153 _
 154 Interface Stability     Committed
 155 _
 156 MT-Level        MT-Safe
 157 _
 158 Standard        See below.
 159 .TE
 160
 161 .sp
 162 .LP
 163 Parsing types that are relative to Defense Intelligence Agency (DIA) encodings
 164 schema are Standard. Standard is specified in \fBlabel_encodings\fR(4).
 165 .SH SEE ALSO
 166 .sp
 167 .LP
 168 \fBlabel_to_str\fR(3TSOL), \fBlibtsol\fR(3LIB), \fBm_label\fR(3TSOL),
 169 \fBlabel_encodings\fR(4), \fBattributes\fR(5), \fBlabels\fR(5)
 170 .sp
 171 .LP
 172 \fIValidating the Label Request Against the Printer\&'s Label Range\fR in
 173 \fISolaris Trusted Extensions Developer\&'s Guide\fR
 174 .SH WARNINGS
 175 .sp
 176 .LP
 177 A number of the parsing rules rely on the DIA label encodings schema. The rules
 178 might not be valid for other label schemata.
 179 .SH NOTES
 180 .sp
 181 .LP
 182 The functionality described on this manual page is available only if the system
 183 is configured with Trusted Extensions.