putauthattr Subroutine

Purpose

Modifies the authorizations that are defined in the authorization database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int putauthattr(Auth, Attribute, Value, Type)
char *Auth;
char *Attribute;
void *Value;
int Type;

Description

The putauthattr subroutine modifies the authorization database. The subroutine can be invoked only by new authorizations or authorizations that exist in the user-defined authorization database. Calling the putauthattr subroutine with an authorization in the system-defined authorization table will fail.

New authorizations can be added to the authorization database by calling the putauthattr subroutine with the SEC_NEW type and specifying the new authorization name. Authorization names are of a hierarchical structure (that is, parent.subparent.subsubparent). Parent authorization must exist before the child can be created. Deletion of an authorization or authorization attribute is done by using the SEC_DELETE type for the putauthattr subroutine. Deleting an authorization requires that all child authorizations have already been deleted.

Data that is changed by the putauthattr subroutine must be explicitly committed by calling the putauthattr subroutine with a Type parameter specifying the SEC_COMMIT type. Until 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 by using the setkst command or until the system is rebooted.

Parameters

Table 1. Parameters
Item	Description
`Auth`	The authorization name. This parameter must be specified unless the `Type` parameter is `SEC_COMMIT`.
`Attribute`	Specifies the attribute to be written. The following possible attributes are defined in the usersec.h file: S_DFLTMSG Specifies a default authorization description to use if message catalogs are not in use. The attribute type is `SEC_CHAR`. S_ID Specifies a unique integer that is used to identify the authorization. The attribute type is `SEC_INT`. Note: Do not modify this value after it is set initially when the authorization is created. Modifying the value might compromise the security of the system. S_MSGCAT Specifies the message catalog file name that contains the description of the authorization. The attribute type is `SEC_CHAR`. S_MSGSET Specifies the message set that contains the message for the description of the authorization in the file that is specified by the `S_MSGCAT` attribute. The attribute type is `SEC_INT`. S_MSGNUMBER Specifies the message number for the description of the authorization in the file that is specified by the `S_MSGCAT` attribute and the message set that is specified by the `S_MSGSET` attribute. The attribute type is `SEC_INT`.
`Value`	Specifies a buffer, a pointer to a buffer, or a pointer to a pointer according to the values of the `Attribute` and `Type` parameters. See the `Type` parameter for more details.
`Type`	Specifies the type of attribute. The following valid types are defined in the usersec.h file: SEC_INT The format of the attribute is an integer. The user should supply an integer value. SEC_CHAR The format of the attribute is a null-terminated character string. The user should supply a character pointer. SEC_LIST The format of the attribute is a series of concatenated strings, each of which is null-terminated. The last string in the series is terminated by two successive null characters. The user should supply a character pointer. SEC_COMMIT Specifies that the changes to the named authorization are to be committed to permanent storage. The values of the `Attribute` and `Value` parameters are ignored. If no authorization is specified, the changes to all modified authorizations are committed to permanent storage. SEC_DELETE If the `Attribute` parameter is specified, the corresponding attribute is deleted from the authorization database. If no `Attribute` parameter is specified, the entire authorization definition is deleted from the authorization database. SEC_NEW Creates a new authorization in the authorization database.

Security

Files Accessed

File	Mode
/etc/security/authorizations	`rw`

Return Values

If successful, the putauthattr subroutine returns zero. Otherwise, a value of -1 is returned and the errno global value is set to indicate the error.

Error Codes

If the putauthattr subroutine fails, one of the following errno values is set:

Table 2. Error Codes
Item	Description
`EEXIST`	The `Type` parameter is `SEC_DELETE` and the `Auth` parameter specifies an authorization that is the parent of at least one another authorization.
`EINVAL`	The `Auth` parameter is `NULL` and the `Type` parameter is not `SEC_COMMIT`.
`EINVAL`	The `Auth` parameter is `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 using the putauthattr subroutine.
`EINVAL`	The `Attribute` parameter is `NULL` and the `Type` parameter is not `SEC_NEW`, `SEC_DELETE` or `SEC_COMMIT`.
`EINVAL`	The `Attribute` parameter does not contain one of the defined attributes.
`EINVAL`	The `Type` parameter does not contain one of the defined values.
`EINVAL`	The `Value` parameter does not point to a valid buffer or to valid data for this type of attribute.
`ENOENT`	The authorization that is specified by the `Auth` parameter does not exist.
`ENOENT`	The `Auth` parameter specifies a hierarchy and the `Type` parameter is `SEC_NEW`, but the parent authorization does not exist.
`ENOMEM`	Memory cannot be allocated.
`EPERM`	The operation is not permitted.