putroleattrs Subroutine

Edit online

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_HOSTSENABLEDROLE The list of hosts from where the role can be downloaded to the Kernel Role Table. SEC_LIST
S_HOSTSDISABLEDROLE The list of hosts from where the role cannot be downloaded to the Kernel Role Table. 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.