'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH getauthattr 3SECDB "20 Feb 2009" "SunOS 5.11" "Security Attributes Database Library Functions"
.SH NAME
getauthattr, getauthnam, free_authattr, setauthattr, endauthattr, chkauthattr
\- get authorization entry
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... -lsecdb  -lsocket  -lnsl  [ \fIlibrary\fR... ]
#include <auth_attr.h> 
#include <secdb.h>  

\fBauthattr_t *\fR\fBgetauthattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBauthattr_t *\fR\fBgetauthnam\fR(\fBconst char *\fR\fIname\fR);
.fi

.LP
.nf
\fBvoid\fR \fBfree_authattr\fR(\fBauthattr_t *\fR\fIauth\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsetauthattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBendauthattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBint\fR \fBchkauthattr\fR(\fBconst char *\fR\fIauthname\fR, \fBconst char *\fR\fIusername\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgetauthattr()\fR and \fBgetauthnam()\fR functions each return an
\fBauth_attr\fR(4) entry. Entries can come from any of the sources specified in
the \fBnsswitch.conf\fR(4) file.
.sp
.LP
The \fBgetauthattr()\fR function enumerates \fBauth_attr\fR entries. The
\fBgetauthnam()\fR function searches for an \fBauth_attr\fR entry with a given
authorization name \fIname\fR. Successive calls to these functions return
either successive \fBauth_attr\fR entries or \fINULL\fR.
.sp
.LP
Th internal representation of an \fBauth_attr\fR entry is an \fBauthattr_t\fR
structure defined in  <\fBauth_attr.h\fR> with the following members:
.sp
.in +2
.nf
char   *name;        /* name of the authorization */
char   *res1;        /* reserved for future use */
char   *res2;        /* reserved for future use */
char   *short_desc;  /* short description */
char   *long_desc;   /* long description */
kva_t  *attr;        /* array of key-value pair attributes */
.fi
.in -2

.sp
.LP
The \fBsetauthattr()\fR function "rewinds" to the beginning of the enumeration
of \fBauth_attr\fR entries.  Calls to \fBgetauthnam()\fR can leave the
enumeration in an indeterminate state. Therefore, \fBsetauthattr()\fR should be
called before the first call to \fBgetauthattr()\fR.
.sp
.LP
The \fBendauthattr()\fR function may be called to indicate that \fBauth_attr\fR
processing is complete; the system may then close any open \fBauth_attr\fR
file, deallocate storage, and so forth.
.sp
.LP
The \fBchkauthattr()\fR function verifies whether or not a user has a given
authorization. It first reads the \fBAUTHS_GRANTED\fR key in the
\fB/etc/security/policy.conf\fR file and returns 1 if it finds a match for the
given authorization. If \fBchkauthattr()\fR does not find a match and the
\fIusername\fR is the name of the "console user", defined as the owner of
\fB/dev/console\fR, it first reads the \fBCONSOLE_USER\fR key in
\fB/etc/security/policy.conf\fR and returns 1 if the given authorization is in
any of the profiles specified in the \fBCONSOLE_USER\fR keyword, then reads the
\fBPROFS_GRANTED\fR key in \fB/etc/security/policy.conf\fR and returns 1 if the
given authorization is in any profiles specified with the \fBPROFS_GRANTED\fR
keyword. If a match is not found from the default authorizations and default
profiles, \fBchkauthattr()\fR reads the \fBuser_attr\fR(4) database. If it does
not find a match in  \fBuser_attr\fR, it reads the \fBprof_attr\fR(4) database,
using the list of profiles assigned to the user, and checks if any of the
profiles assigned to the user has the given authorization.  The
\fBchkauthattr()\fR function returns 0 if it does not find a match in any of
the three sources or if the user does not exist.
.sp
.LP
A user is considered to have been assigned an authorization if either of the
following are true:
.RS +4
.TP
.ie t \(bu
.el o
The authorization name matches exactly any authorization assigned in the
\fBuser_attr\fR or  \fBprof_attr\fR databases (authorization names are
case-sensitive).
.RE
.RS +4
.TP
.ie t \(bu
.el o
The authorization name suffix is not the key word  \fBgrant\fR and the
authorization name matches any authorization up to the asterisk (*) character
assigned in the \fBuser_attr\fR or \fBprof_attr\fR databases.
.RE
.sp
.LP
The examples in the following table illustrate the conditions under which a
user is assigned an authorization.
.sp

.sp
.TS
tab() box;
cw(2.04i) |cw(2.33i) |cw(1.12i) 
cw(2.04i) |cw(2.33i) |cw(1.12i) 
.
\f(CW/etc/security/policy.conf\fR orIs user
_
\fBAuthorization name\fR\fBuser_attr\fR or \fB\fR \fBprof_attr\fR entryauthorized?
_
solaris.printer.postscriptsolaris.printer.postscriptYes
solaris.printer.postscriptsolaris.printer.*Yes
solaris.printer.grantsolaris.printer.*No
.TE

.sp
.LP
The \fBfree_authattr()\fR function releases memory allocated by the
\fBgetauthnam()\fR and  \fBgetauthattr()\fR functions.
.SH RETURN VALUES
.sp
.LP
The \fBgetauthattr()\fR function returns a pointer to an  \fBauthattr_t\fR if
it successfully enumerates an entry; otherwise it returns \fINULL\fR,
indicating the end of the enumeration.
.sp
.LP
The \fBgetauthnam()\fR function returns a pointer to an  \fBauthattr_t\fR if it
successfully locates the requested entry; otherwise it returns \fINULL\fR.
.sp
.LP
The \fBchkauthattr()\fR function returns 1 if the user is authorized and 0 if
the user does not exist or is not authorized.
.SH USAGE
.sp
.LP
The \fBgetauthattr()\fR and \fBgetauthnam()\fR functions both allocate memory
for the pointers they return. This memory should be deallocated with the
\fBfree_authattr()\fR call.
.sp
.LP
Individual attributes in the \fBattr\fR structure can be referred to by calling
the \fBkva_match\fR(3SECDB) function.
.SH WARNINGS
.sp
.LP
Because the list of legal keys is likely to expand, code  must be written to
ignore unknown key-value pairs without error.
.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/etc/nsswitch.conf\fR\fR
.ad
.RS 29n
.rt  
configuration file lookup information for the name server switch
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/user_attr\fR\fR
.ad
.RS 29n
.rt  
extended user attributes
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/security/auth_attr\fR\fR
.ad
.RS 29n
.rt  
authorization attributes
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/security/policy.conf\fR\fR
.ad
.RS 29n
.rt  
policy definitions
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/security/prof_attr\fR\fR
.ad
.RS 29n
.rt  
profile information
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBgetexecattr\fR(3SECDB), \fBgetprofattr\fR(3SECDB),
\fBgetuserattr\fR(3SECDB), \fBauth_attr\fR(4), \fBnsswitch.conf\fR(4),
\fBprof_attr\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5), \fBrbac\fR(5)