1 '\" te
   2 .\" Copyright 2018 Peter Tribble
   3 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH GETEXECATTR 3SECDB "Aug 13, 2018"
   8 .SH NAME
   9 getexecattr, free_execattr, setexecattr, endexecattr, getexecuser, getexecprof,
  10 match_execattr \- get execution profile entry
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR... ] \fIfile\fR... -lsecdb  -lsocket  -lnsl  [ \fIlibrary\fR... ]
  15 #include <exec_attr.h>
  16 #include <secdb.h>
  17 
  18 \fBexecattr_t *\fR\fBgetexecattr\fR(\fBvoid\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBfree_execattr\fR(\fBexecattr_t *\fR\fIep\fR);
  24 .fi
  25 
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBsetexecattr\fR(\fBvoid\fR);
  29 .fi
  30 
  31 .LP
  32 .nf
  33 \fBvoid\fR \fBendexecattr\fR(\fBvoid\fR);
  34 .fi
  35 
  36 .LP
  37 .nf
  38 \fBexecattr_t *\fR\fBgetexecuser\fR(\fBconst char *\fR\fIusername\fR, \fBconst char *\fR\fItype\fR,
  39      \fBconst char *\fR\fIid\fR, \fBint\fR \fIsearch_flag\fR);
  40 .fi
  41 
  42 .LP
  43 .nf
  44 \fBexecattr_t *\fR\fBgetexecprof\fR(\fBconst char *\fR\fIprofname\fR, \fBconst char *\fR\fItype\fR,
  45      \fBconst char *\fR\fIid\fR, \fBint\fR \fIsearch_flag\fR);
  46 .fi
  47 
  48 .LP
  49 .nf
  50 \fBexecattr_t *\fR\fBmatch_execattr\fR(\fBexecattr_t *\fR\fIep\fR, \fBchar *\fR\fIprofname\fR,
  51      \fBchar *\fR\fItype\fR, \fBchar *\fR\fIid\fR);
  52 .fi
  53 
  54 .SH DESCRIPTION
  55 .LP
  56 The \fBgetexecattr()\fR function returns a single \fBexec_attr\fR(4) entry.
  57 Entries can come from any of the sources specified in the
  58 \fBnsswitch.conf\fR(4) file.
  59 .sp
  60 .LP
  61 Successive calls to \fBgetexecattr()\fR return either successive
  62 \fBexec_attr\fR entries or \fINULL\fR. Because \fBgetexecattr()\fR always
  63 returns a single entry, the \fBnext\fR pointer in the \fBexecattr_t\fR data
  64 structure points to \fINULL\fR.
  65 .sp
  66 .LP
  67 The internal representation of an \fBexec_attr\fR entry is an \fBexecattr_t\fR
  68 structure defined in <\fBexec_attr.h\fR> with the following members:
  69 .sp
  70 .in +2
  71 .nf
  72 char              *name;   /* name of the profile */
  73 char              *policy; /* policy under which the attributes are */
  74                            /* relevant*/
  75 char              *type;   /* type of profile */
  76 char              *res1;   /* reserved for future use */
  77 char              *res2;   /* reserved for future use */
  78 char              *id;     /* unique identifier */
  79 kva_t             *attr;   /* attributes */
  80 struct execattr_s *next;   /* optional pointer to next profile */
  81 .fi
  82 .in -2
  83 
  84 .sp
  85 .LP
  86 The \fBfree_execattr()\fR function releases memory. It follows the \fBnext\fR
  87 pointers in the \fBexecattr_t\fR structure so that the entire linked list is
  88 released.
  89 .sp
  90 .LP
  91 The \fBsetexecattr()\fR function "rewinds" to the beginning of the enumeration
  92 of \fBexec_attr\fR entries. Calls to \fBgetexecuser()\fR can leave the
  93 enumeration in an indeterminate state. Therefore, \fBsetexecattr()\fR should be
  94 called before the first call to \fBgetexecattr()\fR.
  95 .sp
  96 .LP
  97 The \fBendexecattr()\fR function can be called to indicate that \fBexec_attr\fR
  98 processing is complete; the library can then close any open \fBexec_attr\fR
  99 file, deallocate any internal storage, and so forth.
 100 .sp
 101 .LP
 102 The \fBgetexecuser()\fR function returns a linked list of entries that match
 103 the \fItype\fR and \fIid\fR arguments and have a profile that has been assigned
 104 to the user specified by \fIusername\fR, as described in \fBpasswd\fR(4).
 105 Profiles for the user are obtained from the list of default profiles in
 106 \fB/etc/security/policy.conf\fR (see \fBpolicy.conf\fR(4)) and the
 107 \fBuser_attr\fR(4) database. Only entries in the name service scope for which
 108 the corresponding profile entry is found in the \fBprof_attr\fR(4) database are
 109 returned.
 110 .sp
 111 .LP
 112 The \fBgetexecprof()\fR function returns a linked list of entries that match
 113 the \fItype\fR and \fIid\fR arguments and have the profile specified by the
 114 \fIprofname\fR argument. Only entries in the name service scope for which the
 115 corresponding profile entry is found in the \fBprof_attr\fR database are
 116 returned.
 117 .sp
 118 .LP
 119 Using \fBgetexecuser()\fR and \fBgetexecprof()\fR, programmers can search for
 120 any \fItype\fR argument, such as the manifest constant \fBKV_COMMAND\fR. The
 121 arguments are logically AND-ed together so that only entries exactly matching
 122 all of the arguments are returned. Wildcard matching applies if there is no
 123 exact match for an \fBID\fR. Any argument can be assigned the \fINULL\fR value
 124 to indicate that it is not used as part of the matching criteria. The \fB\fR
 125 search_flag controls whether the function returns the first match
 126 (\fBGET_ONE\fR), setting the \fBnext\fR pointer to \fINULL\fR or all matching
 127 entries (\fBGET_ALL\fR), using the \fBnext\fR pointer to create a linked list
 128 of all entries that meet the search criteria. See \fBEXAMPLES\fR.
 129 .sp
 130 .LP
 131 Once a list of entries is returned by \fBgetexecuser()\fR or
 132 \fBgetexecprof()\fR, the convenience function \fBmatch_execattr()\fR can be
 133 used to identify an individual entry. It returns a pointer to the individual
 134 element with the same profile name (\fIprofname\fR), type name (\fItype\fR),
 135 and \fIid\fR. Function parameters set to \fINULL\fR are not used as part of the
 136 matching criteria. In the event that multiple entries meet the matching
 137 criteria, only a pointer to the first entry is returned. The
 138 \fBkva_match\fR(3SECDB) function can be used to look up a key in a key-value
 139 array.
 140 .SH RETURN VALUES
 141 .LP
 142 Those functions returning data only return data related to the active policy.
 143 The \fBgetexecattr()\fR function returns a pointer to a \fBexecattr_t\fR if it
 144 successfully enumerates an entry; otherwise it returns \fINULL\fR, indicating
 145 the end of the enumeration.
 146 .SH USAGE
 147 .LP
 148 The \fBgetexecattr()\fR, \fBgetexecuser()\fR, and \fBgetexecprof()\fR functions
 149 all allocate memory for the pointers they return. This memory should be
 150 deallocated with the \fBfree_execattr()\fR call. The \fBmatch_execattr()\fR
 151 function does not allocate any memory. Therefore, pointers returned by this
 152 function should not be deallocated.
 153 .sp
 154 .LP
 155 Individual attributes may be referenced in the \fBattr\fR structure by calling
 156 the \fBkva_match\fR(3SECDB) function.
 157 .SH EXAMPLES
 158 .LP
 159 \fBExample 1 \fRFind all profiles that have the \fBping\fR command.
 160 .sp
 161 .in +2
 162 .nf
 163 if ((execprof=getexecprof(NULL, KV_COMMAND, "/usr/sbin/ping",
 164     GET_ONE)) == NULL) {
 165         /* do error */
 166 }
 167 .fi
 168 .in -2
 169 
 170 .LP
 171 \fBExample 2 \fRFind the entry for the \fBping\fR command in the Network
 172 Administration Profile.
 173 .sp
 174 .in +2
 175 .nf
 176 if ((execprof=getexecprof("Network Administration", KV_COMMAND,
 177     "/usr/sbin/ping", GET_ALL))==NULL) {
 178         /* do error */
 179 }
 180 .fi
 181 .in -2
 182 
 183 .LP
 184 \fBExample 3 \fRTell everything that can be done in the Filesystem Security
 185 profile.
 186 .sp
 187 .in +2
 188 .nf
 189 if ((execprof=getexecprof("Filesystem Security", NULL, NULL,
 190     GET_ALL))==NULL)) {
 191         /* do error */
 192 }
 193 .fi
 194 .in -2
 195 
 196 .LP
 197 \fBExample 4 \fRTell if the \fBtar\fR utility is in a profile assigned to user
 198 wetmore. If there is no exact profile entry, the wildcard (*), if defined, is
 199 returned.
 200 .sp
 201 .in +2
 202 .nf
 203 if ((execprof=getexecuser("wetmore", KV_COMMAND, "/usr/bin/tar",
 204     GET_ONE))==NULL) {
 205         /* do error */
 206 }
 207 .fi
 208 .in -2
 209 
 210 .SH FILES
 211 .ne 2
 212 .na
 213 \fB\fB/etc/nsswitch.conf\fR\fR
 214 .ad
 215 .RS 29n
 216 configuration file lookup information for the name service switch
 217 .RE
 218 
 219 .sp
 220 .ne 2
 221 .na
 222 \fB\fB/etc/user_attr\fR\fR
 223 .ad
 224 .RS 29n
 225 extended user attributes
 226 .RE
 227 
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fB/etc/security/exec_attr\fR\fR
 232 .ad
 233 .RS 29n
 234 execution profiles
 235 .RE
 236 
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fB/etc/security/policy.conf\fR\fR
 241 .ad
 242 .RS 29n
 243 policy definitions
 244 .RE
 245 
 246 .sp
 247 .ne 2
 248 .na
 249 \fB\fB/etc/security/prof_attr\fR\fR
 250 .ad
 251 .RS 29n
 252 profile information
 253 .RE
 254 
 255 .SH ATTRIBUTES
 256 .LP
 257 See \fBattributes\fR(5) for descriptions of the following attributes:
 258 .sp
 259 
 260 .sp
 261 .TS
 262 box;
 263 c | c
 264 l | l .
 265 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 266 _
 267 MT-Level        MT-Safe
 268 .TE
 269 
 270 .SH SEE ALSO
 271 .LP
 272 \fBgetauthattr\fR(3SECDB), \fBgetprofattr\fR(3SECDB), \fBgetuserattr\fR(3SECDB),
 273 \fBkva_match\fR(3SECDB), \fBexec_attr\fR(4), \fBpasswd\fR(4),
 274 \fBpolicy.conf\fR(4), \fBprof_attr\fR(4), \fBuser_attr\fR(4),
 275 \fBattributes\fR(5)