priv_add(3)

NAME

priv_add: priv_add_effective(), priv_remove(), priv_set_effective(), privset_add_effective(), privset_get(), privset_remove(), privset_set_effective() — add, set, remove, and retrieve a process' privileges

SYNOPSIS

#include <sys/types.h> 
#include <sys/privileges.h> 

int priv_add_effective(const char *priv_list,
const char *delim);

int priv_remove(int priv_type,
const char *priv_list,
const char *delim);

int priv_set_effective(const char *priv_list,
const char *delim);

int privset_add_effective(const priv_set_t *priv_set);

int privset_remove(int priv_type,
const priv_set_t *priv_set);

priv_set_t *privset_get(int priv_type,
int pid);,

int privset_set_effective(const priv_set_t *priv_set);

Parameters

delim

Null-terminated string specifying the delimiter string that separates privilege names.

pid

Process ID of the target process whose privileges are to be retrieved.

priv_list

Sequence of privilege names in ASCII, separated by one more characters from delim parameter.

priv_set

Set of privileges in internal format.

priv_type

Privilege set to be operated upon.

The following are the valid values for priv_type argument:

PRIV_EFFECTIVE: Modifies or retrieves privileges from the effective privilege set of the process.
PRIV_PERMITTED: Modifies or retrieves privileges from the permitted privilege set of the process. Note that the privileges removed from the permitted set are also removed from the effective and retained privilege sets.
PRIV_RETAINED: Modifies or retrieves privileges from the retained privilege set of the process.

DESCRIPTION

The priv_add_effective(), privset_add_effective(), priv_remove(), privset_remove(), privset_set_effective(), and privset_get() functions facilitate the manipulation of the privileges of a process. See privileges(5). The functions beginning with privset_ accept an internal format of the privileges, while functions beginning with priv_, accept a string representation of the privileges.

priv_add_effective(): Adds the given privilege(s) to the calling process' effective privilege set. To add a privilege to the effective privilege set, the privilege should be present in the permitted privilege set of the calling process.
priv_remove(): Removes the given privilege(s) from the calling process' privilege set. The priv_type argument specifies the privilege set is to be modified. Privileges removed from permitted privilege set are also removed from effective and retained privilege sets of the calling process.
priv_set_effective(): Sets the effective privilege set of the calling process to the given privilege(s).
privset_add_effective(): Similar to priv_add_effective(), except that it uses a privilege set type to specify the privileges to add to the calling process' effective privilege set.
privset_get(): Returns the privilege set specified by the priv_type argument of the process specified by pid. If the pid is 0, the calling process's privilege set is returned. The caller must free the memory allocated for the privilege vector when it is no longer referenced using privset_free
privset_remove(): Similar to priv_remove(), except that it uses a privilege set type to specify the privileges to remove from the calling process' effective privilege set.
privset_set_effective(): Similar to priv_set_effective, except that it uses a privilege set type to specify the privileges to set the calling process' effective privilege set.

RETURN VALUE

Upon successful completion, priv_add_effective(), priv_set_effective(), priv_remove(), privset_add_effective(), privset_set_effective(), and privset_remove() return the following values:

0: Successful completion.
-1: Function failed. errno is set to indicate the error.

privset_get() returns the following values:

pointer: Successful completions. Returns a non-null pointer to the privilege vector.
NULL pointer: Function failed. Returns a null pointer and sets errno to indicate the error.

ERRORS

If any of the following conditions occur, the functions fail and set errno.

EINVAL: Invalid parameter or operation.
ENOMEM: The function failed to allocate sufficient memory for its operation.
EPERM: The privilege to be set in the effective set is not present in the permitted set. Attempt to add or remove privileges of a different process fails.
ESRCH: pid is not valid.

EXAMPLES

#include <sys/privileges.h>
#include <stdio.h>
#include <stdlib.h>
#define priv_list "basic,policy,limit,!cmptread,!fork"

main()
{

    if (priv_set_effective(priv_list, ",") )
    {
        printf("priv_set failed \n");
        exit(1);
    }

    printf("\nThe effective set of the process is %s\n",
      priv_set_to_str(privset_get(PRIV_EFFECTIVE, 0), ',', PRIV_STR_SHORT));
}

NOTES

Future product updates may introduce new privileges. In order to assure forward compatibility, applications must not remove a basic privilege from their effective, potential, or retained set that they do not recognize. One way to accomplish this is to use set negation notation: for instance, a process can set its effective set to "basic,!exec,!fork,!linkany" instead of "session". This allows the application to maintain its functionality even when a new basic privilege is introduced. Another way to accomplish this is to use the interface privset_remove() or priv_remove() to remove only the privileges that the application understands.

DEPENDENCIES

These functions are a part of the libsec library.