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