putauthattrs Subroutine

Purpose

Modifies multiple authorization attributes in the authorization database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int putauthattrs(Auth, Attributes, Count)
    char *Auth;
    dbattr_t *Attributes;
    int Count;

Description

The putauthattrs subroutine modifies one or more attributes from the authorization database. The subroutine can be called only with an authorization that already exists in the user-defined authorization database. Calling the putauthattrs subroutine with an authorization in the system-defined authorization table fails.

The putauthattrs subroutine is used to modify attributes of existing authorizations only. To create or remove user-defined authorizations, use the putauthattr subroutine instead. Data changed by the putauthattrs subroutine must be explicitly committed by calling the putauthattr subroutine with a Type parameter specifying SEC_COMMIT. When all the data is committed, only the getauthattr and getauthattrs subroutines within the process return the modified data. Changes that are made to the authorization 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 value specified in the Attributes array must be examined on a successful call to the putauthattrs subroutine to determine whether the value of the Attributes array was successfully written. The dbattr_t data structure contains the following fields:
Item Description
attr_name The name of the authorization attribute to update.
attr_idx This attribute is used internally by the putauthattrs subroutine.
attr_type The type of the attribute that is being updated.
attr _flag The result of the request to update the target attribute. On successful completion, a value of zero is returned. Otherwise, a value of nonzero value is returned.
attr_un A union that contains the value to update the requested attribute with.
attr_domain This field is ignored by the putauthattrs subroutine.
The following valid authorization attributes for the putauthattrs subroutine are defined in the usersec.h file:
Name Description Type
S_DFLTMSG The default authorization description that is used when catalogs are not in use. SEC_CHAR
S_ID A unique integer that is used to identify the authorization.
Note: After the value is set initially, it must not be modified because it might be in use on the system.
 SEC_INT
S_MSGCAT The message catalog name that contains the authorization description. SEC_CHAR
S_MSGSET The message catalog's set number for the authorization description. SEC_INT
S_MSGNUMBER The message number for the authorization description. SEC_INT
The following union members correspond to the definitions of the attr_char, attr_int, attr_long and the attr_llong macros in the usersec.h file respectively.
Item Description
au_char A character pointer to the value that is to be written for attributes of SEC_CHAR and SEC_LIST types.
au_int Integer value that is to be written for attributes of the SEC_INT type.
au_long Long value that is to be written for attributes of the SEC_LONG type.
au_llong Long long value that is to be written for attributes of the SEC_LLONG type.

Parameters

Item Description
Auth Specifies the authorization name for which the attributes are to be updated.
Attributes A pointer to an array of zero or more attributes of the dbattr_t type. The list of authorization attributes is defined in the usersec.h header file.
Count The number of array elements in the Attributes parameter.

Security

Files Accessed:
File Mode
/etc/security/authorizations rw

Return Values

If the authorization specified by the Auth parameter exists in the authorization database, the putauthattrs subroutine returns zero, even in the case when no attributes in the Attributes array are successfully updated. On successful completion, the attr_flag attribute of each value that is specified in the Attributes array must be examined to determine whether it was successfully updated. If the specified authorization does not exist, a value of -1 is returned and the errno value is set to indicate the error.

Error Codes

If the putauthattrs returns -1, one of the following errno values is set:
Item Description
EINVAL The Auth parameter is NULL, default, ALL, ALLOW_OWNER, ALLOW_GROUP, or ALLOW_ALL.
EINVAL The Auth parameter begins with aix. Authorizations with a hierarchy that begin with aix are reserved for system-defined authorizations and are not modifiable through the putauthattrs subroutine.
EINVAL The Count parameter is less than zero.
EINVAL The Attributes array is NULL and the Count parameter is greater than zero.
EINVAL The Attributes array does not point to valid data for the requested attribute.
ENOENT The authorization specified by the Auth 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 putauthattrs 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 authorization database.
EINVAL The attr_name field in the Attributes entry is not a recognized authorization 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.