usr/src/man/man3secdb/getauthattr.3secdb

   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)