getuserattrs Subroutine

Purpose

Retrieves multiple user attributes in the user database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int getuserattrs (User, Attributes, Count) char * User; dbattr_t * Attributes; int Count

Description

Attention: Do not use this subroutine and the setpwent and setgrent subroutines simultaneously. The results can be unpredictable.

The getuserattrs subroutine accesses user information. Because of its greater granularity and extensibility, use it instead of the getpwent routines.

The getuserattrs subroutine reads one or more attributes from the user database. If the database is not already open, this subroutine does an implicit open for reading. A call to the getuserattrs subroutine with an Attributes parameter of null and the Count parameter of zero for every new user verifies that the user exists.

The Attributes array contains information about each attribute that is to be read. The dbattr_t data structure contains the following fields:

attr_name

The name of the desired attribute.

attr_idx

Used internally by the getuserattrs subroutine.

attr_type

The type of the desired attribute. The following possible attributes are defined in the usersec.h file:

S_CORECOMP

Core compression status. The attribute type is SEC_CHAR.

S_COREPATH

Core path specification status. The attribute type is SEC_CHAR.

S_COREPNAME

Core path specification location. The attribute type is SEC_CHAR.

S_CORENAMING

Core naming status. The attribute type is SEC_CHAR.

S_ID

User ID. The attribute type is SEC_INT.

S_PGID

Principle group ID. The attribute type is SEC_INT.

S_PGRP

Principle group name. The attribute type is SEC_CHAR.

S_GROUPS

Groups to which the user belongs. The attribute type is SEC_LIST.

S_ADMGROUPS

Groups for which the user is an administrator. The attribute type is SEC_LIST.

S_ADMIN

Administrative status of a user. The attribute type is SEC_BOOL.

S_AUDITCLASSES

Audit classes to which the user belongs. The attribute type is SEC_LIST.

S_AUTHSYSTEM

Defines the user's authentication method. The attribute type is SEC_CHAR.

S_HOME

Home directory. The attribute type is SEC_CHAR.

S_SHELL

Initial program run by a user. The attribute type is SEC_CHAR.

S_GECOS

Personal information for a user. The attribute type is SEC_CHAR.

S_USRENV

User-state environment variables. The attribute type is SEC_LIST.

S_SYSENV

Protected-state environment variables. The attribute type is SEC_LIST.

S_LOGINCHK

Specifies whether the user account can be used for local logins. The attribute type is SEC_BOOL.

S_HISTEXPIRE

Defines the period of time (in weeks) that a user cannot reuse a password. The attribute type is SEC_INT.

S_HISTSIZE

Specifies the number of previous passwords that the user cannot reuse. The attribute type is SEC_INT.

S_MAXREPEAT

Defines the maximum number of times a user can repeat a character in a new password. The attribute type is SEC_INT.

S_MINAGE

Defines the minimum age in weeks that the user's password must exist before the user can change it. The attribute type is SEC_INT.

S_PWDCHECKS

Defines the password restriction methods for this account. The attribute type is SEC_LIST.

S_MINALPHA

Defines the minimum number of alphabetic characters required in a new user's password. The attribute type is SEC_INT.

S_MINDIFF

Defines the minimum number of characters required in a new password that were not in the old password. The attribute type is SEC_INT.

S_MINLEN

Defines the minimum length of a user's password. The attribute type is SEC_INT.

S_MINOTHER

Defines the minimum number of non-alphabetic characters required in a new user's password. The attribute type is SEC_INT.

S_DICTIONLIST

Defines the password dictionaries for this account. The attribute type is SEC_LIST.

S_SUCHK

Specifies whether the user account can be accessed with the su command. Type SEC_BOOL.

S_REGISTRY

Defines the user's authentication registry. The attribute type is SEC_CHAR.

S_RLOGINCHK

Specifies whether the user account can be used for remote logins using the telnet or rlogin commands. The attribute type is SEC_BOOL.

S_DAEMONCHK

Specifies whether the user account can be used for daemon execution of programs and subsystems using the cron daemon or src. The attribute type is SEC_BOOL.

S_TPATH

