'\" te
.\" Copyright (C) 2002, 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 auth_attr 4 "9 Jan 2002" "SunOS 5.11" "File Formats"
.SH NAME
auth_attr \- authorization description database
.SH SYNOPSIS
.LP
.nf
\fB/etc/security/auth_attr\fR 
.fi

.SH DESCRIPTION
.sp
.LP
\fB/etc/security/auth_attr\fR is a local source for authorization names and
descriptions. The \fBauth_attr\fR file can be used with other authorization
sources, including the \fBauth_attr\fR \fBNIS\fR map and \fBNIS+\fR table.
Programs use the \fBgetauthattr\fR(3SECDB) routines to access this information.
.sp
.LP
The search order for multiple authorization sources is specified in the
\fB/etc/nsswitch.conf\fR file, as described in the \fBnsswitch.conf\fR(4) man
page.
.sp
.LP
An authorization is a right assigned to users that is checked by certain
privileged programs to determine whether users can execute restricted
functionality. Each entry in the \fBauth_attr\fR database consists of one line
of text containing six fields separated by colons (\fB:\fR). Line continuations
using the backslash (\fB\e\fR) character are permitted. The format of each
entry is:
.sp
.in +2
.nf
\fIname\fR:\fIres1\fR:\fIres2\fR:\fIshort_desc\fR:\fIlong_desc\fR:\fIattr\fR
.fi
.in -2

.sp
.ne 2
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 14n
.rt  
The name of the authorization. Authorization names are unique strings.
Construct authorization names using the following convention:
.sp
\fIprefix.\fR or \fIprefix.suffix\fR
.sp
.ne 2
.mk
.na
\fB\fIprefix\fR\fR
.ad
.RS 10n
.rt  
Everything in the name field up to the final dot (\fB\&.\fR). Authorizations
from Sun Microsystems, Inc. use \fBsolaris\fR as a prefix. To avoid name
conflicts, all other authorizations should use a prefix that begins with the
reverse-order Internet domain name of the organization that creates the
authorization (for example, \fBcom.xyzcompany\fR). Prefixes can have additional
arbitrary components chosen by the authorization's developer, with components
separated by dots.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsuffix\fR\fR
.ad
.RS 10n
.rt  
The final component in the name field. Specifies what is being authorized.
.sp
When there is no suffix, the name is defined as a heading. Headings are not
assigned to users but are constructed for use by applications in their
\fBGUI\fRs.
.RE

When a name ends with the word \fBgrant\fR, the entry defines a grant
authorization. Grant authorizations are used to support fine-grained
delegation. Users with appropriate grant authorizations can delegate some of
their authorizations to others. To assign an authorization, the user needs to
have both the authorization itself and the appropriate grant authorization.
.RE

.sp
.ne 2
.mk
.na
\fB\fIres1\fR\fR
.ad
.RS 14n
.rt  
Reserved for future use.
.RE

.sp
.ne 2
.mk
.na
\fB\fIres2\fR\fR
.ad
.RS 14n
.rt  
Reserved for future use.
.RE

.sp
.ne 2
.mk
.na
\fB\fIshort_desc\fR\fR
.ad
.RS 14n
.rt  
A short description or terse name for the authorization. This name should be
suitable for displaying in user interfaces, such as in a scrolling list in a
\fBGUI\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlong_desc\fR\fR
.ad
.RS 14n
.rt  
A long description. This field can explain the precise purpose of the
authorization, the applications in which it is used, and the type of user that
would be interested in using it. The long description can be displayed in the
help text of an application.
.RE

.sp
.ne 2
.mk
.na
\fB\fIattr\fR\fR
.ad
.RS 14n
.rt  
An optional list of semicolon-separated (\fB;\fR) key-value pairs that describe
the attributes of an authorization. Zero or more keys may be specified. The
keyword \fBhelp\fR identifies a help file in HTML.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRConstructing a Name
.sp
.LP
In the following example, the name has a prefix (\fBsolaris.admin.usermgr\fR)
followed by a suffix (\fBread\fR):

.sp
.in +2
.nf
solaris.admin.usermgr.read
.fi
.in -2

