getcmdattrs Subroutine

Purpose

Retrieves multiple command attributes from the privileged command database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int getcmdattrs(Command, Attributes, Count)
    char *Command;
    dbattr_t *Attributes;
    int Count;

Description

The getcmdattrs subroutine reads one or more attributes from the privileged command database. The command specified with the Command parameter must include the full path to the command and exist in the privileged command database. If the database is not open, this subroutine does an implicit open for reading.

The Attributes array contains information about each attribute that is to be read. Each element in the Attributes array must be examined upon a successful call to the getcmdattrs subroutine to determine whether the Attributes array was successfully retrieved. The values of the SEC_CHAR or SEC_LIST attributes successfully returned are in the allocated memory. Caller need to free this memory after use. The dbattr_t data structure contains the following fields:

Item	Description
attr_name	The name of the target command attribute.
attr_idx	This attribute is used internally by the getcmdattrs subroutine.
attr_type	The type of the target attribute.
attr _flag	The result of the request to read the target attribute. On successful completion, a value of zero is returned. Otherwise, it returns a nonzero value.
attr_un	A union that contains the returned values for the requested query.
attr_domain	The subroutine ignores any input to this field. If this field is set to null, the subroutine sets this field to the name of the domain where the command is found.

The following valid privileged command attributes for the subroutine are defined in the usersec.h file:

Name	Description	Type
S_PRIVCMDS	Retrieves all the commands in the privileged command database. It is valid only when the Command parameter is ALL.	SEC_LIST
S_ACCESSAUTHS	Access authorizations. This is a null-separated list of authorization names. Sixteen authorizations can be specified. A user with any one of the authorizations is allowed to run the command. In addition to the user-defined and system-defined authorizations available on the system, the following three special values are allowed: ALLOW_OWNER Allows the command owner to run the command without checking for access authorizations. ALLOW_GROUP Allows the command group to run the command without checking for access authorizations. ALLOW_ALL Allows every user to run the command without checking for access authorizations.	SEC_LIST
S_AUTHPRIVS	Authorized privileges. Privilege authorization and authorized privileges pairs indicate process privileges during the execution of the command corresponding to the authorization that the parent process possesses. The authorization and its corresponding privileges are separated by an equal sign (=); individual privileges are separated by a plus sign (+). The attribute is of the SEC_LIST type and the value is a null-separated list, so authorization and privileges pairs are separated by a NULL character (\0), as shown in the following illustration: `auth=priv+priv+...\0auth=priv+priv+...\0...\0\0` The number of authorization and privileges pairs is limited to sixteen.	SEC_LIST
S_AUTHROLES	The role or list of roles, users having these have to be authenticated to allow execution of the command.	SEC_LIST
S_INNATEPRIVS	Innate privileges. This is a null-separated list of privileges that are assigned to the process when running the command.	SEC_LIST
S_INHERITPRIVS	Inheritable privileges. This is a null-separated list of privileges that are assigned to child processes.	SEC_LIST
S_EUID	The effective user ID to be assumed when running the command.	SEC_INT
S_EGID	The effective group ID to be assumed when running the command.	SEC_INT
S_RUID	The real user ID to be assumed when running the command.	SEC_INT

The following union members correspond to the definitions of the attr_char, attr_char, attr_int, attr_long and attr_llong macros in the usersec.h file:

Item	Description
au_char	Attributes of the SEC_CHAR and SEC_LIST types store a pointer to the returned value in this member when the attributes are successfully retrieved. Caller need to free this memory.
au_int	Storage location for attributes of the SEC_INT type.
au_long	Storage location for attributes of the SEC_LONG type.
au_llong	Storage location for attributes of the SEC_LLONG type.

If ALL is specified for the Command parameter, the S_PRIVCMDS attribute is the only valid attribute that is displayed in the Attribute array. Specifying any other attribute with a command name of ALL causes the getcmdattrs subroutine to fail.

Parameters

Item	Description
Command	Specifies the command for the attributes to be read.
Attributes	A pointer to an array of zero or more elements of the dbattr_t type. The list of command attributes is defined in the usersec.h header file.
Count	The number of array elements in the Attributes array.

Security

Files Accessed:

File	Mode
/etc/security/privcmds	r

Return Values

If the command specified by the Command parameter exists in the privileged command database, the getcmdattrs subroutine returns zero. On successful completion, the attr_flag attribute of each element in the Attributes array must be examined to determine whether it was successfully retrieved. On failure, a value of -1 is returned and the errno value is set to indicate the error.

Error Codes

If the getcmdattrs subroutine returns -1, one of the following errno values is set:

Item	Description
EINVAL	The Command parameter is NULL or default.
EINVAL	The Command parameter is ALL but the Attributes entry contains an attribute other than S_PRIVCMDS.
EINVAL	The Count parameter is less than zero.
ENOENT	The command specified in the Command parameter does not exist.
ENOMEM	Memory cannot be allocated.
EPERM	The operation is not permitted.

If the getcmdattrs subroutine fails to query an attribute, one of the following errors is returned in the attr_flag field of the corresponding attributes element:

Item	Description
EACCES	The invoker does not have access to the attribute that is specified in the attr_name field.
EINVAL	The attr_name field in the Attributes array is not a recognized command attribute.
EINVAL	The attr_type field in the Attributes array contains a type that is not valid.
EINVAL	The attr_un field in the Attributes array does not point to a valid buffer.
ENOATTR	The attr_name field in the Attributes array specifies a valid attribute, but no value is defined for this privileged command.
ENOMEM	Memory cannot be allocated to store the return value.
EIO	Failed to access remote command database.