Defines how the account might be used on the trusted path. The attribute type is SEC_CHAR. This attribute must be one of the following values:

nosak: The secure attention key is not enabled for this account.
notsh: The trusted shell cannot be accessed from this account.
always: This account may only run trusted programs.
on: Normal trusted-path processing applies.

S_TTYS

List of ttys that can or cannot be used to access this account. The attribute type is SEC_LIST.

S_SUGROUPS

Groups that can or cannot access this account. The attribute type is SEC_LIST.

S_EXPIRATION

Expiration date for this account is a string in the form MMDDhhmmyy, where MM is the month, DD is the day, hh is the hour in 0 to 24 hour notation, mm is the minutes past the hour, and yy is the last two digits of the year. The attribute type is SEC_CHAR.

S_AUTH1

Primary authentication methods for this account. The attribute type is SEC_LIST.

S_AUTH2

Secondary authentication methods for this account. The attribute type is SEC_LIST.

S_UFSIZE

Process file size soft limit. The attribute type is SEC_INT.

S_UCPU

Process processor time soft limit. The attribute type is SEC_INT.

S_UDATA

Process data segment size soft limit. The attribute type is SEC_INT.

S_USTACK

Process stack segment size soft limit. Type: SEC_INT.

S_URSS

Process real memory size soft limit. Type: SEC_INT.

S_UCORE

Process core file size soft limit. The attribute type is SEC_INT.

S_UNOFILE

Process file descriptor table size soft limit. The attribute type is SEC_INT.

S_PWD

Specifies the value of the passwd field in the /etc/passwd file. The attribute type is SEC_CHAR.

S_UMASK

File creation mask for a user. The attribute type is SEC_INT.

S_LOCKED

Specifies whether the user's account can be logged into. The attribute type is SEC_BOOL.

S_ROLES

Defines the administrative roles for this account. The attribute type is SEC_LIST.

S_UFSIZE_HARD

Process file size hard limit. The attribute type is SEC_INT.

S_UCPU_HARD

Process processor time hard limit. The attribute type is SEC_INT.

S_UDATA_HARD

Process data segment size hard limit. The attribute type is SEC_INT.

S_USREXPORT

Specifies if the DCE registry can overwrite the local user information with the DCE user information during a DCE export operation. The attribute type is SEC_BOOL.

S_USTACK_HARD

Process stack segment size hard limit. Type: SEC_INT.

S_URSS_HARD

Process real memory size hard limit. Type: SEC_INT.

S_UCORE_HARD

Process core file size hard limit. The attribute type is SEC_INT.

S_UNOFILE_HARD

Process file descriptor table size hard limit. The attribute type is SEC_INT.

S_DFLT_ROLES

The default roles for the user. It can be one or more. The attribute type is SEC_LIST.

S_DOMAINS

The domains for the user. It can be one or more. The attribute type is SEC_LIST.

S_MINLOWERALPHA

Defines the minimum number of lowercase alphabetic characters required in a new user password. The attribute type is SEC_INT.

S_MINUPPERALPHA

Defines the minimum number of uppercase alphabetic characters required in a new user password. The attribute type is SEC_INT.

S_MINDIGIT

Defines the minimum number of digits required in a new user password. The attribute type is SEC_INT.

S_MINSPECIALCHAR

Defines the minimum number of special characters required in a new user password. The attribute type is SEC_INT.

attr_flag

The results of the request to read the desired attribute.

attr_un

A union containing the returned values. Its union members, which follows, correspond to the definitions of the attr_char, attr_int, attr_long, and attr_llong macros, respectively:

au_char: Attributes of type SEC_CHAR and SEC_LIST store a pointer to the returned attribute in this member when the requested attribute is successfully read. The caller is responsible for freeing this memory.
au_int: Attributes of type SEC_INT and SEC_BOOL store the value of the attribute in this member when the requested attribute is successfully read.
au_long: Attributes of type SEC_LONG store the value of the attribute in this member when the requested attribute is successfully read.
au_llong: Attributes of type SEC_LLONG store the value of the attribute in this member when the requested attribute is successfully read.

