1 GETAUTHATTR(3SECDB)             Security Attributes Database Library Functions
   2 
   3 
   4 
   5 NAME
   6        getauthattr, getauthnam, free_authattr, setauthattr, endauthattr,
   7        chkauthattr - get authorization entry
   8 
   9 SYNOPSIS
  10        cc [ flag... ] file... -lsecdb  -lsocket  -lnsl  [ library... ]
  11        #include <auth_attr.h>
  12        #include <secdb.h>
  13 
  14        authattr_t *getauthattr(void);
  15 
  16 
  17        authattr_t *getauthnam(const char *name);
  18 
  19 
  20        void free_authattr(authattr_t *auth);
  21 
  22 
  23        void setauthattr(void);
  24 
  25 
  26        void endauthattr(void);
  27 
  28 
  29        int chkauthattr(const char *authname, const char *username);
  30 
  31 
  32 DESCRIPTION
  33        The getauthattr() and getauthnam() functions each return an
  34        auth_attr(4) entry. Entries can come from any of the sources specified
  35        in the nsswitch.conf(4) file.
  36 
  37 
  38        The getauthattr() function enumerates auth_attr entries. The
  39        getauthnam() function searches for an auth_attr entry with a given
  40        authorization name name. Successive calls to these functions return
  41        either successive auth_attr entries or NULL.
  42 
  43 
  44        Th internal representation of an auth_attr entry is an authattr_t
  45        structure defined in  <auth_attr.h> with   the following members:
  46 
  47          char   *name;        /* name of the authorization */
  48          char   *res1;        /* reserved for future use */
  49          char   *res2;        /* reserved for future use */
  50          char   *short_desc;  /* short description */
  51          char   *long_desc;   /* long description */
  52          kva_t  *attr;        /* array of key-value pair attributes */
  53 
  54 
  55 
  56        The setauthattr() function "rewinds" to the beginning of the
  57        enumeration of auth_attr entries.  Calls to getauthnam() can leave the
  58        enumeration in an indeterminate state. Therefore, setauthattr() should
  59        be called before the first call to getauthattr().
  60 
  61 
  62        The endauthattr() function may be called to indicate that auth_attr
  63        processing is complete; the system may then close any open auth_attr
  64        file, deallocate storage, and so forth.
  65 
  66 
  67        The chkauthattr() function verifies whether or not a user has a given
  68        authorization. It first reads the AUTHS_GRANTED key in the
  69        /etc/security/policy.conf file and returns 1 if it finds a match for
  70        the given authorization. If chkauthattr() does not find a match and the
  71        username is the name of the "console user", defined as the owner of
  72        /dev/console, it first reads the CONSOLE_USER key in
  73        /etc/security/policy.conf and returns 1 if the given authorization is
  74        in any of the profiles specified in the CONSOLE_USER keyword, then
  75        reads the PROFS_GRANTED key in /etc/security/policy.conf and returns 1
  76        if the given authorization is in any profiles specified with the
  77        PROFS_GRANTED keyword. If a match is not found from the default
  78        authorizations and default profiles, chkauthattr() reads the
  79        user_attr(4) database. If it does not find a match in user_attr, it
  80        reads the prof_attr(4) database, using the list of profiles assigned to
  81        the user, and checks if any of the profiles assigned to the user has
  82        the given authorization.  The chkauthattr() function returns 0 if it
  83        does not find a match in any of the three sources or if the user does
  84        not exist.
  85 
  86 
  87        A user is considered to have been assigned an authorization if either
  88        of the following are true:
  89 
  90            o      The authorization name matches exactly any authorization
  91                   assigned in the user_attr or prof_attr databases
  92                   (authorization names are case-sensitive).
  93 
  94            o      The authorization name suffix is not the key word grant and
  95                   the authorization name matches any authorization up to the
  96                   asterisk (*) character assigned in the user_attr or
  97                   prof_attr databases.
  98 
  99 
 100        The examples in the following table illustrate the conditions under
 101        which a user is assigned an authorization.
 102 
 103 
 104 
 105 
 106        +---------------------------+------------------------------+-------------+
 107        |                           | /etc/security/policy.conf or |   Is user   |
 108        |    Authorization name     | user_attr or prof_attr entry | authorized? |
 109        +---------------------------+------------------------------+-------------+
 110        |solaris.printer.postscript |  solaris.printer.postscript  |     Yes     |
 111        |solaris.printer.postscript |      solaris.printer.*       |     Yes     |
 112        |  solaris.printer.grant    |      solaris.printer.*       |     No      |
 113        +---------------------------+------------------------------+-------------+
 114 
 115 
 116        The free_authattr() function releases memory allocated by the
 117        getauthnam() and getauthattr() functions.
 118 
 119 RETURN VALUES
 120        The getauthattr() function returns a pointer to an authattr_t if it
 121        successfully enumerates an entry; otherwise it returns NULL, indicating
 122        the end of the enumeration.
 123 
 124 
 125        The getauthnam() function returns a pointer to an authattr_t if it
 126        successfully locates the requested entry; otherwise it returns NULL.
 127 
 128 
 129        The chkauthattr() function returns 1 if the user is authorized and 0 if
 130        the user does not exist or is not authorized.
 131 
 132 USAGE
 133        The getauthattr() and getauthnam() functions both allocate memory for
 134        the pointers they return. This memory should be deallocated with the
 135        free_authattr() call.
 136 
 137 
 138        Individual attributes in the attr structure can be referred to by
 139        calling the kva_match(3SECDB) function.
 140 
 141 WARNINGS
 142        Because the list of legal keys is likely to expand, code must be
 143        written to ignore unknown key-value pairs without error.
 144 
 145 FILES
 146        /etc/nsswitch.conf
 147                                     configuration file lookup information for
 148                                     the name service switch
 149 
 150 
 151        /etc/user_attr
 152                                     extended user attributes
 153 
 154 
 155        /etc/security/auth_attr
 156                                     authorization attributes
 157 
 158 
 159        /etc/security/policy.conf
 160                                     policy definitions
 161 
 162 
 163        /etc/security/prof_attr
 164                                     profile information
 165 
 166 
 167 ATTRIBUTES
 168        See attributes(5) for descriptions of the following attributes:
 169 
 170 
 171 
 172 
 173        +---------------+-----------------+
 174        |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
 175        +---------------+-----------------+
 176        |MT-Level       | MT-Safe         |
 177        +---------------+-----------------+
 178 
 179 SEE ALSO
 180        getexecattr(3SECDB), getprofattr(3SECDB), getuserattr(3SECDB),
 181        kva_match(3SECDB), auth_attr(4), nsswitch.conf(4), policy.conf(4),
 182        prof_attr(4), user_attr(4), attributes(5), rbac(5)
 183 
 184 
 185 
 186                                 August 13, 2018            GETAUTHATTR(3SECDB)