putroleattrs Subroutine

Purpose

Modifies multiple role attributes in the role database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int putroleattrs(Role, Attributes, Count)
    char *Role;
    dbattr_t *Attributes;
    int Count;

Description

The putroleattrs subroutine modifies one or more attributes from the role database. The role specified by the Role parameter must already exist in the role database.

The putroleattrs subroutine is used to modify attributes of existing roles only. To create or remove user-defined roles, use the putroleattr subroutine instead. Data changed by the putroleattrs subroutine must be explicitly committed by calling the putroleattr subroutine with a Type parameter specifying SEC_COMMIT. Until all the data is committed, only the getroleattr and getroleattrs subroutines within the process return the modified data. Changes made to the role database do not impact security considerations until the entire database is sent to the Kernel Security Tables using the setkst command.

The Attributes array contains information about each attribute that is to be updated. Each element in the Attributes array must be examined on a successful call to the putroleattrs subroutine to determine if the Attributes array was successfully written. The dbattr_t data structure contains the following fields:

Item	Description
attr_name	The name of the role attribute to update.
attr_idx	This attribute is used internally by the putroleattrs subroutine.
attr_type	The type of the attribute being updated.
attr _flag	The result of the request to update the desired attribute. Zero is returned on success; a nonzero value is returned otherwise.
attr_un	A union containing the value to update the requested query with.
attr_domain	This field is ignored by the putroleattrs subroutine.

Valid role attributes for the putroleattrs subroutine defined in the usersec.h file are:

Name	Description	Type
S_AUTHORIZATIONS	A list of authorizations assigned to the role.	SEC_LIST
S_AUTH_MODE	The authentication to perform when assuming the role through the swrole command. Possible values are: NONE No authentication is required. INVOKER This is the default value. Invokers of the swrole command must enter their passwords to assume the role.	SEC_CHAR
S_DFLTMSG	The default role description used when catalogs are not in use.	SEC_CHAR
S_GROUPS	The groups that a user is suggested to be a member of. It is for informational purposes only.	SEC_LIST
S_ID	The role identifier.	SEC_INT
S_MSGCAT	The message catalog name containing the role description.	SEC_CHAR
S_MSGSET	The message catalog set number for the role description.	SEC_INT
S_MSGNUMBER	The message number for the role description.	SEC_INT
S_ROLELIST	The list of roles whose authorizations are included in this role.	SEC_LIST
S_SCREENS	The SMIT screens that the role can access.	SEC_LIST
S_VISIBILITY	An integer that determines whether the role is active or not. Possible values are: -1 The role is disabled. 0 The role is active but not visible from a GUI. 1 The role is active and visible. This is the default value.	SEC_INT

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

Item	Description
au_char	A character pointer to the value to be written for attributes of the SEC_CHAR and SEC_LIST types.
au_int	Integer value to be written for attributes of the SEC_INT type.
au_long	Long value to be written for attributes of the SEC_LONG type.
au_llong	Long long value to be written for attributes of the SEC_LLONG type.

Parameters

Item	Description
Role	Specifies the role name for which the attributes are to be updated.
Attributes	A pointer to an array of zero or more elements of the dbattr_t type. The list of role 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/roles	rw

Return Values

If the role specified by the Role parameter exists in the role database, the putroleattrs subroutine returns zero, even in the case when no attributes in the Attributes array were successfully updated. On success, the attr_flag attribute of each element in the Attributes array must be examined to determine whether it was successfully updated. If the specified role does not exist, a value of -1 is returned, and the errno value is set to indicate the error.

Error Codes

If the putroleattrs returns -1, one of the following errno values can be set:

Item	Description
EINVAL	The Role parameter is NULL or ALL.
EINVAL	The Count parameter is less than zero.
EINVAL	The Attributes parameter is NULL and the Count parameter is greater than zero.
EINVAL	The Attributes parameter does not point to valid data for the requested attribute.
ENOENT	The role specified by the Role parameter does not exist.
ENOMEM	Memory cannot be allocated.
EPERM	The operation is not permitted.
EACCES	Access permission is denied for the data request.

If the putroleattrs subroutine fails to update 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 write access to the role database.
EINVAL	The attr_name field in the Attributes entry is not a recognized role attribute.
EINVAL	The attr_type field in the Attributes entry contains a type that is not valid.
EINVAL	The attr_un field in the Attributes entry does not point to a valid buffer or to valid data for this type of attribute.