siad_update_pass(3) Library Functions Manual siad_update_pass(3)
NAME
siad_update_pass - store new passphrase routine for SIA (Security Integration Architecture)
LIBRARY
Standard C library - libc.so and libc.a
SYNOPSIS
#include <sia.h>
#include <siad.h>
int siad_update_pass(
sia_collect_func_t *collect,
SIAENTITY *entity,
int *mechind,
const char newpass);
PARAMETERS
collect This is a pointer to an SIA collection routine that provides the ability for the mechanism to prompt the user for additional
information. If this pointer is NULL no collection is possible. If this parameter is not NULL and the colinput parameter
entered during the sia_ses_init() call was zero then this collection routine cannot be used to prompt for input but can be used
to display warnings or error messages.
entity This is a pointer to the SIAENTITY structure that was allocated and setup by the previous sia_ses_init() call. It is used to
access arguments which have either been collected or derived from the session processing.
mechind The mechind parameter is the package index number for the mechanism. This index can be used to set the mechanism-specific data
pointer array element in the SIAENTITY structure pointed to by entity.
newpass Pointer to the character string which contains a new password.
DESCRIPTION
The siad_update_pass() routine stores the new password in the mechanism's user database. An entity must have been set up and the
siad_chk_user() routine must have been able to handle the CHGENTITY flag during processing. This routine may have been called to "stuff" a
password if the mechanism's siad_chk_user() routine was able to handle the CHGNEWVALUE flag.
This routine is called from the sia_chg_password() and sia_update_pass() routines.
RETURN VALUES
The siad_update_pass() routine returns a bitmapped value which indicate the following status:
SIADSUCCESS All bits set to 0. Indicates unconditional success, that is, successful storage of the newpass string.
SIADFAIL Lowest bit set to 1. Indicates conditional failure, that is, failure to store the newpass string. If other security mech-
anism are in place, continue.
SIADFAIL|SIADSTOP
Second lowest bit set to 1. Indicates unconditional failure. Do not continue. Returned when incorrect usage of this rou-
tine is detected, meaning either the entity does not exist or was set up wrong.
For each mechanism in the current list, a call is made to its siad_update_pass() entrypoint. Only return codes of SIADFAIL and SIADSUCCESS
are meaningful here, indicating failure or success. Failures are noted by issuing a warning through the collect routine, and moving that
mechanism to the list for re-try. Successes are noted by an informational message through the collect routine (code SIAINFO) for interac-
tive calls.
For non-interactive calls, the return from the update code is made at this point, with a code of SIASUCCESS if all participating mechanisms
were updated, or SIAFAIL if only some were updated, otherwise with SIAFAIL|SIASTOP if no mechanism could be updated. This return is only
after clearing the old passphrase storage in the entity structure. Auditing of the attempt, and of just which mechanisms were updated,
occurs here.
For interactive calls, the user is notified as to which mechanisms failed and which succeeded. The failures are noted through the collect
routine as they occur. The list of successful mechanisms is noted through the collect routine as a summary at the end of processing.
Retries are up to the user. The return code for an interactive call will be SIASUCCESS if any updates were made, and SIAFAIL if no updates
were made. Auditing of the attempt, as well as of which mechanisms were updated, occurs before returning.
ERRORS
The errno values are those returned from the dynamic loader interface, from the (siad_*) routines, or from malloc. Possible errors include
resource constraints (no memory) and various authentication failures.
FILES
/etc/passwd
/etc/sia/matrix.conf
RELATED INFORMATION
sia_chg_password(3), siad_chk_user(3), sia_update_pass(3), siad_test_newpass(3), matrix.conf(4)
Security delim off
siad_update_pass(3)