setpriv(S)                     6 January 1993                     setpriv(S)


 Name

    setpriv - set system privileges for this process

 Syntax


    cc  . . .  -lprot


    #include  <sys/types.h>
    #include  <sys/security.h>
    #include  <sys/audit.h>

    int setpriv (privtype, privs)
    int privtype;
    priv_t *privs;


 Description

    The setpriv routine sets the system privilege vector for the current pro-
    cess to that in the user-supplied privs vector.  This vector should have
    at least SECSPRIVVECSIZE (a system constant) entries.  The privtype
    argument may only contain the privilege type SECEFFECTIVEPRIV (another
    system constant).

    At system initialization, all privileges are included. System privileges
    are inherited by all children of any process and must call the setpriv
    routines themselves to further restrict system privileges.

    The system privilege vector contains per-process rivileges used by the
    TCB.  The following system privileges are defined:

    [LABELTERMINAL]
                 With this privilege, the process can output the string to
                 set or change the terminal label, or otherwise modify the
                 field where the terminal label resides.  Without this
                 privilege, the sequence to set the terminal label is inter-
                 cepted by the system and altered to a harmless (to the label
                 field) sequence.

    [PROMAIN]    Allow a SUID program to access any pathname, subject to the
                 normal discretionary access checking.  Without this
                 privilege, a SUID program, after invoking setuid(S) to
                 change identity from the program owner to the real user, may
                 only access a pathname (restricted to the real user) in or
                 under the current directory.  Path names above the current
                 directory are only accessible if the program owner may
                 access them.  Changing the current directory has no effect
                 on this, for the current directory at the time of the SUID
                 program execution (called the promain root) is remembered.
                 Previously open files continue to be accessible, no matter
                 how they were opened.  Until this privilege was devised, a
                 user had no protection against errant or malicious SUID pro-
                 grams.  The privilege provides a means for the process to
                 restrict the environment used by the SUID program, so that
                 the program owner cannot usurp files owned by the real UID.
                 With this privilege off, the user may run a SUID program
                 with the current directory the root of a subtree that con-
                 tains no important data therein.  Any attempt to access a
                 pathname above the current directory returns an error of
                 [ENOENT].  This mechanism prevents many kinds of Trojan
                 horses fromSUID programs, where the SUID program uses the
                 setuid(S) call to assign the effective UID to the real UID
                 so that files inaccessible to the prior effective UID become
                 accessible, all done without the knowledge or consent of the
                 session user.

    [SELFAUDIT]  The process does its own auditing.  The system does not pro-
                 duce audit records for this process.

    [SETID]      Allow a program to set the SUID or SGID bits on a file.
                 Turning this privilege off prevents a new user from acciden-
                 tally propagating his identity.  Turning this privilege off
                 and running an untrusted program prevents that program from
                 secretly creating a file owned by you (like a copy of
                 /bin/sh) and setting the SUID bit so that it can run as you
                 unrestricted.  There are other similar uses.

    [SETOWNER]   Allow a program to give a file away (either the user or
                 group).  This privilege is needed for a user to execute the
                 System V chown(S) call.  Without this privilege, a user
                 operates with the chown semantics of BSD, where a normal
                 user cannot give a file away.

    [SUID]       The process may execute SUID programs.  Without this
                 privilege, the process cannot execute any SUID program not
                 set to the same process owner.


 Return value

    Upon successful completion, the setpriv routine returns a value of zero.
    If the routine fails, a value of -1 is returned and errno is set to indi-
    cate the appropriate error.

 Diagnostics

    If one of the following conditions occurs, the setpriv routine fails and
    errno is set to the corresponding value:


    [EFAULT]     privs points to an invalid address.

    [EPERM]      privs has more privileges set than what the process has
                 currently.

    [EINVAL]     privtype is not set to SECEFFECTIVEPRIV.


 See also

    .() chdir(S), chroot(S), getpriv(S), audit(S)

 Standards conformance

    The setpriv routine is an extension of AT&T System V provided by the
    Santa Cruz Operation.