attr_domain

The authentication domain containing the attribute. The getuserattrs subroutine is responsible for managing the memory referenced by this pointer. If attr_domain is specified for an attribute, the get request is sent only to that domain. If attr_domain is not specified (that is, set to NULL), getuserattrs searches the domains known to the system and sets this field to the name of the domain from which the value is retrieved. This search space can be restricted with the setauthdb subroutine so that only the domain specified in the setauthdb call is searched. If the request for a NULL domain was not satisfied, the request is tried from the local files using the default stanza.

Use the setuserdb and enduserdb subroutines to open and close the user database. Failure to explicitly open and close the user database can result in loss of memory and performance.

Parameters

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

Security

Files accessed:

Item	Description
Mode	File
rw	/etc/passwd
rw	/etc/group
rw	/etc/security/user
rw	/etc/security/limits
rw	/etc/security/group
rw	/etc/security/environ

Return Values

If User exists, the getuserattrs subroutine returns zero. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error. Each element in the Attributes array must be examined on a successful call to getuserattrs to determine if the Attributes array entry was successfully retrieved.

Error Codes

The getuserattrs subroutine returns an error that indicates that the user does or does not exist. Additional errors can indicate an error querying the information databases for the requested attributes.

Item	Description
EINVAL	The Count parameter is less than zero.
EINVAL	The Attributes parameter is null and the Count parameter is greater than zero.
ENOENT	The specified User parameter does not exist.
EIO	Failed to access remote user database.

If the getuserattrs subroutine fails to query an attribute, one or more of the following errors is returned in the attr_flag field of the corresponding Attributes element:

Item	Description
EACCES	The user does not have access to the attribute specified in the attr_name field.
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. Limited testing is possible and all errors might not be detected.
ENOATTR	The attr_name field in the Attributes entry specifies an attribute that is not defined for this user or group.

Examples

The following sample test program displays the output to a call to getuserattrs. In this example, the system has a user named foo.

#include <stdio.h> 
#include <usersec.h>

#define NATTR 3
#define USERNAME "foo"

main() {

	dbattr_t attributes[NATTR]; 
	int 	i;
	int 	rc;


	memset (&attributes, 0, sizeof(attributes));

	/*
	 * Fill in the attributes array with "id", "expires" and
	 * "SYSTEM" attributes.
	 */

	attributes[0].attr_name = S_ID;
	attributes[0].attr_type = SEC_INT;;

	attributes[1].attr_name = S_ADMIN;
	attributes[1].attr_type = SEC_BOOL;

	attributes[2].attr_name = S_AUTHSYSTEM;
	attributes[2].attr_type = SEC_CHAR;

	/* 
	 * Make a call to getuserattrs.
	 */

        setuserdb(S_READ);

	rc = getuserattrs(USERNAME, attributes, NATTR);

        enduserdb();

	if (rc) {
		printf("getuserattrs failed ....\n");
		exit(-1);
	}

	for (i = 0; i < NATTR; i++) {
		printf("attribute name   : %s \n", attributes[i].attr_name);
		printf("attribute flag   : %d \n", attributes[i].attr_flag);

		if (attributes[i].attr_flag) {

			/*
			 * No attribute value. Continue.
			 */
			printf("\n");
			continue;
		}
		/*
		 * We have a value.
		 */
		printf("attribute domain : %s \n", attributes[i].attr_domain);
		printf("attribute value  : ");

		switch (attributes[i].attr_type)
		{
			case SEC_CHAR:
				if (attributes[i].attr_char) {
                               		printf("%s\n", attributes[i].attr_char);
					free(attributes[i].attr_char);
				}
                               	break;
			case SEC_INT:
			case SEC_BOOL:
                       		printf("%d\n", attributes[i].attr_int);
                               	break;
			default:
				break;
                }
		printf("\n");
	}
	exit(0);
}

The following output for the call is expected:

	attribute name   : id 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : 206
	
	attribute name   : admin 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : 0
	
	attribute name   : SYSTEM 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : compat

Files

Item	Description
/etc/passwd	Contains user IDs.