siad_update_pass(3)siad_update_pass(3)NAMEsiad_update_pass - store new passphrase routine for SIA (Security Inte‐
gration Architecture)
SYNOPSIS
#include <sia.h> #include <siad.h>
int siad_update_pass
sia_collect_func_t *collect,
SIAENTITY *entity,
int *mechind,
const char newpass );
LIBRARY
Standard C library - libc.so and libc.a
PARAMETERS
This is a pointer to an SIA collection routine that provides the abil‐
ity 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. 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. The
mechind parameter is the package index number for the mechanism. This
index can be used to set the mechanism-specific data pointer array ele‐
ment in the SIAENTITY structure pointed to by entity. Pointer to the
character string which contains a new password.
DESCRIPTION
The siad_update_pass() routine stores the new password in the mecha‐
nism'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: All bits set to 0. Indicates unconditional suc‐
cess, that is, successful storage of the newpass string. Lowest bit
set to 1. Indicates conditional failure, that is, failure to store the
newpass string. If other security mechanism are in place, continue.
Second lowest bit set to 1. Indicates unconditional failure. Do not
continue. Returned when incorrect usage of this routine 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. Fail‐
ures 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
interactive 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
SEE ALSOsia_chg_password(3), siad_chk_user(3), sia_update_pass(3),
siad_test_newpass(3), matrix.conf(4)
Security
siad_update_pass(3)
