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. 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 GETAUTHATTR 3SECDB "Feb 20, 2009" 7 .SH NAME 8 getauthattr, getauthnam, free_authattr, setauthattr, endauthattr, chkauthattr 9 \- get authorization entry 10 .SH SYNOPSIS 11 .LP 12 .nf 13 cc [ \fIflag\fR... ] \fIfile\fR... -lsecdb -lsocket -lnsl [ \fIlibrary\fR... ] 14 #include <auth_attr.h> 15 #include <secdb.h> 16 17 \fBauthattr_t *\fR\fBgetauthattr\fR(\fBvoid\fR); 18 .fi 19 20 .LP 21 .nf 22 \fBauthattr_t *\fR\fBgetauthnam\fR(\fBconst char *\fR\fIname\fR); 23 .fi 24 25 .LP 26 .nf 27 \fBvoid\fR \fBfree_authattr\fR(\fBauthattr_t *\fR\fIauth\fR); 28 .fi 29 30 .LP 31 .nf 32 \fBvoid\fR \fBsetauthattr\fR(\fBvoid\fR); 33 .fi 34 35 .LP 36 .nf 37 \fBvoid\fR \fBendauthattr\fR(\fBvoid\fR); 38 .fi 39 40 .LP 41 .nf 42 \fBint\fR \fBchkauthattr\fR(\fBconst char *\fR\fIauthname\fR, \fBconst char *\fR\fIusername\fR); 43 .fi 44 45 .SH DESCRIPTION 46 .sp 47 .LP 48 The \fBgetauthattr()\fR and \fBgetauthnam()\fR functions each return an 49 \fBauth_attr\fR(4) entry. Entries can come from any of the sources specified in 50 the \fBnsswitch.conf\fR(4) file. 51 .sp 52 .LP 53 The \fBgetauthattr()\fR function enumerates \fBauth_attr\fR entries. The 54 \fBgetauthnam()\fR function searches for an \fBauth_attr\fR entry with a given 55 authorization name \fIname\fR. Successive calls to these functions return 56 either successive \fBauth_attr\fR entries or \fINULL\fR. 57 .sp 58 .LP 59 Th internal representation of an \fBauth_attr\fR entry is an \fBauthattr_t\fR 60 structure defined in <\fBauth_attr.h\fR> with the following members: 61 .sp 62 .in +2 63 .nf 64 char *name; /* name of the authorization */ 65 char *res1; /* reserved for future use */ 66 char *res2; /* reserved for future use */ 67 char *short_desc; /* short description */ 68 char *long_desc; /* long description */ 69 kva_t *attr; /* array of key-value pair attributes */ 70 .fi 71 .in -2 72 73 .sp 74 .LP 75 The \fBsetauthattr()\fR function "rewinds" to the beginning of the enumeration 76 of \fBauth_attr\fR entries. Calls to \fBgetauthnam()\fR can leave the 77 enumeration in an indeterminate state. Therefore, \fBsetauthattr()\fR should be 78 called before the first call to \fBgetauthattr()\fR. 79 .sp 80 .LP 81 The \fBendauthattr()\fR function may be called to indicate that \fBauth_attr\fR 82 processing is complete; the system may then close any open \fBauth_attr\fR 83 file, deallocate storage, and so forth. 84 .sp 85 .LP 86 The \fBchkauthattr()\fR function verifies whether or not a user has a given 87 authorization. It first reads the \fBAUTHS_GRANTED\fR key in the 88 \fB/etc/security/policy.conf\fR file and returns 1 if it finds a match for the 89 given authorization. If \fBchkauthattr()\fR does not find a match and the 90 \fIusername\fR is the name of the "console user", defined as the owner of 91 \fB/dev/console\fR, it first reads the \fBCONSOLE_USER\fR key in 92 \fB/etc/security/policy.conf\fR and returns 1 if the given authorization is in 93 any of the profiles specified in the \fBCONSOLE_USER\fR keyword, then reads the 94 \fBPROFS_GRANTED\fR key in \fB/etc/security/policy.conf\fR and returns 1 if the 95 given authorization is in any profiles specified with the \fBPROFS_GRANTED\fR 96 keyword. If a match is not found from the default authorizations and default 97 profiles, \fBchkauthattr()\fR reads the \fBuser_attr\fR(4) database. If it does 98 not find a match in \fBuser_attr\fR, it reads the \fBprof_attr\fR(4) database, 99 using the list of profiles assigned to the user, and checks if any of the 100 profiles assigned to the user has the given authorization. The 101 \fBchkauthattr()\fR function returns 0 if it does not find a match in any of 102 the three sources or if the user does not exist. 103 .sp 104 .LP 105 A user is considered to have been assigned an authorization if either of the 106 following are true: 107 .RS +4 108 .TP 109 .ie t \(bu 110 .el o 111 The authorization name matches exactly any authorization assigned in the 112 \fBuser_attr\fR or \fBprof_attr\fR databases (authorization names are 113 case-sensitive). 114 .RE 115 .RS +4 116 .TP 117 .ie t \(bu 118 .el o 119 The authorization name suffix is not the key word \fBgrant\fR and the 120 authorization name matches any authorization up to the asterisk (*) character 121 assigned in the \fBuser_attr\fR or \fBprof_attr\fR databases. 122 .RE 123 .sp 124 .LP 125 The examples in the following table illustrate the conditions under which a 126 user is assigned an authorization. 127 .sp 128 129 .sp 130 .TS 131 box; 132 c | c | c 133 c | c | c . 134 \f(CW/etc/security/policy.conf\fR or Is user 135 _ 136 \fBAuthorization name\fR \fBuser_attr\fR or \fB\fR \fBprof_attr\fR entry authorized? 137 _ 138 solaris.printer.postscript solaris.printer.postscript Yes 139 solaris.printer.postscript solaris.printer.* Yes 140 solaris.printer.grant solaris.printer.* No 141 .TE 142 143 .sp 144 .LP 145 The \fBfree_authattr()\fR function releases memory allocated by the 146 \fBgetauthnam()\fR and \fBgetauthattr()\fR functions. 147 .SH RETURN VALUES 148 .sp 149 .LP 150 The \fBgetauthattr()\fR function returns a pointer to an \fBauthattr_t\fR if 151 it successfully enumerates an entry; otherwise it returns \fINULL\fR, 152 indicating the end of the enumeration. 153 .sp 154 .LP 155 The \fBgetauthnam()\fR function returns a pointer to an \fBauthattr_t\fR if it 156 successfully locates the requested entry; otherwise it returns \fINULL\fR. 157 .sp 158 .LP 159 The \fBchkauthattr()\fR function returns 1 if the user is authorized and 0 if 160 the user does not exist or is not authorized. 161 .SH USAGE 162 .sp 163 .LP 164 The \fBgetauthattr()\fR and \fBgetauthnam()\fR functions both allocate memory 165 for the pointers they return. This memory should be deallocated with the 166 \fBfree_authattr()\fR call. 167 .sp 168 .LP 169 Individual attributes in the \fBattr\fR structure can be referred to by calling 170 the \fBkva_match\fR(3SECDB) function. 171 .SH WARNINGS 172 .sp 173 .LP 174 Because the list of legal keys is likely to expand, code must be written to 175 ignore unknown key-value pairs without error. 176 .SH FILES 177 .sp 178 .ne 2 179 .na 180 \fB\fB/etc/nsswitch.conf\fR\fR 181 .ad 182 .RS 29n 183 configuration file lookup information for the name server switch 184 .RE 185 186 .sp 187 .ne 2 188 .na 189 \fB\fB/etc/user_attr\fR\fR 190 .ad 191 .RS 29n 192 extended user attributes 193 .RE 194 195 .sp 196 .ne 2 197 .na 198 \fB\fB/etc/security/auth_attr\fR\fR 199 .ad 200 .RS 29n 201 authorization attributes 202 .RE 203 204 .sp 205 .ne 2 206 .na 207 \fB\fB/etc/security/policy.conf\fR\fR 208 .ad 209 .RS 29n 210 policy definitions 211 .RE 212 213 .sp 214 .ne 2 215 .na 216 \fB\fB/etc/security/prof_attr\fR\fR 217 .ad 218 .RS 29n 219 profile information 220 .RE 221 222 .SH ATTRIBUTES 223 .sp 224 .LP 225 See \fBattributes\fR(5) for descriptions of the following attributes: 226 .sp 227 228 .sp 229 .TS 230 box; 231 c | c 232 l | l . 233 ATTRIBUTE TYPE ATTRIBUTE VALUE 234 _ 235 MT-Level MT-Safe 236 .TE 237 238 .SH SEE ALSO 239 .sp 240 .LP 241 \fBgetexecattr\fR(3SECDB), \fBgetprofattr\fR(3SECDB), 242 \fBgetuserattr\fR(3SECDB), \fBauth_attr\fR(4), \fBnsswitch.conf\fR(4), 243 \fBprof_attr\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5), \fBrbac\fR(5)