.LP
\fBExample 2 \fRDefining a Heading
.sp
.LP
Because the name field ends with a dot, the following entry defines a heading:

.sp
.in +2
.nf
solaris.admin.usermgr.:::User Accounts::help=AuthUsermgrHeader.html
.fi
.in -2

.LP
\fBExample 3 \fRAssigning Separate Authorizations to Set User Attributes
.sp
.LP
In this example, a heading entry is followed by other associated authorization
entries. The entries below the heading provide separate authorizations for
setting user attributes. The \fIattr\fR field for each entry, including the
heading entry, assigns a help file. The application that uses the \fBhelp\fR
key requires the value to equal the name of a file ending in \fB\&.htm\fR or
\fB\&.html\fR:

.sp
.in +2
.nf
solaris.admin.usermgr.:::User Accounts::help=AuthUsermgrHeader.html
solaris.admin.usermgr.pswd:::Change Password::help=AuthUserMgrPswd.html
solaris.admin.usermgr.write:::Manage Users::help=AuthUsermgrWrite.html
.fi
.in -2

.LP
\fBExample 4 \fRAssigning a Grant Authorization
.sp
.LP
This example assigns to an administrator the following authorizations:

.sp
.in +2
.nf
solaris.admin.printer.grant
solaris.admin.printer.delete
solaris.admin.printer.modify
solaris.admin.printer.read
solaris.login.enable
.fi
.in -2

.sp
.LP
With the above authorizations, the administrator can assign to others the
\fBsolaris.admin.printer.delete\fR, \fBsolaris.admin.printer.modify\fR, and
\fBsolaris.admin.printer.read\fR authorizations, but not the
\fBsolaris.login.enable\fR authorization. If the administrator has both the
grant authorization, \fBsolaris.admin.printmgr.grant\fR, and the wildcard
authorization, \fBsolaris.admin.printmgr.*\fR, the administrator can grant to
others any of the printer authorizations. See \fBuser_attr\fR(4) for more
information about how wildcards can be used to assign multiple authorizations
whose names begin with the same components.

.LP
\fBExample 5 \fRAuthorizing the Ability to Assign Other Authorizations
.sp
.LP
The following entry defines an authorization that grants the ability to assign
any authorization created with a \fBsolaris\fR prefix, when the administrator
also has either the specific authorization being granted or a matching wildcard
entry:

.sp
.in +2
.nf
solaris.grant:::Grant All Solaris Authorizations::help=PriAdmin.html
.fi
.in -2

.LP
\fBExample 6 \fRConsulting the Local Authorization File Ahead of the NIS Table
.sp
.LP
With the following entry from \fB/etc/nsswitch.conf\fR, the local
\fBauth_attr\fR file is consulted before the \fBNIS\fR table:

.sp
.in +2
.nf
auth_attr:files nisplus
.fi
.in -2

.SH FILES
.sp
.LP
\fB/etc/nsswitch.conf\fR
.sp
.LP
\fB/etc/user_attr\fR
.sp
.LP
\fB/etc/security/auth_attr\fR
.SH SEE ALSO
.sp
.LP
\fBgetauthattr\fR(3SECDB), \fBgetexecattr\fR(3SECDB),
\fBgetprofattr\fR(3SECDB), \fBgetuserattr\fR(3SECDB), \fBexec_attr\fR(4),
\fBnsswitch.conf\fR(4), \fBuser_attr\fR(4)
.SH NOTES
.sp
.LP
When deciding which authorization source to use, keep in mind that \fBNIS+\fR
provides stronger authentication than \fBNIS\fR.
.sp
.LP
Because the list of legal keys is likely to expand, any code that parses this
database must be written to ignore unknown key-value pairs without error. When
any new keywords are created, the names should be prefixed with a unique
string, such as the company's stock symbol, to avoid potential naming
conflicts.
.sp
.LP
Each application has its own requirements for whether the help value must be a
relative pathname ending with a filename or the name of a file. The only known
requirement is for the name of a file.
.sp
.LP
The following characters are used in describing the database format and must be
escaped with a backslash if used as data: colon (\fB:\fR), semicolon (\fB;\fR),
equals (\fB=\fR), and backslash (\fB\e\fR).