Index for Section 3

Alphabetical listing for S

Bottom of page

siad_update_pass(3)
NAME
  siad_update_pass - store new passphrase routine for SIA (Security
  Integration 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
  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 mechanism are in place,
      continue.

  SIADFAIL |   SIADSTOP
      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. 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 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 ALSO
  sia_chg_password(3), siad_chk_user(3), sia_update_pass(3),
  siad_test_newpass(3), matrix.conf(4)

  Security

Index for Section 3

Alphabetical listing for S

Top of page