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 Th 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)