'\" te .\" Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved. .TH getauthattr 3C "10 Mar 2011" "SunOS 5.11" "Standard C Library Functions" .SH NAME getauthattr, getauthnam, free_authattr, setauthattr, endauthattr, chkauthattr, chkauthattr_ucred \- get authorization entry .SH SYNOPSIS .LP .nf #include .fi .LP .nf \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 .LP .nf \fBint\fR \fBchkauthattr_ucred\fR(\fBconst char *\fR\fIauthname\fR, \fBconst char *\fR\fIusername\fR, \fBucred_t\fR \fIucred\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 \fBuser_attr\fR(4) database and returns 1 if it finds a match for the given authorization. If it does not find a match in \fBuser_attr\fR, \fBchkauthattr()\fR 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. .sp .LP For each user, there are two sets of profiles, an authenticated set and an unauthenticated set. Authorizations in the authenticated set are always effective, but those in the unauthenticated set only become effective after a successful response to an authentication challenge. Such challenges are automatically issued when the user executes a command matching an entry in the authenticated profiles set. See \fBpfexec\fR(1). .sp .LP When \fBchkauthattr()\fR finds a profile called "Stop", further profiles are ignored, the authorizations and profiles mentioned in \fB/etc/security/policy.conf\fR are ignored and it returns 0. If it does not find a match in the user's profiles, \fBchkauthattr()\fR reads the \fBAUTHS_GRANTED\fR key in the \fB/etc/security/policy.conf file\fR and returns 1 if it finds a match for the given authorization. If \fBchkauthattr()\fR does not find a match and the username 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. 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 The \fBchkauthattr_ucred()\fR function is identical to the \fBchkauthattr()\fR function, except for its interpretation of authorizations specified in the authenticated profiles set. In determining whether the authenticated profiles are effective, it uses the \fBucred\fR pointer instead of the process flags of the calling process. This function should be used for local services that run on behalf of clients. The \fBucred\fR of the client can be obtained by \fBgetpeerucred\fR(3C) or \fBdoor_ucred\fR(3C). .sp .LP Authorization names consist of a hierarchical set of dot (.)-separated words, called the predicate, and an optional object qualifier preceded by a slash character (/). Authorizations listed in \fBuser_attr\fR and \fBprof_attr\fR may contain an asterisk (*) following the final dot in the predicate to indicate a wildcard. The reserved word \fBgrant\fR, used for delegating authorizations, is not matched by *. .sp .LP A user is considered to have been assigned an authorization if all 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 predicate of \fIauthname\fR matches the predicate of an authorization completely, or the predicate does not end in \fBgrant\fR and matches up to the * if present. .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 .RS +4 .TP .ie t \(bu .el o If the authorization includes an object qualifier, then \fIauthname\fR must include the same object qualifier. .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 _ solaris.zone.login/z1solaris.zone.*Yes _ solaris.zone.loginsolaris.zone.*/z1No .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(3C) 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(3C), \fBgetprofattr\fR(3C), \fBgetuserattr\fR(3C), \fBauth_attr\fR(4), \fBnsswitch.conf\fR(4), \fBprof_attr\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5), \fBrbac\fR(5)