usr/src/man/man4/auth_attr.4

   1 '\" te
   2 .\" Copyright (C) 2002, 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.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" 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 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH AUTH_ATTR 4 "Feb 25, 2017"
   7 .SH NAME
   8 auth_attr \- authorization description database
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/etc/security/auth_attr\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .LP
  17 \fB/etc/security/auth_attr\fR is a local source for authorization names and
  18 descriptions. The \fBauth_attr\fR file can be used with other authorization
  19 sources, including the \fBauth_attr\fR \fBNIS\fR map.
  20 Programs use the \fBgetauthattr\fR(3SECDB) routines to access this information.
  21 .sp
  22 .LP
  23 The search order for multiple authorization sources is specified in the
  24 \fB/etc/nsswitch.conf\fR file, as described in the \fBnsswitch.conf\fR(4) man
  25 page.
  26 .sp
  27 .LP
  28 An authorization is a right assigned to users that is checked by certain
  29 privileged programs to determine whether users can execute restricted
  30 functionality. Each entry in the \fBauth_attr\fR database consists of one line
  31 of text containing six fields separated by colons (\fB:\fR). Line continuations
  32 using the backslash (\fB\e\fR) character are permitted. The format of each
  33 entry is:
  34 .sp
  35 .in +2
  36 .nf
  37 \fIname\fR:\fIres1\fR:\fIres2\fR:\fIshort_desc\fR:\fIlong_desc\fR:\fIattr\fR
  38 .fi
  39 .in -2
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIname\fR\fR
  45 .ad
  46 .RS 14n
  47 The name of the authorization. Authorization names are unique strings.
  48 Construct authorization names using the following convention:
  49 .sp
  50 \fIprefix.\fR or \fIprefix.suffix\fR
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIprefix\fR\fR
  55 .ad
  56 .RS 10n
  57 Everything in the name field up to the final dot (\fB\&.\fR). Authorizations
  58 from Sun Microsystems, Inc. use \fBsolaris\fR as a prefix. To avoid name
  59 conflicts, all other authorizations should use a prefix that begins with the
  60 reverse-order Internet domain name of the organization that creates the
  61 authorization (for example, \fBcom.xyzcompany\fR). Prefixes can have additional
  62 arbitrary components chosen by the authorization's developer, with components
  63 separated by dots.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIsuffix\fR\fR
  70 .ad
  71 .RS 10n
  72 The final component in the name field. Specifies what is being authorized.
  73 .sp
  74 When there is no suffix, the name is defined as a heading. Headings are not
  75 assigned to users but are constructed for use by applications in their
  76 \fBGUI\fRs.
  77 .RE
  78
  79 When a name ends with the word \fBgrant\fR, the entry defines a grant
  80 authorization. Grant authorizations are used to support fine-grained
  81 delegation. Users with appropriate grant authorizations can delegate some of
  82 their authorizations to others. To assign an authorization, the user needs to
  83 have both the authorization itself and the appropriate grant authorization.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fIres1\fR\fR
  90 .ad
  91 .RS 14n
  92 Reserved for future use.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fIres2\fR\fR
  99 .ad
 100 .RS 14n
 101 Reserved for future use.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fIshort_desc\fR\fR
 108 .ad
 109 .RS 14n
 110 A short description or terse name for the authorization. This name should be
 111 suitable for displaying in user interfaces, such as in a scrolling list in a
 112 \fBGUI\fR.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fIlong_desc\fR\fR
 119 .ad
 120 .RS 14n
 121 A long description. This field can explain the precise purpose of the
 122 authorization, the applications in which it is used, and the type of user that
 123 would be interested in using it. The long description can be displayed in the
 124 help text of an application.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fIattr\fR\fR
 131 .ad
 132 .RS 14n
 133 An optional list of semicolon-separated (\fB;\fR) key-value pairs that describe
 134 the attributes of an authorization. Zero or more keys may be specified. The
 135 keyword \fBhelp\fR identifies a help file in HTML.
 136 .RE
 137
 138 .SH EXAMPLES
 139 .LP
 140 \fBExample 1 \fRConstructing a Name
 141 .sp
 142 .LP
 143 In the following example, the name has a prefix (\fBsolaris.admin.usermgr\fR)
 144 followed by a suffix (\fBread\fR):
 145
 146 .sp
 147 .in +2
 148 .nf
 149 solaris.admin.usermgr.read
 150 .fi
 151 .in -2
 152
 153 .LP
 154 \fBExample 2 \fRDefining a Heading
 155 .sp
 156 .LP
 157 Because the name field ends with a dot, the following entry defines a heading:
 158
 159 .sp
 160 .in +2
 161 .nf
 162 solaris.admin.usermgr.:::User Accounts::help=AuthUsermgrHeader.html
 163 .fi
 164 .in -2
 165
 166 .LP
 167 \fBExample 3 \fRAssigning Separate Authorizations to Set User Attributes
 168 .sp
 169 .LP
 170 In this example, a heading entry is followed by other associated authorization
 171 entries. The entries below the heading provide separate authorizations for
 172 setting user attributes. The \fIattr\fR field for each entry, including the
 173 heading entry, assigns a help file. The application that uses the \fBhelp\fR
 174 key requires the value to equal the name of a file ending in \fB\&.htm\fR or
 175 \fB\&.html\fR:
 176
 177 .sp
 178 .in +2
 179 .nf
 180 solaris.admin.usermgr.:::User Accounts::help=AuthUsermgrHeader.html
 181 solaris.admin.usermgr.pswd:::Change Password::help=AuthUserMgrPswd.html
 182 solaris.admin.usermgr.write:::Manage Users::help=AuthUsermgrWrite.html
 183 .fi
 184 .in -2
 185
 186 .LP
 187 \fBExample 4 \fRAssigning a Grant Authorization
 188 .sp
 189 .LP
 190 This example assigns to an administrator the following authorizations:
 191
 192 .sp
 193 .in +2
 194 .nf
 195 solaris.admin.printer.grant
 196 solaris.admin.printer.delete
 197 solaris.admin.printer.modify
 198 solaris.admin.printer.read
 199 solaris.login.enable
 200 .fi
 201 .in -2
 202
 203 .sp
 204 .LP
 205 With the above authorizations, the administrator can assign to others the
 206 \fBsolaris.admin.printer.delete\fR, \fBsolaris.admin.printer.modify\fR, and
 207 \fBsolaris.admin.printer.read\fR authorizations, but not the
 208 \fBsolaris.login.enable\fR authorization. If the administrator has both the
 209 grant authorization, \fBsolaris.admin.printmgr.grant\fR, and the wildcard
 210 authorization, \fBsolaris.admin.printmgr.*\fR, the administrator can grant to
 211 others any of the printer authorizations. See \fBuser_attr\fR(4) for more
 212 information about how wildcards can be used to assign multiple authorizations
 213 whose names begin with the same components.
 214
 215 .LP
 216 \fBExample 5 \fRAuthorizing the Ability to Assign Other Authorizations
 217 .sp
 218 .LP
 219 The following entry defines an authorization that grants the ability to assign
 220 any authorization created with a \fBsolaris\fR prefix, when the administrator
 221 also has either the specific authorization being granted or a matching wildcard
 222 entry:
 223
 224 .sp
 225 .in +2
 226 .nf
 227 solaris.grant:::Grant All Solaris Authorizations::help=PriAdmin.html
 228 .fi
 229 .in -2
 230
 231 .LP
 232 \fBExample 6 \fRConsulting the Local Authorization File Ahead of the NIS Table
 233 .sp
 234 .LP
 235 With the following entry from \fB/etc/nsswitch.conf\fR, the local
 236 \fBauth_attr\fR file is consulted before the \fBNIS\fR table:
 237
 238 .sp
 239 .in +2
 240 .nf
 241 auth_attr:files nis
 242 .fi
 243 .in -2
 244
 245 .SH FILES
 246 .LP
 247 \fB/etc/nsswitch.conf\fR
 248 .sp
 249 .LP
 250 \fB/etc/user_attr\fR
 251 .sp
 252 .LP
 253 \fB/etc/security/auth_attr\fR
 254 .SH SEE ALSO
 255 .LP
 256 \fBgetauthattr\fR(3SECDB), \fBgetexecattr\fR(3SECDB),
 257 \fBgetprofattr\fR(3SECDB), \fBgetuserattr\fR(3SECDB), \fBexec_attr\fR(4),
 258 \fBnsswitch.conf\fR(4), \fBuser_attr\fR(4)
 259 .SH NOTES
 260 .LP
 261 Because the list of legal keys is likely to expand, any code that parses this
 262 database must be written to ignore unknown key-value pairs without error. When
 263 any new keywords are created, the names should be prefixed with a unique
 264 string, such as the company's stock symbol, to avoid potential naming
 265 conflicts.
 266 .sp
 267 .LP
 268 Each application has its own requirements for whether the help value must be a
 269 relative pathname ending with a filename or the name of a file. The only known
 270 requirement is for the name of a file.
 271 .sp
 272 .LP
 273 The following characters are used in describing the database format and must be
 274 escaped with a backslash if used as data: colon (\fB:\fR), semicolon (\fB;\fR),
 275 equals (\fB=\fR), and backslash (\fB\e\fR).