From Nicolas.Williams at sun.com Fri Aug 14 16:18:40 2009 From: Nicolas.Williams at sun.com (Nicolas Williams) Date: Fri, 14 Aug 2009 18:18:40 -0500 Subject: [cpg-discuss] CPGs and "legacy" process groups In-Reply-To: <20090623032315.GN1308@Sun.COM> References: <20090623032315.GN1308@Sun.COM> Message-ID: <20090814231840.GK1043@Sun.COM> I've thought long and hard about this and I've come to conclude that we can represent some "legacy" process groups as CPGs easily enough: - System V process groups - SVR4/BSD sessions - tasks Audit context can be left for much later. Process contracts can't easily be represented as CPGs. I've also resolved a variety of related and unrelated issues (e.g., Gary's comments re: su and pam_unix_cred). I've expanded the use of doors (to match needs of klpd), and I've replaced "user data" with environment variables (this simplifies pam_krb5). Updated manpages attached. Garret: You had asked that I remove the ability to change another process' CPG memberships, but it turns out that there's precedent for this in setpgid(2), and there's good reasons for it besides the one I'd proffered (which was: to make it easy to implement setpag(1) variants that modify the parent process' PAG). More notes below. On Mon, Jun 22, 2009 at 10:23:16PM -0500, Nicolas Williams wrote: > But note that the semantics of these are, mostly, significantly > different from CPG semantics, specifically: > > - pgrps and sessions: ID namespace shared with process ID namespace; > change of pgrp/sid allowed only in some cases (when the process is > not already a pgrp or sid leader), and with side effects > (dropping/changing ctty) This is addressed by making such "CPGs" invalid when the last member process leaves. The CPG will "shadow" the actual pgrp/sid hanging off of proc_t. Otherwise we'd have a PID exhaustion attack: a variant of a fork-bomb where each process changes pgrp, opens one file, forks, ... to accumulate, say, 1,000 processes with 1,000 files open, each with different CPGs, to add up to 1,001,000 process group IDs (and therefore PIDs) consumed by just 1,000 processes! > - projects: not really a group -- can't create new ones, can only > change project ID, and only by joining a new task I'll leave this for a future day. > - tasks come pretty close to CPG semantics Tasks were worth tackling now though. > - process contracts can only be created at fork time, can't be parted, > can't be joined ETOOHARD. > - audit context requires privilege to get/set but otherwise is very > similar to CPG semantics Future. Nico -- -------------- next part -------------- Credentials Process Groups CPG_CHANGE(2) NAME cpg_change - Manipulate Credentials Process Groups SYNOPSIS cc [ flag... ] file... -lcpg [ library... ] #include /* CPG type/class registration */ idtype_t cpg_type_reg(const char *name, const char *classes, uint32_t semantics, const char *privs, size_t env_size); int cpg_type_unreg(const char *name); /* Door registration */ int cpg_reg_door(char *name, id_t cpg_id, int door_fd, cpg_door_type_t dtype, cpg_door_scope_t dscope, int devents) /* Map idtype_t to setpriority(3C) "int who" */ #define CPG_IDTYPE2WHO(/* idtype_t */ idtype) ... /* CPG join new/existing functions */ int cpg_change(pid_t victim, const char *join_new, const char *join_existing, pid_t like_pid, int flags, ...); int cpg_change1(pid_t victim, idtype_t idtype, id_t *cpg_id, int flags, ...); /* List registrations, a process' CPG memberships, ... */ idtype cpg_type2idtype(const char *name); char *cpg_idtype2type(idtype_t idtype); int cpg_type_list(idtype_t idtype, char **name, uint32_t *semantics, char **privs, size_t *env_size); int cpg_getids(pid_t pid, int count, idtype_t *idtypes, id_t *cpg_ids) SunOS 5.11 Last change: 2009-08-14 1 Credentials Process Groups CPG_CHANGE(2) /* Functions acting on CPGs */ int cpg_getid(pid_t pid, idtype_t idtype, id_t *cpg_id, pid_t *leader, uid_t *owner); int cpg_final(pid_t pid, idtype_t idtype, id_t cpg_id, int what); int cpg_getdoor(pid_t pid, idtype_t idtype, id_t cpg_id, cpg_door_type_t dtype, cpg_door_scope_t dscope); int cpg_chown(pid_t pid, idtype_t idtype, id_t cpg_id, uid_t owner); int cpg_environ(pid_t pid, idtype_t idtype, id_t cpg_id, void *buf, size_t bufsize); int cpg_getenv(pid_t pid, idtype_t idtype, id_t cpg_id, const char *var, char *buf, size_t bufzise); char *cpg_getenv2(pid_t pid, idtype_t idtype, id_t cpg_id, const char *var); int cpg_putenv(pid_t pid, idtype_t idtype, id_t cpg_id, const char *varval); PARAMETERS name A CPG type name. CPG type names must start with a lower-case US-ASCII letter, and must consist of between 1 and 254 US-ASCII letters, digits, at-signs, hyphens and/or underscores. classes A comma-separated list of CPG class names. CPG class names must start with an upper-case US-ASCII letter, and must consist of between 1 and 254 US-ASCII letters, digits, at-signs, hyphens and/or underscores. idtype An identifier of ID types. See sigsend(2), pset_bind(2), poolbind(1M), etcetera. cpg_id A CPG identifier. Usable as a group ID in most library functions and system calls with idtype_t and id_t arguments. semantics Semantics of CPG types. See CPG Semantics and Privileges. privs Privileges required for various CPG-related operations. See CPG Semantics and Privileges. join_new, join_existing SunOS 5.11 Last change: 2009-08-14 2 Credentials Process Groups CPG_CHANGE(2) Comma-separated lists of CPG types, classes, CPG IDs and negated forms of those same (i.e., prefixed with an exclamation point ("!")). Specific CPG IDs may be given as: : (e.g., 2:123, meaning System V process group number 123). pid, like_pid, victim, leader Process IDs. pid and like_pid is used to refer to a CPG that the pid or like_pid process is a member of. victim is used to refer to a process whose CPG memberships are to be altered. leader refers to the process that created a give CPG. If victim is (pid_t)-1, then the caller's process is the victim. owner The ID of a user that owns a given CPG. dtype Purpose of a door. There are three types: EVENTS, UPCALL, and USER. See Monitoring CPG Events. dscope Scope of a door being registered. There are two scopes: CPG type-wide (TYPE), and per-CPG (CPG). See Monitoring CPG Events. DESCRIPTION Credentials Process Groups (CPGs) allow one to create arbitrary process group types. Each CPG type has a name and a set of semantics flags associated with it, and each CPG type may be a member of one or more classes of CPG types. A process can be a member of more than one CPG, but a process can be in at most one CPG of each CPG type. Once a process is a member of a CPG for some CPG type, it and its progeny must always be members of a CPG of that same type. Each CPG has an ID of type id_t, from a per-CPG type ID type identified by an idtype_t value. CPG membership is tracked through the process credentials structure in the kernel, which means that CPGs are referenced from, for example, open file references as well as from processes. A CPG remains in existence as long as any processes are members of it or, if allowed for each given CPG type, as long as there exist open file references where the file was opened by a process that was a member of that CPG. However, CPG references by member processes are tracked separately from CPG references from open files. CPG IDs do not share a namespace with process IDs, except in the case of CPG types which correspond to legacy process group types (see Pre-Defined CPG Types and Classes). SunOS 5.11 Last change: 2009-08-14 3 Credentials Process Groups CPG_CHANGE(2) There are three types of operations related to CPGS that are provided by these system calls: o Operations on CPG types: * registration * unregistration * enumeration * registration of doors for event notification, IPC o Operations on CPG memberships: join a process to a new CPG of a given type join an existing CPG o Operations on CPGs themselves: get CPG IDs, owner UID, group leader process IDs set CPG owner get/set environment variables get/set doors for event notification, IPC Registration of CPG Types and Classes Use cpg_type_reg() to register a new CPG type with the given name, in the given CPG classes, and with the given semantics. CPG type and class names must conform to the constraints listed in PARAMETERS. CPG type names are normally allocated by Sun, however, names of the form type-name at domainname may be used without prior approval from Sun, with a domainname that the developer is associated with as the domainname. The optional classes argument (i.e., it may be NULL) must conform to the constraints listed in PARAMETERS. As with types, class names of the form Class-name at domainname can be used without prior approval from Sun, but class names without an '@' are assigned by Sun. The optional privs argument allows control over what privilege(s) is required for each of various operations on CPGs or on processes' CPG memberships; this argument and its default value are described in CPG Semantics and Privileges. CPG types are assigned an idtype_t value at registration time. CPG types corresponding to process group types that were introduced prior to CPGs (e.g., System V process groups and session IDs, task IDs, etcetera) are assigned the existing idtype_t; others are assigned idtype_t values dynamically. The former are referred to as "legacy" CPG types and are all members of the "Legacy" class. An integer value for the who argument of setpriority(3C) can be derived from an idtype_t value by using the CPG_IDTYPE2WHO() macro. SunOS 5.11 Last change: 2009-08-14 4 Credentials Process Groups CPG_CHANGE(2) The process that first joins a new CPG is its "leader". There is nothing special about the leader of a CPG, except as accorded by drivers and kernel subsystems that may associate controlling devices with CPGs. See Controlling Devices. CPGs may also have an "environment" associated with them, consisting of variables and values, much like the normal parocess enviornment (see env(1)). Variable names must consist of US-ASCII letters, digits and/or underscores and must be at least one character long. CPGs are allowed up to env_size bytes to store their environment; the size of an environment consists of one byte plues the sum of the lengths of variable names and values plus two (for an '=' and a NUL terminator). CPG environment variable names that start with one underscore can be set only by kernel code, and they are public interfaces (see driver documentation). CPG environment variable names that start with two or more underscores can be set only by kernel code, and they are private interfaces. CPG environment variable names that start with one or more underscores don't count against the CPG's type's env_size. Well-known classes are described below in Pre-Defined CPG Types and Classes. cpg_type_reg() may be called multiple times for the same CPG type. Each re-registration simply updates the semantics, classes, privs and env_size of the CPG type. Each zone has its own, independent CPG type and class namespace, and may have distinct idtype_t assignments for non-legacy CPG types. Use cpg_type_unreg() to unregister a CPG type. Unregistering a CPG type causes that CPG type to no longer be available for new CPGs. cpg_type_unreg() does not block; any existing CPGs of the given type remain as they are until no longer referenced. However, a CPG type cannot be re- registered after being unregistered until all existing CPGs of that type have disappeared. Listing CPG Types and Memberships Use cpg_type_list() to list CPG types. Call it repeatedly, with idtype initially set to 0 and incremented byone for each call, until cpg_type_list() returns -1. If a CPG type has been unregistered cpg_type_list() returns 0 but sets name to NULL. The caller must free() the name and privs outputs. SunOS 5.11 Last change: 2009-08-14 5 Credentials Process Groups CPG_CHANGE(2) Use cpg_getids() to list the CPG memberships of a process identified by pid (the caller, if (pid_t)-1). idtypes and cpg_ids must point to arrays of count elements, wherein the list of CPGs will be placed on return. This function returns the number of CPG memberships of the process. CPG memberships that the caller is not permitted to observe are excluded. Monitoring CPG Events The CPG subsystem allows doors to be associated with CPG types and/or individual CPGs. Up to three doors can be registered with each CPG type or CPG: * CPG event notifications * Driver IPC upcalls * Application IPC Use cpg_reg_door() to register a door for a CPG type in the caller's zone. Set the dtype argument to EVENTS to register a door for event notification. Set the dtype argument to UPCALL to receive upcalls from kernel code. Set the dtype argument to USER to receive door calls from other user applications. The dscope argument indicates whether a door should be associated with a CPG type (TYPE_WIDE), named by the name argument, or a single CPG (CPG) named by the name and cpg_id arguments. The protocols used in the case of UPCALL and USER doors is specific to each CPG type, and these are not described here. USER and UPCALL doors may be accessed by calling cpg_getdoor() with the desired scope and door type (retrieval of EVENTS and UPCALL door always requires all zone privileges and effective UID 0). The kernel will upcall a CPG type's EVENTS door to report that a CPG has no more references to it from either any process or any open file reference. There can be only one such door per CPG type in any given zone. The upcall will have the following data: a 32-bit event ID (see below), a 32-bit idtype_t value, a 32-bit CPG ID, a reserved 64-bit field (currently set to 0), and optional data (see below). The events of interest to the door server are listed in the devents argument (see below). To unregister this door simply close the door server file descriptor. Event notifications are synchronous (the operations that trigger event notification will not complete until the door call completes), but not serialized (i.e., if multiple threads call, for example, cpg_putenv() on the same CPG simultaneously, then the upcalls may use more than one door server thread). Asynchronous event notification (where the SunOS 5.11 Last change: 2009-08-14 6 Credentials Process Groups CPG_CHANGE(2) door upcall is done by a kernel task queue) may be added later. Event IDs for door upcalls include: 0x00000000 A new CPG has been created. Event notification doors associated with specific CPGs get this event only when CPG_F_COPY is used (see below). 0x00000001 An environment variable has been changed. A string for the form variable=value, including NUL terminator, is included as the optional data. 0x000000002 No processes remain that are members of this CPG. The environment of the CPG is included as the optional data, and is encoded as the concatenation of variable=value, each terminated by a NUL, with an additional trailing NUL after the last variable. 0x000000003 No references remain to this CPG from any open files nor are any processes members of it. The environment of the CPG is included as the optional data (see above). 0x000000004 The CPG type has been unregistered. 0x000000004 The CPG type has been unregistered and there remain no CPGs of that type. Event notification doors associated with specific CPGs do not get this event. The devents argument is a bitmask: CPG_EV_SYNC_CREATE If set then CPG creation events are of interest. CPG_EV_SYNC_PUTENV If set then CPG environment variable modifications (by user code) are of interest. CPG_EV_SYNC_EMPTY If set then CPG emptiness events (no member processes remain) are of interest. CPG_EV_SYNC_UNREF If set then CPG unreferenced events are of interest. CPG_EV_SYNC_UNREG SunOS 5.11 Last change: 2009-08-14 7 Credentials Process Groups CPG_CHANGE(2) If set then CPG type unregistration events are of interest. CPG_EV_SYNC_UNREG_COMPLETE If set then CPG type unregistration completion events are of interest. Managing CPG Memberships The remaining CPG system calls deal with CPG membership and CPG attributes. There are several ways to refer to a CPG: by {CPG type name, process ID}, {idtype_t, pid_t} and/or by {idtype_t, id_t}, depending on the context. Use cpg_change() to manage a victim process' CPG memberships for the CPGs or CPG types/classes given by join_new and join_existing. New CPGs for all types/classes indicated by join_new will be joined (and existing CPG memberships for those types will be parted). The victim will be joined to the CPGs listed by ID in join_existing and to the CPGs of types/classes listed in join_existing that the like_pid process is a member of (or, if it isn't, then the victim will be parted from them). As with setpgid(2), one reason for allowing changes to other process' CPG memberships is to allow shells and other such applications to construct groups of processes where all the processes can be children of the shell, instead of having to be progeny of their process group leader. If there is any overlap between the three sets of types/classes/IDs then join_new takes precedence over join_existing. CPG changes are atomic -- all happen, or none at all -- unless the CPG_F_ALL_PERMITTED flag is used, in which case any requested CPG changes which are disallowed will be ignored (but the other changes are still atomic with respect to such errors as ENOMEM). The cpg_change1() function allows the caller to change the membership of a single CPG type, given by the idtype argument. If the cpg_id argument is NULL or points to the value (id_t)-1, then the caller will be joined to a new CPG of the given idtype_t. If the cpg_id argument is non-NULL and points to a valid CPG ID, then the caller will be joined to the given CPG. If CPG_F_TYPE_SPECIFIC_DATA is included in flags then additional arguments must be provided as follows: a CPG type name (const char *), followed by arguments specific to that CPG type. The variable arguments list is terminated by a SunOS 5.11 Last change: 2009-08-14 8 Credentials Process Groups CPG_CHANGE(2) NULL CPG type name. Currently CPG type-specific data are defined only for Solaris tasks, where the arguments are: a pointer to a project ID, and a pointer to flags (see Pre- Defined CPG Types and Classes). (Note that the cpg_change() and cpg_change1() functions are similar to setpgid(2) in that they allow the caller to change other processes' process group memberships, subject, of course, to access controls.) The following are the flags accepted by cpg_change(): CPG_F_ALL_PERMITTED If CPG_F_ALL_PERMITTED is set then cpg_change() and cpg_change1() will skip any CPG types which disallow the given operation. Normally cpg_change() and cpg_change1() will leave the victim process' CPG memberships unchanged if permission would be denied for the given operation on one or more of the memberships of the given types. CPG_F_FINAL This flag cause any new CPGs to be "final", as if cpg_final(..., CPG_W_MEMBERSHIP) had been called (meaning that their members cannot leave them). CPG_F_COPY This flag causes new CPGs to copy the environment and door registrations of the CPGs they replace, if any. CPG_F_TYPE_SPECIFIC_DATA If set, then a variable argument list must follow (see above). Operations on CPGs Use cpg_getid() to get the ID, owner UID, if any, and leader process ID, if any, of a CPG identified by {process ID, ID type}. If the pid argument is (pid_t)-1 then the calling process' ID will be substituted. The other functions described in this section operate on a CPG identified by {process ID, ID type} or {ID type, CPG ID}. One of the pid and idtype arguments must be (pid_t)-1 or (idtype_t)-1, and the other must be a positive number. Use cpg_final() to disallow leaving a given CPG (what | CPG_W_MEMBERSHIP > 0), disallow changing environment variables (what | CPG_W_ENV > 0), and/or disallow changing doors (what | CPG_W_DOOR > 0). SunOS 5.11 Last change: 2009-08-14 9 Credentials Process Groups CPG_CHANGE(2) Use cpg_getdoor() to retrieve a door associated with a CPG or CPG type. Use cpg_chown() to set the UID that owns a CPG. It is allowed to set the ownership of a CPG to (uid_t)-1 (see CPG Semantics and Privileges). The owner of a new CPG is always the same as the effective UID of the caller of cpg_change()/cpg_change1(). Use cpg_putenv() to set or remove an environment-like variable for the given CPG. cpg_putenv() removes a variable from the environment if varval has no '=' in it, else it sets the variable to the string following the first '=' (possibly the empty string). Use cpg_getenv() to get the value of a given CPG environment variable. cpg_getenv2() returns allocated memory; the caller must call free() to release that memory. Use cpg_environ() to get the entire environment associated with a CPG. The environment is encoded as a the concatenation of the NUL-terminated variable-value strings. Utility Functions Use cpg_type2idtype() to easily lookup the assigned ID type for a named CPG type. Use cpg_idtype2type() to lookup the type name for a given ID type. CPG Semantics and Privileges The CPG type semantics flags are: CPG_S_DISTINGUISH_CRED Processes with process credentials that differ only with respect to membership in CPGs whose semantics include this flag will be treated as having distinct process credentials by the kernel private function crcmp(). This flag should be set for CPG types that are in the "NetworkIdentity" class, if the credentials associated with such CPGs can be used by, for example, the NFS, CIFS or other clients implemented in the kernel. (Some such clients use crcmp() to compare process credentials that are associated with client state obtained with user cryptographic credentials.) CPG_S_INVALID_WHEN_EMPTY CPGs of CPG types with this flag are removed (or, rather, become invalid) when the last member process exits, and will not be visible through the credentials used to obtain open file references. Normally a CPG SunOS 5.11 Last change: 2009-08-14 10 Credentials Process Groups CPG_CHANGE(2) remains valid as long as there are open file references where the file was opened by a process that is a member of that CPG. This semantics flag is typically set for CPG types in the Legacy class. This flag is required in order to support the use of legacy process group types, as CPGs, whose ID namespace is shared with the process ID namespace. CPG_S_CHANGE_SELF_ONLY CPG types of this semantics flag don't allow changes of CPG membership of any victim process other than the caller of cpg_change(). Use CPG_F_ALL_PERMITTED to avoid failures when changing CPGs for classes that include types with this semantics flag. CPG_S_DISALLOW_EXPLICIT_CHANGE CPG types with this semantics flag don't allow changes of CPG membership via the cpg_change() and cpg_change1() calls. Legacy CPG types usually have this semantics flag. Use CPG_F_ALL_PERMITTED to avoid failures when changing CPGs for classes that include types with this semantics flag. CPG_S_NO_OWNER CPG types with this semantics flag don't have an owner for CPGs. Chown attempts will fail, and (uid_t)-1 will be reported as the owner of such CPGs. CPG_S_DISALLOW_JOIN_EXISTING Existing CPGs of this type cannot be joined. Use CPG_F_ALL_PERMITTED to avoid failures when changing CPGs for classes that include types with this semantics flag. CPG_S DISALLOW_LEAVE Processes must be members of CPGs with this flag. CPG_S_ALLOW_TYPE_EVENTS_DOOR CPG_S_ALLOW_CPG_EVENTS_DOOR CPG_S_ALLOW_TYPE_UPCALL_DOOR CPG_S_ALLOW_CPG_UPCALL_DOOR CPG_S_ALLOW_TYPE_USER_DOOR CPG_S_ALLOW_CPG_USER_DOOR These semantics flags indicate whether doors of a given scope (TYPE or CPG) and type (EVENTS, UPCALL, or USER) are allowed. By default none are allowed. The privs argument to cpg_type_reg() is a semi-colon separated list of rules of the form = and -, where is one of: SunOS 5.11 Last change: 2009-08-14 11 Credentials Process Groups CPG_CHANGE(2) - join-new - leave These apply to CPG creation, and to the act of leaving a CPG (in order to join another). The caller must also separately have permission or privilege to modify the victim process -- see the PRIV_PROC_OWNER privilege in privileges(5). Default: "all-zone" for non-owner-join, "none" for the others (see below). - observe Indicates what privileges are needed in order to be able to observe a given CPG type (that it has been registered, what its semantics are, its ID type, ...). These privileges are also required to observe any CPG membeships. Default: "none". - reg-door This applies to callers of cpg_reg_door() with dscope == TYPE. Default: "all-zone". - get This applies to callers of cpg_getdoor() using dscope == TYPE and type == USER. For type other than USER all zone privileges are required. Default: "none". is one of: - non-owner - non-member - owner-member is one of: - join-existing Applies to callers of cpg_change() to join existing CPGs. Defaults: "priv_proc_info", for non-members (the non- members privilege requirement always applies, necessarily, for join-existing), "priv_proc_owner" for non-owners, "none" for owner members. - observe Indicates what privileges are needed to observe a process' CPG membership for a given CPG type. A caller SunOS 5.11 Last change: 2009-08-14 12 Credentials Process Groups CPG_CHANGE(2) lacking such privileges will not be able to determine whether a process belongs to any CPG of that type, nor what that CPG's ID, owner, or leader might be. Default: for all three subject types. - get Applies to callers of cpg_getenv() and cpg_getdoor() (to retrieve USER type doors). To be able to get a CPG's environment variables and doors, the user must also be able to observe a CPG membership. To retrieve doors of type UPCALL or EVENTS the caller must also have all zone privileges asserted and effective UID 0. Defaults: "priv_proc_info", for non-members, "priv_proc_owner" for non-owners, "none" for owner members. - modify This apply to callers of cpg_chown() and cpg_putenv(). Defaults: "priv_proc_session", for non-members, and "priv_proc_owner" for non-owners, "none" for owner members. When a CPG system call is called to operate on a given CPG or on a process' CPG memberships, the kernel first determines whether the caller is a non-member and/or non-owner, or a member and owner of the CPG in question, and will then compute the union of the privilege sets for all the rules that apply to the given operation, then it will check if the caller has all those privileges in its effective set -- if not, the operation will fail with EACCES. If the owner of the given CPG is UID 0, then all zone privileges will be required of the caller if the caller does not have UID 0 as its effective UID. For example, cpg_getenv() by a non-member and non-owner of the given CPG will compute the union of the privilege sets given by the non-member-getenv and non-owner-getenv rules in the CPG's type's registered privs. The specifies a set of privileges that will be required to perform a given i, and consists of one of: - all (all privileges) - all-zone (all zone privileges) - none (no privileges) - default (default privilege set for the given operation) - priv_* (a single privilege) SunOS 5.11 Last change: 2009-08-14 13 Credentials Process Groups CPG_CHANGE(2) The given set of privileges will be required to be effective for the caller's to succeed. Sets of privileges other than "default", "all" or "all-zone" must be empty ("none") or have a single privilege ("priv_*"; see priv_getbyname(3C))). If a non-NULL privs is given then it must specify privileges for all operations known at the time. Note that new operations may be added in the future; earlier applications that register CPG types without specifying privileges needed for such new operations will get default behavior to be specified when such operations are added. Pre-Defined CPG Types and Classes The following are pre-defined CPG type classes: Login Login application processes are placed in new CPGs of this class when a user logs in; this is done by pam_unix_cred(5). This class excludes legacy process group types. The Unix credentials PAM module, called with PAM_ESTABLISH_CRED, joins the caller to new CPGs in this class. That is, it calls cpg_change(-1, "Login", "", -1, 0). See pam_unix_cred(5). ControllingDevice CPG types of this class are used to track controlling device associations of a process, much like controlling ttys. This class should be used for audio devices, display devices, etcetera, and does include one legacy process group type. ResourceControl CPG types of this class are used for resource control purposes (see below). NetworkIdentity CPG types of this class are used to associate cryptographic credentials of a user with the user's processes. CPG types of this class should typically also be members of the "Login" CPG type class. All The "All" class includes all CPG types other than legacy CPG types (see below). This class' membership is computed; all CPG types are in this class, even if "All" is not listed at registration time. Unclassed All CPG types with unspecified class(es) are in the SunOS 5.11 Last change: 2009-08-14 14 Credentials Process Groups CPG_CHANGE(2) "Unclassed" class in addition to the "All" class. Legacy The "Legacy" class contains all legacy CPG types (see below). Only pre-defined CPG types may be members of this class. Some CPG types may be pre-defined that correspond to legacy process grouping types. Not all values of idtype_t have corresponding CPG registrations (see Listing CPG Types and Memberships). The pre-defined CPG types are: pgrp ID type: P_PGID. Classes: Legacy. Semantics: CPG_S_INVALID_WHEN_EMPTY, CPG_S_NO_OWNER. Environment size: 0. Environment variables: _session= Privs: default. Type-specific arguments: none. Constraints: See setpgid(2). Description: System V process groups. session ID type: P_SID. Classes: Legacy, ControllingDevice. Semantics: CPG_S_INVALID_WHEN_EMPTY, CPG_S_NO_OWNER, CPG_S_CHANGE_SELF_ONLY, CPG_S_DISALLOW_JOIN_EXISTING Environment size: 0. Environment variables: _has_cdev=1|0 _ctty_major=[] _ctty_minor=[] Privs: default. Type-specific arguments: none. Constraints: See setsid(2). Description: System V / BSD sessions. See setsid(2) and Controlling Devices for information about how controlling devices are acquired. task SunOS 5.11 Last change: 2009-08-14 15 Credentials Process Groups CPG_CHANGE(2) ID type: P_TASKID. Classes: Legacy, ResourceControl. Semantics: CPG_S_INVALID_WHEN_EMPTY, CPG_S_NO_OWNER, CPG_S_CHANGE_SELF_ONLY, CPG_S_DISALLOW_JOIN_EXISTING Environment size: 0. Environment variables: _projid= Privs: default. Type-specific arguments: const char *project, int *flags Constraints: See settaskid(2). Description: Solaris tasks. If type-specific arguments are not given then the project will be that of the user whose UID is the effective UID of the victim process, and TASK_NORMAL. network_identity ID type: dynamically assigned at zone boot time Classes: Login, NetworkIdentity. Semantics: CPG_S_DISTINGUISH_CRED. Environment size: 1024. Environment variables: see krb5envvar(5). Privs: default. Type-specific arguments: none. Constraints: None. Description: Generic CPG type for referencing a user's network identity and/or credentials. For example: the Solaris Kerberos subsystem looks for environment variables in this CPG (see krb5envvar(5), pam_krb5(5)). Controlling Devices Drivers and kernel subsystems may associate devices with CPGs, much like the TTY/PTS subsystem associates "controlling terminals" with System V / BSD sessions. CPGs with which controlling devices are associated should be members of the ControllingDevice class. When joining a new CPG of a type in the ControllingDevice class, there should, initially, not be any controlling device associated with the new CPG. The details of how controlling devices are associated with a CPG may vary by CPG type, driver and/or subsystem, but it is recommended that drivers emulate the System V / BSD session model: new CPGs should have no controlling device, and the first device of the right type opened by the group leader after changing CPG IDs should become the controlling device for that CPG. It is further recommended that drivers use CPG environment variables (with names starting with underscore) to track whether a CPG has or has had a controlling device associated SunOS 5.11 Last change: 2009-08-14 16 Credentials Process Groups CPG_CHANGE(2) with it, and that they track the CPG ID type and ID in the controlling device. Note that a CPG type that is in the ControllingDevice need not have a controlling tty-like device. Imagine a CPG type for tracking X11 display and authorization cookies -- there may be no way to "acquire" a controlling X11 display other than by explicitly setting DISPLAY and related environment variables in the CPG. But it would nonetheless be useful to have such a CPG type be in the ControllingDevice class, as joining a process to new ControllingDevice CPGs would detach the process from all controlling devices, including X11 displays. RETURN VALUES Upon successful CPG type registration, cpg_type_reg() returns the ID type of the CPG type, else it returns (idtype_t)-1. cpg_idtype2type() returns NULL if the given ID type is not registered, or the name of that CPG type. cpg_getenv2() returns NULL if the given CPG doesn't exist or if the given variable is not assigned in the given CPG's environment, else it returns the variable's value. For all other functions, upon successful completion, 0 is returned. Otherwise, -1 (or (idtype_t)-1) is returned, errno is set to indicate the error. ERRORS The CPG functions will fail if: EINVAL The given CPG type name or idtype_t is not known, the given flags or semantics, the the given privs is malformed, or some other constraint described above has been violated. E2BIG Returned by cpg_environ() and cpg_getenv() when the buffer supplied by the caller is too small to hold the result value. ESRCH No process exists with the given process ID. EFAULT One or more of the pointers pointed to illegal addresses. ENOCPG SunOS 5.11 Last change: 2009-08-14 17 Credentials Process Groups CPG_CHANGE(2) The given process is not a member of any CPG of the given type, the CPG type does not exist, or no more CPG types may be registered in the caller's zone. ENOCPGENV The given environment variable does not exist in the given CPG. EBADF The given file descriptor is invalid or not a door file descriptor. EPERM Permission denied. EACCES Access denied. ECPGEXIST The given CPG type existed before, has been unregistered, and there still exist CPGs of that type, therefore it may not be re-registered at this time. EXAMPLES Example 1: Changing a process' System V process group err = cpg_change(victim_pid, "pgrp", "", -1, 0); if (err < 0) ... Example 2: Making a process's CPG memberships match another's as much as possible err = cpg_change(victim_pid, "", "All", like_pid, CPG_F_ALL_PERMITTED); if (err < 0) ... Example 3: pam_unix_cred(5)-like applications err = cpg_change(-1, "Login", "", -1, CPG_F_TYPE_SPECIFIC_DATA, "task", project, TASK_NORMAL, NULL); if (err < 0) ... Example 4: Finding Kerberos V credentials idtype_t idtype; char *ccache = NULL; SunOS 5.11 Last change: 2009-08-14 18 Credentials Process Groups CPG_CHANGE(2) idtype = cpg_type2idtype("network_identity"); if (idtype == (idtype_t)-1) goto fallback; ccache = cpg_getenv2(-1, idtype, -1, "KRB5CCNAME"); fallback: if (ccache == NULL || *ccache == '\0') { free(ccache); ccache = getenv("KRB5CCNAME"); } Example 5: Dropping all controlling devices /* Join new ControllingDevice CPGs ... */ err = cpg_change(-1, "", "ControllingDevice", "", -1); if (err < 0) ... /* ... then fork() and exit the parent */ switch (fork()) { case 0: /* Can't acquire controlling devices now */ break; case -1: /* failure */ ... default: /* Exit to prevent ever getting a cdev */ exit(0); } Example 5: Privilege specifications SunOS 5.11 Last change: 2009-08-14 19 Credentials Process Groups CPG_CHANGE(2) /* * Audit context-like privilege specifications * * Only privileged applications can observe * this CPG type and membership of CPGs of this * type. */ aprivs = "join-new=all-zone;leave=all-zone;" "observe=all-zone;reg-door=all-zone;" "get=all-zone;" "non-owner-join-existing=all-zone;" "non-owner-observe=all-zone;" "non-owner-get=all-zone;" "non-owner-modify=all-zone;" "non-member-join-existing=all-zone;" "non-member-observe=all-zone;" "non-member-get=all-zone;" "non-member-modify=all-zone;"; "owner-member-join-existing=all-zone;" "owner-member-observe=all-zone;" "owner-member-get=all-zone;" "owner-member-modify=all-zone;"; /* * "Secret" CPGs * * Only privileged applications can see environment * variables, or access CPG doors. Such CPGs should * be finalized to prevent updates of envirnoment * variables and doors, since *-modify=default. * * Useful for storing secret cryptographic keys, * perhaps. */ aprivs = "join-new=default;leave=default;" "observe=default;reg-door=default;" "get=default;" "non-owner-join-existing=default;" "non-owner-observe=default;" "non-owner-get=all-zone;" "non-owner-modify=default;" "non-member-join-existing=default;" "non-member-observe=default;" "non-member-get=all-zone;" "non-member-modify=default;"; "owner-member-join-existing=default;" "owner-member-observe=default;" "owner-member-get=all-zone;" "owner-member-modify=default;"; NOTES Some legacy process group types cannot be easily represented SunOS 5.11 Last change: 2009-08-14 20 Credentials Process Groups CPG_CHANGE(2) as CPGs. For example: process contracts. Not every pre- defined value of idtype_t has a corresponding CPG type. pam_krb5(5)'s credentials module will associate Kerberos V credentials with a login process' CPG of type "network_identity" using standard Solaris Kerberos environment variables (see krb5envvar(5)). See pam_krb5(5). There is a limit on how many CPGs a process can be a member of, and this limits the number of CPG types that may be registered. This limit currently defaults to 16, and can be set at boot time by setting ncpgroups_max via /etc/system. To retain CPG memberships, environment, or doors across su(1M) for CPG types that are in the Login class one must have a PAM credentials module stacked around pam_unix_cred(5) that either rejoins the previous CPG membership, or copy its environment and doors, after pam_unix_cred(5) modifies the login process. [Utility functions (ones that can be defined in terms of system calls, or which allocate memory) need to be moved to a 3CPG section manpage.] ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Uncommitted | |_____________________________|_____________________________| | MT-Level | Async-Signal-Safe | | | except for functions that | | | allocate memory (see above) | |_____________________________|_____________________________| SEE ALSO intro(2), system(4), privileges(5), pam_unix_cred(5), pam_krb5(5), krb5envvar(5), login(1), su(1), pool_set_binding(3POOL), setpriority(3C), setpgid(2), settaskid(2), attributes(5) SunOS 5.11 Last change: 2009-08-14 21 -------------- next part -------------- User Commands CPG(1) NAME cpg - Manipulate Credentials Process Groups SYNOPSIS cpg list [options] [pid] cpg list -t [-c] cpg show [options] cpg-spec ... cpg register [options] cpg-type-name cpg unregister cpg-type-name cpg register -r [options] cpg-type-name cpg monitor [-e eventspec] cpg-type-name ... cpg getenv cpg-spec variable cpg putenv cpg-spec variable[=[value]] cpg chown cpg-spec uid|username cpg change [options] [pid] DESCRIPTION Credentials Process Groups (CPGs) allow one to create arbitrary process group types. Each CPG type has a name and a set of semantics flags associated with it. A process can be in at most one CPG for any given CPG type. See cpg_change(2) for more details. The cpg command takes a sub-command and sub-command-specific options and arguments. The first form lists the CPG memberships of the given PID, or the current process if no PID is given. The second form lists the registered CPG types. If the -c option is given, then the output will be cpg register command lines suitable for evaluation in a shell. The third form shows all information about one or more CPGs named by . The next three forms allow for registering, unregistering, and re-registering CPG types. See below for options. The monitor sub-command allows the user to monitor the events for one or more of the named CPG types. The -e option specifies what event types to monitor. The parameter is a comma-separated list of: create, empty, unref, unregister, unregister-complete, putenv, and custom. See cpg_change(2). The getenv sub-command allows the user to get a single environment variable's value from a given CPG. The putenv sub-sommand allows the user to clear or set an environment variable in a given CPG. SunOS 5.11 Last change: 2009-08-14 1 User Commands CPG(1) The chown sub-command allows the user to set the owner of a given CPG. The change sub-command allows the user to change the CPG memberships of a process. consists of: cpg-type-name:PID This refers to the CPG of the given type that the process named by the given PID is a member of. cpg-type-name/cpg-ID This is the ID of a CPG. OPTIONS -n Don't resolve UIDs to usernames. -e An option for the list and show sub-commands: show the CPG environment(s). -e eventspec A monitor sub-command option (see above). Defaults to all. -e size A register and reregister sub-command option specifying the allowable environment size. Defaults to 0. See cpg_type_reg(2). -s semantics A comma-separated list of semantics flags. See cpg_type_reg(2). The "CPG_S_" prefix and capitalization are not necessary. Defaults to "". -c classes A register sub-command option; classes is comma- separated list of CPG type classes. See cpg_reg(2). Defaults to "". -p priv-spec A privilege specification. See cpg_reg(2) for details and default. -r A register sub-command option. Reregisters the given CPG type. -H A show, list sub-command option causing headers to be excluded. -t A list sub-command option that causes it to list the registered CPG types. SunOS 5.11 Last change: 2009-08-14 2 User Commands CPG(1) -c A list sub-command option for use with the -t option. With this option the list command outputs quoted cpg register command lines suitable for use in shells. -L pid See option -J. -J cpg-join-spec A change sub-command option. Join existing CPGs that the process named with the -L option is a member of. -N cpg-join-spec A change sub-command option. Join new CPGs of the given types. -x cpg-data Sets CPG type-specific data for any new CPG of the given type. cpg-data is: :. Currently only the "task" CPG type has type-specific data defined: :normal|final. EXAMPLES To register a new CPG type named "foo at example", with the CPG_S_DISTINGUISH_CRED semantic flag, and in the Login and Example at example classes: % cpg register -e 1024 -c Login,Example at example \ -s distinguish_cred foo at example To monitor CPG events for the CPG type "foo at example": % cpg monitor -e create,empty,unref foo at example To show a CPG: % cpg show -n foo at example:$$ OWNER LEADER 12345 456 % cpg show -e foo at example:$$ SOMEVAR=someval SOMEVAR2=someval2 % cpg show -He foo at example:$$ joeuser 456 SOMEVAR=someval joeuser 456 SOMEVAR2=someval2 % ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: SunOS 5.11 Last change: 2009-08-14 3 User Commands CPG(1) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Uncommitted | | show sub-command output | Uncommitted | | other output | Not an interface | |_____________________________|_____________________________| SEE ALSO intro(2), cpg_reg(2), attributes(5) SunOS 5.11 Last change: 2009-08-14 4 -------------- next part -------------- Generic Security Services API Library Functions gss_acquire_cred_ucred(3GSS) NAME gss_acquire_cred_with_ucred - Acquire a credential corresponding to a given ucred SYNOPSIS cc [ flag... ] file... -lgss [ library... ] #include OM_uint32 gss_acquire_cred_with_ucred(OM_uint32 *minor_status, const ucred_t desired_ucred, const gss_name_t *desired_name, OM_uint32 time_req, const gss_OID_set desired_mech, gss_cred_usage_t cred_usage, gss_cred_id_t * output_cred_handle, gss_OID_set *actual_mechs, OM_uint32 *time_rec); OM_uint32 gss_add_cred_with_ucred(OM_uint32 *minor_status, const ucred_t desired_ucred, const gss_cred_id_t input_cred_handle, const gss_name_t desired_name, const gss_OID desired_mech, gss_cred_usage_t cred_usage, OM_uint32 initiator_time_req, OM_uint32 acceptor_time_req, gss_cred_id_t *output_cred_handle, gss_OID_set *actual_mechs, OM_uint32 *initiator_time_rec, OM_uint32 *acceptor_time_rec); DESCRIPTION These two functions are just like gss_acquire_cred(3GSS) and gss_add_cred(3GSS), but take an additional argument: a ucred (see ucred_get(3C)). These functions acquire GSS-API credentials that correspond to the process credentials represented by the given ucred object. GSS-API mechanisms could use Credentials Process Group (CPG) information from the ucred to find credentials for the mechanism. For example, the ucred may show a CPG ID and CPG user-data for the "network_identity" CPG type, and the Kerberos V mechanism may be able to locate a Ticket Granting Ticket (TGT) through the CPG ID and/or CPG environment. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | SunOS 5.11 Last change: 2009-08-14 1 Generic Security Services API Library Functions gss_acquire_cred_ucred(3GSS) |_____________________________|_____________________________| | Interface Stability | Uncommitted | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| SEE ALSO intro(2), cpg_change(2), gss_acquire_cred(3GSS), gss_add_cred(3GSS), privileges(5), pam_unix_cred(5), pam_krb5(5), login(1), su(1), attributes(5). SunOS 5.11 Last change: 2009-08-14 2 Generic Security Services API Library Functions gss_acquire_cred_ucred(3GSS) SunOS 5.11 Last change: 2009-08-14 3 -------------- next part -------------- --- stuff/gssd-orig Sun Jun 21 15:47:49 2009 +++ stuff/gssd-new Sun Jun 21 15:47:49 2009 @@ -1,86 +1,92 @@ System Administration Commands gssd(1M) NAME gssd - generates and validates GSS-API tokens for kernel RPC SYNOPSIS /usr/lib/gss/gssd DESCRIPTION gssd is the user mode daemon that operates between the ker- nel rpc and the Generic Security Service Application Program Interface (GSS-API) to generate and validate GSS-API secu- rity tokens. In addition, gssd maps the GSS-API principal names to the local user and group ids. By default, all groups that the requested user belongs to will be included in the grouplist credential. gssd is invoked by the Internet daemon inetd(1m) the first time that the kernel RPC requests GSS-API services. EXIT STATUS The following exit values are returned: 0 Successful completion. >0 An error occurred. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWgssk | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| SEE ALSO kill(1), pkill(1), svcs(1), inetadm(1M), inetd(1M), gsscred(1M), svcadm(1M), gsscred.conf(4), resolv.conf(4), - attributes(5), smf(5) + attributes(5), smf(5), cpg_change(2), pam_unix_cred(5) RFC 2078 NOTES The following signal has the specified effect when sent to the server process using the kill(1) command: SIGHUP gssd rereads the gsscred.conf(4) options. When one of the mechanisms being used is Kerberos, then the gssd process must be restarted after adding or changing the resolv.conf(4) file. + gssd uses the gss_acquire_cred_with_ucred(3GSS) to obtain + credentials suitable for use with gss_init_sec_context(3GSS). + This means that credentials process group (CPG) information + can be used to select an appropriate GSS-API credential. + + The gssd service is managed by the service management facil- ity, smf(5), under the service identifier: svc:/network/rpc/gss:default Administrative actions on this service, such as enabling, disabling, or requesting restart, can be performed using svcadm(1M). Responsibility for initiating and restarting this service is delegated to inetd(1M). Use inetadm(1M) to make configuration changes and to view configuration infor- mation for this service. The service's status can be queried using the svcs(1) command. -------------- next part -------------- --- stuff/krb5envvar-orig Fri Aug 14 15:47:02 2009 +++ stuff/krb5envvar-new Fri Aug 14 15:47:29 2009 @@ -1,194 +1,198 @@ Standards, Environments, and Macros krb5envvar(5) NAME krb5envvar - Kerberos environment variables DESCRIPTION The Kerberos mechanism provides a number of environment variables to configure different behavior in order to meet - applications' needs. Environment variables used within the + applications' needs. Environment variables are searched for + in the current environment first, then in process' + "network_identity" Credentials Process Group (CPG) (see + cpg_getenv(2)). Environment variables used within the Kerberos mechanism are: KRB5_KTNAME Used by the mechanism to specify the location of the key table file. The variable can be set to the following value: [[:]] where can be FILE or WRFILE. FILE is for read operations; WRFILE is for write operations. is the location of the keytab file. r If KRB5_KTNAME is not defined, the default value is: FILE:/etc/krb5/krb5.keytab The keytab file is used to store credentials per- sistently and is used commonly for service daemons. Specifying the FILE type assumes that the subsequent operations on the associated file are readable by the invoking process. Care must be taken to ensure that the file is readable only by the set of principals that need to retrieve their unencrypted keys. The WRFILE type is used by the kadmin(1M) command. Specifying this type allows the administrator to desig- nate an alternate keytab file to write to without using extra command line arguments for file location. KRB5CCNAME Used by the mechanism to specify the location of the credential cache. The variable can be set to the follow- ing value: [[:]] where can be FILE or MEMORY. is the location of the principal's credential cache. If KRB5CCNAME is not defined, the default value is: FILE:/tmp/krb5cc_ where is the user id of the process that created the cache file. The credential cache file is used to store tickets that have been granted to the principal. Specifying the FILE types assumes that subsequent opera- tions on the associated file are readable and writable by the invoking process. Care must be taken to ensure that the file is accessible only by the set of princi- pals that need to access their credentials. If the credential file is in a directory to which other users have write access, you need to set that directory's sticky bit (see chmod(1)). The MEMORY credential cache type is used only in special cases, such as when making a temporary cache for the life of the invoking process. KRB5RCNAME Used by the mechanism to specify the type and location of the replay cache. The variable can be set to the fol- lowing value: [[:]] where can be either FILE, MEMORY, or NONE. is relevant only when specifying the replay cache file type. If not defined, the default value is: FILE:/var/krb5/rcache/root/rc_ ...if the process is owned by root, or: FILE:/var/krb5/rcache/rc_ ...if the process is owned by a user other than root. is the service process name associated with the replay cache file. The replay cache is used by Kerberos to detect the replay of authentication data. This prevents people who capture authentication messages on the network from authenticating to the server by resending these messages. When specifying the FILE replay cache type, care must be taken to prevent the replay cache file from being deleted by another user. Make sure that every directory in the replay cache path is either writable only by the owner of the replay cache or that the sticky bit ("t") is set on every directory in the replay cache path to which others have write permission. When specifying the MEMORY replay cache type you need to weigh the trade-off of performance against the slight security risk created by using a non-persistent cache. The risk occurs during system reboots when the following condition obtains: o The duration from the last write to the replay cache before reboot to the point when the Ker- berized server applications are running is less than the Kerberos clockskew (see krb5.conf(4)). When specifying the NONE replay cache time you need to understand that this disables the replay cache, and all security risks that this presents. This includes all the risks outlined in this section of the man page. Under this condition, the server applications can accept a replay of Kerberos authentication data (up to the difference between the time of the last write and the clockskew). Typically, this is a small window of time. If the server applications take longer than the clock- skew to start accepting connections there is no replay risk. The risk described above is the same when using FILE replay cache types when the replay cache resides on swap file systems, such as /tmp and /var/run. The performance improvement in MEMORY replay cache types over FILE types is derived from the absence of disk I/O. This is true even if the FILE replay cache is on a memory-backed file system, such as swap (/tmp and /var/run). Note that MEMORY-type caches are per-process caches, therefore use of these types of caches must be carefully considered. One example of where MEMORY-type caches can be problematic is when an application uses more than one process for establishing security contexts. In such a case, memory replay caches are not shared across the processes, thus allowing potential for replay attacks. KRB5_CONFIG Allows you to change the default location of the /etc/krb5/krb5.conf file to enable the Kerberos library code to read configuration parameters from another file specified by KRB5_CONFIG. For example (using kinit from ksh(1)): KRB5_CONFIG=/var/tmp/krb5.conf kinit ATTRIBUTES See attributes(5) for a description of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWkrbu | |_____________________________|_____________________________| | Interface Stability | Uncommitted | |_____________________________|_____________________________| SEE ALSO chmod(1), kinit(1), klist(1), ksh(1), kadmin(1M), - kadmind(1M), krb5.conf(4), attributes(5), kerberos(5) + kadmind(1M), krb5.conf(4), attributes(5), kerberos(5), + cpg_putenv(2) -------------- next part -------------- --- stuff/pam_krb5-orig Sun Jun 21 15:47:51 2009 +++ stuff/pam_krb5-new Fri Aug 14 15:39:50 2009 @@ -1,473 +1,477 @@ Standards, Environments, and Macros pam_krb5(5) NAME pam_krb5 - authentication, account, session, and password management PAM modules for Kerberos V5 SYNOPSIS /usr/lib/security/pam_krb5.so.1 DESCRIPTION The Kerberos V5 service module for PAM provides functional- ity for all four PAM modules: authentication, account management, session management, and password management. The service module is a shared object that can be dynamically loaded to provide the necessary functionality upon demand. Its path is specified in the PAM configuration file. Kerberos Authentication Module The Kerberos V5 authentication component provides functions to verify the identity of a user, pam_sm_authenticate(), and to manage the Kerberos credentials cache, pam_sm_setcred(). pam_sm_authenticate() authenticates a user principal through the Kerberos authentication service. If the authentication request is successful, the authentication service sends a ticket-granting ticket (TGT) back to the service module, which then verifies that the TGT came from a valid Key Dis- tribution Center (KDC) by attempting to get a service ticket for the local host service. For this to succeed, the local host's keytab file (/etc/krb5/krb5.keytab) must contain the entry for the local host service. For example, in the file host/hostname.com at REALM, hostname.com is the fully qualified local hostname and REALM is the default realm of the local host as defined in /etc/krb5/krb5.conf. If the host entry is not found in the keytab file, the authentication fails. Administrators may optionally disable this "strict" verifi- cation by setting "verify_ap_req_nofail = false" in /etc/krb5/krb5.conf. See krb5.conf(4) for more details on this option. This allows TGT verification to succeed in the absence of a keytab host principal entry. pam_sm_authenticate(3PAM) may be passed the following flag: PAM_DISALLOW_NULL_AUTHTOK This flag is ignored. The Kerberos authentication mechanism will not allow an empty password string by default. pam_sm_setcred() creates and modifies the user's credential cache. This function initializes the user's credential cache, if it does not already exist, and stores the initial credentials for later use by Kerberized network applica- tions. The following flags may be set in the flags field. They are best described by their effect on the user's credential cache. PAM_ESTABLISH_CRED Stores the initial credentials in the user's credential - cache so that the user may access Kerberos network ser- - vices. If a successful authentication pass was made, the - new credentials are stored in the credential cache, - overwriting any existing credentials that were previ- - ously stored. If an unsuccessful authentication pass - was made, PAM_CRED_UNAVAIL is returned. + cache, and sets PAM environment variables (see + krb5envvar(5)) and the same environment variables in the + caller's "network_identity" Credentials Process Group + (CPG), so that the user may access Kerberos network + services. If a successful authentication pass was made, + the new credentials are stored in the credential cache, + overwriting any existing credentials that were previous- + ly stored. If an unsuccessful authentication pass was + made, PAM_CRED_UNAVAIL is returned. PAM_DELETE_CRED This flag has no effect on the credential cache and always returns PAM_SUCCESS. The credential cache is not deleted because there is no accurate method to determine if the credentials are needed by another process. The credential cache may be deleted with the kdestroy(1) command. PAM_REINITIALIZE_CRED Deletes the user's existing credential cache, if it exists, and creates a new credential cache. The new credentials are stored in the new cache and the user's ticket lifetime and renewable life time values are reset. PAM_REFRESH_CRED Does not require a previous authentication pass, but if a successful one is made, the new credentials are stored in the credential cache. If a previous authentication pass was not made or was unsuccessful, an attempt to renew the existing credentials is made. Note that this function fails if the user's renewable ticket lifetime is expired. The following options can be passed to the Kerberos V5 authentication module: debug Provides syslog(3C) debugging information at LOG_DEBUG level. nowarn Turns off warning messages. Kerberos V5 Account Management Module The Kerberos account management component provides a func- tion to perform account management, pam_sm_acct_mgmt(). This function checks to see if the pam_krb5 authentication module has noted that the user's password has not expired. The fol- lowing options may be passed in to the Kerberos V5 account management module: debug Provides syslog(3C) debugging information at LOG_DEBUG level nowarn Turns off warning messages. Also, does not query KDC for impending password expiration information used to warn the user. Kerberos V5 Session Management Module The Kerberos V5 session management component provides func- tions to initiate pam_sm_open_session() and terminate pam_sm_close_session() Kerberos sessions. For Kerberos V5, both pam_sm_open_session and pam_sm_close_session() are null functions, returning PAM_IGNORE. Kerberos V5 Password Management Module The Kerberos V5 password management component provides a function to change passwords, pam_sm_chauthtok(), in the Key Distribution Center (KDC) database. The following flags may be passed to pam_sm_chauthtok(3PAM): PAM_CHANGE_EXPIRED_AUTHTOK The password service should only update the user's Ker- beros password if it is expired. Otherwise, this func- tion returns PAM_IGNORE. The default behaviour is to always change the user's Kerberos password. PAM_PRELIM_CHECK This is a null function that always returns PAM_IGNORE. PAM_UPDATE_AUTHTOK This flag is necessary to change the user's Kerberos password. If this flag is not set, pam_krb5 returns PAM_SYSTEM_ERR. The following option can be passed to the Kerberos V5 pass- word module: debug Provides syslog(3C) debugging information at LOG_DEBUG level. ERRORS The following error codes are returned for pam_sm_authenticate(): PAM_AUTH_ERR Authentication failure PAM_BUF_ERR Memory buffer error. PAM_IGNORE The user is "root" and the root key exists in the default keytab. PAM_SUCCESS Successfully obtained Kerberos creden- tials . PAM_SYSTEM_ERR System error. PAM_USER_UNKNOWN An unknown Kerberos principal was requested. The following error codes are returned for pam_sm_setcred(): PAM_AUTH_ERR Authentication failure. PAM_BUF_ERR Memory buffer error. PAM_IGNORE The user is "root" and the root key exists in the default keytab. PAM_SYSTEM_ERR System error. PAM_SUCCESS Successfully modified the Kerberos creden- tial cache. The following error codes are returned for pam_sm_acct_mgmt(): PAM_AUTH_ERR Authentication failure. PAM_IGNORE Kerberos service module pam_sm_authenticate() was never called, or the user is "root" and the root key exists in the default keytab. PAM_NEW_AUTHTOK_REQD Obtain new authentication token from the user. PAM_SERVICE_ERR Error in underlying service module. PAM_SUCCESS Kerberos principal account is valid. PAM_SYSTEM_ERR System error. PAM_USER_UNKNOWN An unknown Kerberos principal was requested. The following error code is returned for pam_sm_open_session() and pam_sm_close_session(): PAM_IGNORE These two functions are null functions in pam_krb5: The following error codes are returned for pam_sm_chauthtok(): PAM_AUTH_ERR Authentication failure. PAM_IGNORE The user has not been authenticated by Kerberos service module pam_sm_authenticate(), or the user is "root" and the root key exists in the default keytab. PAM_NEW_AUTHTOK_REQD User's Kerberos password has expired. PAM_SERVICE_ERR Error in module. At least one input parameter is missing. PAM_SYSTEM_ERR System error. PAM_USER_UNKNOWN An unknown Kerberos principal was requested. PAM_SUCCESS Successfully changed the user's Ker- beros password. EXAMPLES Example 1 Authenticate Users Through Kerberos as First Choice The following is an excerpt of a sample pam.conf configura- tion file that authenticates users through the Kerberos authentication service and authenticates through the Unix login only if the Kerberos authentication fails. This arrangement is helpful when a majority of the users are networked by means of Kerberos and when there are only a few non-Kerberos type user accounts, such as root. The service illustrated below is for dtlogin. dtlogin auth requisite pam_smartcard.so.1 dtlogin auth requisite pam_authtok_get.so.1 dtlogin auth required pam_dhkeys.so.1 dtlogin auth required pam_unix_cred.so.1 dtlogin auth sufficient pam_krb5.so.1 dtlogin auth required pam_unix_auth.so.1 Note that these changes should not be made to the existing krlogin, krsh, and ktelnet service entries. Those services require Kerberos authentication, so using a seemingly suffi- cient control flag would not provide the necessary func- tionality for privacy and integrity. There should be no need to change those entries. The following entries check for password expiration when dealing with Kerberos and Unix password aging policies: other account requisite pam_roles.so.1 other account required pam_unix_account.so.1 other account required pam_krb5.so.1 The following entries would change the Kerberos password of the user and continue to change the Unix login password only if the Kerberos password change had failed: other password required pam_dhkeys.so.1 other password requisite pam_authtok_get.so.1 other password requisite pam_authtok_check.so.1 other password sufficient pam_krb5.so.1 other password required pam_authtok_store.so.1 When changing Kerberos based user's password, use kpasswd(1). When changing a non-Kerberos user's password, it is recommended that the repository is specified (-r) with the passwd(1) command. Example 2 Authenticate Users Through Kerberos Only The following example allows authentication only to users that have Kerberos-based accounts. dtlogin auth requisite pam_smartcard.so.1 dtlogin auth requisite pam_authtok_get.so.1 dtlogin auth required pam_dhkeys.so.1 dtlogin auth required pam_unix_cred.so.1 dtlogin auth binding pam_krb5.so.1 dtlogin auth required pam_unix_auth.so.1 Typically, you would have another service specified in the pam.conf file that would allow local users, such as data- base, web server, system administrator accounts, to log in to the host machine. For example, the service name "login" could be used for these users. Note that these users should not belong to any roles. The rest of the module types look similar to that shown in the previous example: other account requisite pam_roles.so.1 other account required pam_unix_account.so.1 other account required pam_krb5.so.1 With binding specified in the following, it is important that non-Kerberos users specify the repository in which they reside using the -r option with the passwd(1) command. This configuration is also based on the assumptions that: o Kerberos users maintain only their Kerberos pass- words; o changing their Unix password is not necessary, given that they are authenticated only through their Kerberos passwords when logging in. other password required pam_dhkeys.so.1 other password requisite pam_authtok_get.so.1 other password requisite pam_authtok_check.so.1 other password binding pam_krb5.so.1 other password required pam_authtok_store.so.1 Example 3 Authenticate Through Kerberos Optionally This configuration is helpful when the majority of users are non-Kerberos users and would like to authenticate through Kerberos if they happened to exist in the Kerberos database. The effect of this is similar to users voluntarily executing kinit(1) after they have successfully logged in: dtlogin auth requisite pam_smartcard.so.1 dtlogin auth requisite pam_authtok_get.so.1 dtlogin auth required pam_dhkeys.so.1 dtlogin auth required pam_unix_cred.so.1 dtlogin auth required pam_unix_auth.so.1 dtlogin auth optional pam_krb5.so.1 The rest of the configuration is as follows: other account requisite pam_roles.so.1 other account required pam_unix_account.so.1 other account required pam_krb5.so.1 other password required pam_dhkeys.so.1 other password requisite pam_authtok_get.so.1 other password requisite pam_authtok_check.so.1 other password required pam_authtok_store.so.1 other password optional pam_krb5.so.1 Non-Kerberos users should specify their respective reposi- tories by using the -r option when changing their password with the passwd(1) command. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| SEE ALSO kdestroy(1), kinit(1), kpasswd(1), passwd(1), ktkt_warnd(1M), libpam(3LIB), pam(3PAM), pam_sm(3PAM), pam_sm_acct_mgmt(3PAM), pam_sm_authenticate(3PAM), pam_sm_chauthtok(3PAM), pam_sm_close_session(3PAM), pam_sm_open_session(3PAM), pam_sm_setcred(3PAM), syslog(3C), - pam.conf(4), attributes(5), kerberos(5), krb5envvar(5) + pam.conf(4), attributes(5), kerberos(5), krb5envvar(5), + cpg_putenv(2) NOTES The interfaces in libpam(3LIB) are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle. On successful acquisition of initial credentials (ticket- granting ticket), ktkt_warnd(1M) will be notified, to alert the user when the initial credentials are about to expire. -------------- next part -------------- --- stuff/pam_unix_cred-orig Sun Jun 21 15:47:52 2009 +++ stuff/pam_unix_cred-new Fri Aug 14 15:49:18 2009 @@ -1,149 +1,153 @@ Standards, Environments, and Macros pam_unix_cred(5) NAME pam_unix_cred - PAM user credential authentication module for UNIX SYNOPSIS pam_unix_cred.so.1 DESCRIPTION The pam_unix_cred module implements pam_sm_setcred(3PAM). It provides functions that establish user credential informa- tion. It is a module separate from the pam_unix_auth(5) module to allow replacement of the authentication func- tionality independently from the credential functionality. The pam_unix_cred module must always be stacked along with whatever authentication module is used to ensure correct credential setting. Authentication service modules must implement both pam_sm_authenticate() and pam_sm_setcred(). pam_sm_authenticate() in this module always returns PAM_IGNORE. pam_sm_setcred() initializes the user's project, privilege sets and initializes or updates the user's audit context if it hasn't already been initialized. The following flags may be set in the flags field: PAM_ESTABLISH_CRED PAM_REFRESH_CRED PAM_REINITIALIZE_CRED Initializes the user's project to the project specified in PAM_RESOURCE, or if PAM_RESOURCE is not specified, to the user's default project. Establishes the user's privilege sets. + Initializes the user's credentials process groups (CPG) + of all CPG types which in the Login class, and sets + their owner to be the PAM_USER's UID. + If the audit context is not already initialized and auditing is configured, these flags cause the context to be initialized to that of the user specified in PAM_AUSER (if any) merged with the user specified in PAM_USER and host specified in PAM_RHOST. If PAM_RHOST is not specified, PAM_TTY specifies the local terminal name. Attributing audit to PAM_AUSER and merging PAM_USER is required for correctly attributing auditing when the system entry is performed by another user that can be identified as trustworthy. If the audit context is already initialized, the PAM_REINITIALIZE_CRED flag merges the current audit con- text with that of the user specified in PAM_USER. PAM_REINITIALIZE_CRED is useful when a user is assuming a new identity, as with su(1M). PAM_DELETE_CRED This flag has no effect and always returns PAM_SUCCESS. The following options are interpreted: debug Provides syslog(3C) debugging information at the LOG_DEBUG level. nowarn Disables any warning messages. ERRORS Upon successful completion of pam_sm_setcred(), PAM_SUCCESS is returned. The following error codes are returned upon error: PAM_CRED_UNAVAIL Underlying authentication service cannot retrieve user credentials PAM_CRED_EXPIRED User credentials have expired PAM_USER_UNKNOWN User is unknown to the authentication service PAM_CRED_ERR Failure in setting user credentials PAM_BUF_ERR Memory buffer error PAM_SYSTEM_ERR System error The following values are returned from pam_sm_authenticate(): PAM_IGNORE Ignores this module regardless of the control flag ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| | MT Level | MT-Safe with exceptions | |_____________________________|_____________________________| SEE ALSO ssh(1), su(1M), settaskid(2), libpam(3LIB), getprojent(3PROJECT), pam(3PAM), pam_set_item(3PAM), pam_sm_authenticate(3PAM), syslog(3C), setproject(3PROJECT),pam.conf(4), nsswitch.conf(4), pro- ject(4), attributes(5), pam_authtok_check(5), pam_authtok_get(5), pam_authtok_store(5), pam_dhkeys(5), pam_passwd_auth(5), pam_unix_auth(5), pam_unix_account(5), - pam_unix_session(5), privileges(5) + pam_unix_session(5), privileges(5), cpg_change(2) NOTES The interfaces in libpam(3LIB) are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle. If this module is replaced, the audit context and credential may not be correctly configured. -------------- next part -------------- --- stuff/pcred-orig Sun Jun 21 15:47:53 2009 +++ stuff/pcred-new Fri Aug 14 12:59:23 2009 @@ -1,303 +1,342 @@ User Commands proc(1) NAME proc, pflags, pcred, pldd, psig, pstack, pfiles, pwdx, pstop, prun, pwait, ptime - proc tools SYNOPSIS /usr/bin/pflags [-r] pid | core [/lwp] ... /usr/bin/pcred [pid | core]... - /usr/bin/pcred [-u user/uid] [-g group/gid] [-G grouplist] pid... + /usr/bin/pcred [-u user/uid] [-g group/gid] [-G grouplist] + [-J cpg-spec] [-N cpg-spec] [-L pid] + [-F cpg-flags] pid... /usr/bin/pcred -l login pid... /usr/bin/pldd [-Fl] [pid | core]... /usr/bin/psig [-n] pid... /usr/bin/pstack [-F] pid | core [/lwp] ... /usr/bin/pfiles [-Fn] pid... /usr/bin/pwdx pid... /usr/bin/pstop pid[/lwp] ... /usr/bin/prun pid[/lwp] ... /usr/bin/pwait [-v] pid... /usr/bin/ptime command [arg]... DESCRIPTION The proc tools are utilities that exercise features of /proc (see proc(4)). Most of them take a list of process-ids (pid). The tools that do take process-ids also accept /proc/nnn as a process-id, so the shell expansion /proc/* can be used to specify all processes in the system. Some of the proc tools can also be applied to core files (see core(4)). The tools that apply to core files accept a list of either process IDs or names of core files or both. Some of the proc tools can operate on individual threads. Users can examine only selected threads by appending /thread-id to the process-id or core. Multiple threads can be selected using the - and , delimiters. For example /1,2,7-9 examines threads 1, 2, 7, 8, and 9. See WARNINGS. pflags Print the /proc tracing flags, the pending and held signals, and other /proc status information for each process or specified lwps in each pro- cess. pcred Print or set the credentials (effective, real, saved UIDs and GIDs) of each process. pldd List the dynamic libraries linked into each pro- cess, including shared objects explicitly attached using dlopen(3C). See also ldd(1). psig List the signal actions and handlers of each pro- cess. See signal.h(3HEAD). pstack Print a hex+symbolic stack trace for each process or specified lwps in each process. pfiles Report fstat(2) and fcntl(2) information for all open files in each process. For network endpoints, the local (and peer if connected) address informa- tion is also provided. For sockets, the socket type, socket options and send and receive buffer sizes are also provided. In addition, a path to the file is reported if the information is avail- able from /proc/pid/path. This is not necessarily the same name used to open the file. See proc(4) for more information. pwdx Print the current working directory of each pro- cess. pstop Stop each process or the specified lwps (PR_REQUESTED stop). prun Set running each process or the specified lwps (the inverse of pstop). pwait Wait for all of the specified processes to ter- minate. ptime Time the command, like time(1), but using micro- state accounting for reproducible precision. Unlike time(1), children of the command are not timed. OPTIONS The following general options are supported: -F Force. Grabs the target process even if another pro- cess has control. -n (psig and pfiles only) Sets non-verbose mode. psig displays signal handler addresses rather than names. pfiles does not display verbose information for each file descriptor. Instead, pfiles limits its output to the information that would be retrieved if the process applied fstat(2) to each of its file descriptors. -r (pflags only) If the process is stopped, displays its machine registers. -v (pwait only) Verbose. Reports terminations to standard output. In addition to the general options, pcred supports the fol- lowing options: -g group/gid Sets the real, effective, and saved group ids (GIDs) of the target processes to the specified value. -G grouplist Sets the supplementary GIDs of the target process to the specified list of groups. The supplementary groups should be specified as a comma-separated list of group names ids. An empty list clears the supplementary group list of the target processes. -l login Sets the real, effective, and saved UIDs of the target processes to the UID of the specified login. Sets the real, effective, and saved GIDs of the target processes to the GID of the specified login. Sets the supplementary group list to the supplemen- tary groups list of the specified login. -u user/uid Sets the real, effective, and saved user ids (UIDs) of the target processes to the speci- fied value. + -N cpg-spec Joins the process to new Credentials Process + Groups (CPGs) of the given types/classes. + -J cpg-spec Joins the process to existing CPGs + specified by cpg-spec that the process named + by the -L option is a member of. + + cpg-spec is a comma-separated list of CPG + type names, class names, or + type-name: values, where is + the ID of a CPG. + + -L pid See -L above. + + -F cpg-flags cpg-flags is a comma-separated list of CPG + change flags to use: + + o all-permitted + o copy-env + o final + + See cpg_change(2) for a complete description. + + -X cpg-data CPG type-specific data. cpg-data is + :. + + Currently only the "task" type has extra + data defined: + + :normal + or + :final + + where is a Solaris project ID. + See cpg_change(2) for a complete + description. + + In addition to the general options, pldd supports the fol- lowing option: -l Shows unresolved dynamic linker map names. In order to set the credentials of another process, a pro- cess must have sufficient privilege to change its user and group ids to those specified according to the rules laid out in setuid(2) and it must have sufficient privilege to con- trol the target process. USAGE These proc tools stop their target processes while inspect- ing them and reporting the results: pfiles, pldd, and pstack. A process can do nothing while it is stopped. Thus, for example, if the X server is inspected by one of these proc tools running in a window under the X server's control, the whole window system can become deadlocked because the proc tool would be attempting to print its results to a win- dow that cannot be refreshed. Logging in from from another system using rlogin(1) and killing the offending proc tool would clear up the deadlock in this case. See WARNINGS. Caution should be exercised when using the -F flag. Imposing two controlling processes on one victim process can lead to chaos. Safety is assured only if the primary controlling process, typically a debugger, has stopped the victim pro- cess and the primary controlling process is doing nothing at the moment of application of the proc tool in question. Some of the proc tools can also be applied to core files, as shown by the synopsis above. A core file is a snapshot of a process's state and is produced by the kernel prior to ter- minating a process with a signal or by the gcore(1) utility. Some of the proc tools can need to derive the name of the executable corresponding to the process which dumped core or the names of shared libraries associated with the process. These files are needed, for example, to provide symbol table information for pstack(1). If the proc tool in question is unable to locate the needed executable or shared library, some symbol information is unavailable for display. Simi- larly, if a core file from one operating system release is examined on a different operating system release, the run- time link-editor debugging interface (librtld_db) cannot be able to initialize. In this case, symbol information for shared libraries is not available. EXIT STATUS The following exit values are returned: 0 Successful operation. non-zero An error has occurred. FILES /proc/* process files ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWesu | |_____________________________|_____________________________| | Interface Stability | See below. | |_____________________________|_____________________________| The human readable output is Uncommitted. The options are Committed. SEE ALSO gcore(1), ldd(1), pargs(1), pgrep(1), pkill(1), plimit(1), pmap(1), preap(1), ps(1), ptree(1), ppgsz(1), pwd(1), rlo- gin(1), time(1), truss(1), wait(1), fcntl(2), fstat(2), setuid(2), dlopen(3C), signal.h(3HEAD), core(4), proc(4), process(4), attributes(5), zones(5) WARNINGS The following proc tools stop their target processes while inspecting them and reporting the results: pfiles, pldd, and pstack. However, even if pstack operates on an individual thread, it stops the whole process. A process or thread can do nothing while it is stopped. Stopping a heavily used process or thread in a production environment, even for a short amount of time, can cause severe bottlenecks and even hangs of these processes or threads, causing them to be unavailable to users. Some data- bases could also terminate abnormally. Thus, for example, a database server under heavy load could hang when one of the database processes or threads is traced using the above men- tioned proc tools. Because of this, stopping a UNIX process or thread in a production environment should be avoided. A process or thread being stopped by these tools can be identified by issuing /usr/bin/ps -eflL and looking for "T" in the first column. Notice that certain processes, for example "sched", can show the "T" status by default most of the time. The process ID returned for locked files on network file systems might not be meaningful. -------------- next part -------------- --- stuff/ucred_get-orig Sun Jun 21 15:47:54 2009 +++ stuff/ucred_get-new Fri Aug 14 15:52:36 2009 @@ -1,212 +1,217 @@ Standard C Library Functions ucred_get(3C) NAME ucred_get, ucred_free, ucred_geteuid, ucred_getruid, ucred_getsuid, ucred_getegid, ucred_getrgid, ucred_getsgid, ucred_getgroups, ucred_getprivset, ucred_getpid, ucred_getprojid, ucred_getzoneid, ucred_getpflags, ucred_getlabel, ucred_size - user credential functions SYNOPSIS #include ucred_t *ucred_get(pid_t pid); void ucred_free(ucred_t *uc); uid_t ucred_geteuid(const ucred_t *uc); uid_t ucred_getruid(const ucred_t *uc); uid_t ucred_getsuid(const ucred_t *uc); gid_t ucred_getegid(const ucred_t *uc); gid_t ucred_getrgid(const ucred_t *uc); gid_t ucred_getsgid(const ucred_t *uc); int ucred_getgroups(const ucred_t *uc, const gid_t **groups); const priv_set_t *ucred_getprivset(const ucred_t *uc, priv_ptype_t set); pid_t ucred_getpid(const ucred_t *uc); projid_t ucred_getprojid(const ucred_t *uc); zoneid_t ucred_getzoneid(const ucred_t *uc); uint_t ucred_getpflags(const ucred_t *uc, uint_t flags); m_label_t *ucred_getlabel(const ucred_t *uc); + id_t ucred_getcpgid(const ucred_t *uc, const char *cpg_name); size_t ucred_size(void); DESCRIPTION These functions return or act on a user credential, ucred_t. User credentials are returned by various functions and describe the credentials of a process. Information about the process can then be obtained by calling the access func- tions. Access functions can fail if the underlying mechanism did not return sufficient information. The ucred_get() function returns the user credential of the specified pid or NULL if none can be obtained. A pid value of P_MYID returns information about the calling process. The return value is dynamically allocated and must be freed using ucred_free(). The ucred_geteuid(), ucred_getruid(), ucred_getsuid(), ucred_getegid(), ucred_getrgid(), and ucred_getsgid() func- tions return the effective UID, real UID, saved UID, effec- tive GID, real GID, saved GID, respectively, or -1 if the user credential does not contain sufficient information. The ucred_getgroups() function stores a pointer to the group list in the gid_t * pointed to by the second argument and returns the number of groups in the list. It returns -1 if the information is not available. The returned group list is valid until ucred_free() is called on the user credential given as argument. The ucred_getpid() function returns the process ID of the process or -1 if the process ID is not available. The pro- cess ID returned in a user credential is only guaranteed to be correct in a very limited number of cases when returned by door_ucred(3C) and ucred_get(). In all other cases, the process in question might have handed of the file descrip- tor, the process might have exited or executed another pro- gram, or the process ID might have been reused by a com- pletely unrelated process after the original program exited. The ucred_getprojid() function returns the project ID of the process or -1 if the project ID is not available. The ucred_getzoneid() function returns the zone ID of the process or -1 if the zone ID is not available. The ucred_getprivset() function returns the specified privilege set specified as second argument, or NULL if either the requested information is not available or the privilege set name is invalid. The returned privilege set is valid until ucred_free() is called on the specified user credential. The ucred_getpflags() function returns the value of the specified privilege flags from the ucred structure, or (uint_t)-1 if none was present. The ucred_getlabel() function returns the value of the label, or NULL if the label is not available. The returned label is valid until ucred_free() is called on the specified user credential. This function is available only if the sys- tem is configured with Trusted Extensions. + The ucred_getcpgid() function returns the CPG ID (or + (id_t)-1) of the given CPG type name. + + The ucred_free() function frees the memory allocated for the specified user credential. The ucred_size() function returns sizeof(ucred_t). This value is constant only until the next boot, at which time it could change. The ucred_size() function can be used to determine the size of the buffer needed to receive a creden- tial option with SO_RECVUCRED. See socket.h(3HEAD). RETURN VALUES See DESCRIPTION. ERRORS The ucred_get() function will fail if: EAGAIN There is not enough memory available to allocate sufficient memory to hold a user credential. The application can try again later. EACCES The caller does not have sufficient privileges to examine the target process. EMFILE The calling process cannot open any more files. ENFILE ENOMEM The physical limits of the system are exceeded by the memory allocation needed to hold a user credential. ESRCH The target process does not exist. The ucred_getprivset() function will fail if: EINVAL The privilege set argument is invalid. The ucred_getlabel() function will fail if: EINVAL The label is not present. The ucred_geteuid(), ucred_getruid(), ucred_getsuid(), ucred_getegid(), ucred_getrgid(), ucred_getsgid(), ucred_getgroups(), ucred_getpflags(), ucred_getprivset(), ucred_getprojid(), ucred_getpid(), and ucred_getlabel() functions will fail if: EINVAL The requested user credential attribute is not available in the specified user credential. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | MT-Safe | |_____________________________|_____________________________| SEE ALSO getpflags(2), getppriv(2), door_ucred(3C), getpeerucred(3C), priv_set(3C), socket.h(3HEAD), attributes(5), labels(5), - privileges(5) + privileges(5), cpg_change(2)