saf-process.c

Go to the documentation of this file.

/****************************************************************************
 *
 *      Copyright (C) 2006-2008 Micro Focus (IP) Limited.
 *      All rights reserved.
 *
 * The software and information contained herein are proprietary to, and
 * comprise valuable trade secrets of, Micro Focus International Ltd., 
 * which intends to preserve as trade secrets such software and 
 * information. This software is an unpublished copyright of Micro Focus  
 * and may not be used, copied, transmitted, or stored in any manner.  
 * This software and information or any other copies thereof may not be
 * provided or otherwise made available to any other person.
 *
 *      Enterprise Server SAF (Security) Manager
 *      SAF Request Processing
 *
 *      @(#)saf-process.c   $Revision: 1.2 $     
 *
 *      $Date: 2008/07/01 08:32:50 $
 *
 ****************************************************************************/

/* Copyright */
static const char *copyright =
   "Copyright (C) 2006-2008 Micro Focus (IP) Limited";
static const char *sccsid =
   "@(#)saf-process.c  $Revision: 1.2 $ built " __DATE__ " " __TIME__;

/* Start of source module saf-process.c */


/* System Headers */

/* ANSI/ISO standard headers */
#include <stddef.h>
#include <stdlib.h>
#include <stdio.h>
#include <stdarg.h>
#include <string.h>
#include <time.h>
#include <errno.h>
#include <ctype.h>

/* UNIX headers */
#if defined(UNIX)
#   include <unistd.h>
#   include <sys/time.h>
#endif

/* Win32 headers */
#if defined(WIN32)
#   include <windows.h>
#   include <sys/types.h>
#   include <sys/stat.h>
#endif


/* External Headers */
#if defined(UNIX)
#  include "gptypes.h"          /* RTS types, req. by CCI */
#elif defined(WIN32)
#  include "pc_rts.h"           /* ditto for Win32 */
#endif
#include "cci.h"                /* CCI API and types */
                                /* (required for mf_os_size typedef) */
#include "mdsa.h"               /* MDSA SAF and ESM configuration */


/* SAF Headers */

#define saf78_SAFADMIN_DATA_AREAS
#include "safapi.h"
#include "safmgr.h"
#include "saf-esm.h"
#include "saf-env.h"
#include "saf-acee.h"
#include "saf-process.h"
#include "saf-audit.h"
#include "mfaudit.h"


/***
Structure for cached update area. In a shared-memory multiprocess
environment (ie CAS), each update is only processed by a single ESF-calling
process (ie a SEP). That process handles clearing out any globally-cached
data in shared memory, as well as its own private data.

But the other processes will still need to clear out their private data.
So we keep, in shared memory, a cached copy of the most recent admin update, 
plus a sequence number for updates. Then, as each process gets activated,
it checks to see if it's missed any updates (by comparing the global
sequence number with its own internal sequence number). If the sequence
numbers are the same, it hasn't missed any. If they're different by one,
it's only missed the cached update, and it needs to process that (for its
private memory only). If they differ by more than one, it's missed multiple
updates, and it needs to flush all private cached data.

This structure serves as a header for the global cache area. It includes
the sequence number, the cached request, and the indirect data from the
request, such as the entity name and the ACEE.
***/

#define SafCACHE_MAX_ENTITY_LEN 1024

struct UpdateCache
{
   mf_uns32              Sequence;  /* global update sequence number */
   Safpb_Parameter_Block PBlock;    /* cached request block */
   SafACEE               ACEE;      /* ACEE from request */
   char                  Entity[SafCACHE_MAX_ENTITY_LEN];
                                    /* Entity name from request */
};



static SafRet AuditAdminReq(struct safpb_parameter_block *PBlock,
                            int ReqType, SafACEE *AceePtr,
                            const char *CmdName, int CmdLen);
static int LockUpdateArea(void);
static int UnlockUpdateArea(void);
static SafRet HandlePendingUpdates(struct UpdateCache *Cache);
static mf_uns32 CheckForPendingSharedUpdate(struct UpdateCache *Cache);
static struct UpdateCache *GetUpdateCache(void);
static const char *UpdateTypeToString(unsigned char Type);
static const char *EsmrcToString(mf_uns32 EsmRet);


/* Private Data */
static mf_uns32 NumESMMods = 0;
static int AllowUnknownUsers = 0,
           AllowUnknownResources = 0,
           VerifyAllESMs = 0;



/*** Management ***/

mf_uns32 SafProcInit(struct SafInit *Init)
{
   /* Store number of configured ESM Modules */
   NumESMMods = Init->ESMCnt;

   /* Set processing option flags */
   AllowUnknownUsers =
      !! (Init->Config->option_flags & SAF_OPTION_ALLOW_UNKNOWN_USERS);
   AllowUnknownResources =
      !! (Init->Config->option_flags & SAF_OPTION_ALLOW_UNKNOWN_RESOURCES);
   VerifyAllESMs =
      !! (Init->Config->option_flags & SAF_OPTION_VERIFY_AGAINST_ALL_ESMS);

   return SafINIT_OK;
}



/*** SAF Requests ***/

int SafVerify(struct safpb_parameter_block *PBlock)
{
   int Ret = saf78_SAF_RC_SUCCESS, Resolved = 0, Tentative = 0, Allowed = 0,
       IsSysUser = 0;
   mf_uns32 CurrEsm, EsmRet, NumCalled = 0;
   SafRet SRet;
   struct SafACEE *Acee = NULL;
   char AUserBuf[16] = "???", *MUserBuf = NULL, *UserBuf = AUserBuf;
   char GroupBuf[9] = "", *GrpBufPtr, *GrpPtr;
   mf_uns32 UserLen;
   extern int SafCasOldAcee;     /* see saf-esm.c */

   /* Passtoken control */
   #define SafPT_UNKNOWN     (1u<<7)
   #define SafPT_GEN_ALLOWED (1u<<0)
   #define SafPT_USE_ALLOWED (1u<<1)
   static unsigned TokenPerm = SafPT_UNKNOWN;
   

   if (!PBlock)
      return 0;

   UserLen = PBlock->REQUESTS.VERIFY.safpb_verify_USERID_len;
  

   /* Check state */
   if (SafState() != 1)
   {
      Ret = saf78_SAF_RC_FAILURE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
      goto done;
   }

   /* Make sure this a function we handle */
   if (PBlock->safpb_type == saf78_TYPE_ENVIR_DESTROY)
   {
      /* TODO: Handle DESTROY */
      return 0;
   }

   /*AUDITEVENTCALL Check: Verify/create */
   SafRaiseAuditEvent
   (
      AUDIT_EVENT_CHECK_VERIFY
    , AUDIT_EVENT_CATEGORY_SEC_API_REQ_CHECK
    , 2
    , SafEventData
      (
        AUDIT_RECORD_DATA_TYPE_STRING
       ,PBlock->REQUESTS.VERIFY.safpb_verify_USERID_ptr
       ,PBlock->REQUESTS.VERIFY.safpb_verify_USERID_len
      )
    , SafEventData
      (
        AUDIT_RECORD_DATA_TYPE_STRING
       ,PBlock->REQUESTS.VERIFY.safpb_verify_group
       ,sizeof(PBlock->REQUESTS.VERIFY.safpb_verify_group)
      )
   );          


   /* Make sure we have no pending shared update notices */
   HandlePendingUpdates(NULL);


   /* Extract user name string */
   AUserBuf[0] = '\0';              /* to prevent logging issues below */
   UserBuf = AUserBuf;

   if (UserLen < sizeof AUserBuf)
   {
      UserBuf = AUserBuf;
   }
   else
   {
      MUserBuf = malloc(UserLen + 1);
      if (! MUserBuf)
      {
         /* TODO: Audit this */
         Ret = saf78_SAF_RC_FAILURE;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
         goto done;
      }
      UserBuf = MUserBuf;
   }

   memcpy(UserBuf, PBlock->REQUESTS.VERIFY.safpb_verify_USERID_ptr, UserLen);
   UserBuf[UserLen] = '\0';


   /* Extract group string */
   for (GrpBufPtr = GroupBuf,
           GrpPtr = PBlock->REQUESTS.VERIFY.safpb_verify_group;
        *GrpPtr > ' '
           && GrpPtr < PBlock->REQUESTS.VERIFY.safpb_verify_group + 8;
        GrpBufPtr++, GrpPtr++)
   {
      *GrpBufPtr = *GrpPtr;
   }
   *GrpBufPtr = '\0';
        

   /* Check for special processing */
   IsSysUser = PBlock->safpb_flag & saf78_VER_NO_PASSWORD;


   /***
   Passtoken support: if this is a passtoken request (one of Verify-with-
   generate-ticket, Generate-token, or Verify-using-token), check to see
   if it's allowed by our config; this may require parsing the config for
   the first time.
   ***/

   if ((PBlock->safpb_flag & saf78_VER_PT_TICKET) ||
       (PBlock->safpb_flag & saf78_VER_PASSTOKEN) ||
       (PBlock->safpb_flag & saf78_VER_PT_SURROGATE) ||
       (PBlock->safpb_type == saf78_TYPE_TOKEN_CREATE))
   {
      /* Do we need to parse the config setting? */
      if (TokenPerm == SafPT_UNKNOWN)
      {
         char *PTAllow = NULL;
         SafQueryCfg("Passtoken", "allow", &PTAllow);
         if (! PTAllow) PTAllow = "";
         if (SafSTRCMP_CI(PTAllow, ==, "none"))
            TokenPerm = 0;
         else if (SafSTRCMP_CI(PTAllow, ==, "generate"))
            TokenPerm = SafPT_GEN_ALLOWED;
         else if (SafSTRCMP_CI(PTAllow, ==, "signon"))
            TokenPerm = SafPT_USE_ALLOWED;
         else
            TokenPerm = SafPT_GEN_ALLOWED | SafPT_USE_ALLOWED;
      }

      /* Now check to see if this kind of request is allowed */
      if (PBlock->safpb_flag & saf78_VER_PT_TICKET)
      {
         /***
         Request to generate ticket.  If disallowed, or if this is a
         no-password or surrogate-token Verify, silently turn off ticket
         request flag.
         ***/

         if (! (TokenPerm & SafPT_GEN_ALLOWED)
             || (PBlock->safpb_flag & saf78_VER_NO_PASSWORD)
             || (PBlock->safpb_flag & saf78_VER_PT_SURROGATE))
         {
            /* Silently disable ticket-generation option */
            PBlock->safpb_flag &= ~saf78_VER_PT_TICKET;
         }
      }

      if (PBlock->safpb_type == saf78_TYPE_TOKEN_CREATE)
      {
         /* Request to generate token */
         if (! (TokenPerm & SafPT_GEN_ALLOWED))
         {
            /* Reject request */
            Ret = saf78_SAF_RC_FAILURE;
            PBlock->RETCODES.DISCRETE.safpb_mgr_return =
               saf78_RC_TOKEN_REFUSED;
            goto done;
         }
      }

      if ((PBlock->safpb_flag & saf78_VER_PASSTOKEN) ||
          (PBlock->safpb_flag & saf78_VER_PT_SURROGATE))
      {
         /* Request to verify using token */
         if (! (TokenPerm & SafPT_USE_ALLOWED))
         {
            /* Reject request */
            Ret = saf78_SAF_RC_FAILURE;
            PBlock->RETCODES.DISCRETE.safpb_mgr_return =
               saf78_RC_TOKEN_REFUSED;
            #if _DEBUG && SafLOG_ALL
               SafLog
               (
                  2002
                , SafMsgINFO
                , "Passtoken Verify refused for user \"%s\""
                , UserBuf
               );
            #endif
            goto done;
         }
      }
   }


   /* Passtoken-delete requests are handled specially */
   if (PBlock->safpb_type == saf78_TYPE_TOKEN_DELETE)
   {
      /* ESM index must be set in request block */
      if (! PBlock->safpb_safesm_index)
      {
         Ret = saf78_SAF_RC_PARM_ERROR;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_SAFESM_INDEX;
         PBlock->RETCODES.DISCRETE.safpb_mgr_reason = saf78_RS_BAD_VALUE;
         goto done;
      }

      /* Assume success */
      Ret = 0;
      PBlock->RETCODES.DISCRETE.safpb_api_rc     = 0;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
      PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;

      /* Call the specified ESM module */
      EsmRet = SafEsmCVerify(PBlock->safpb_safesm_index - 1, PBlock);

      if (EsmRet)
      {
         Ret = saf78_SAF_RC_FAILURE;
         if (! PBlock->RETCODES.DISCRETE.safpb_mgr_return)
         {
            PBlock->RETCODES.DISCRETE.safpb_mgr_return =
               saf78_RC_DATABASE_ERROR;
         }
      }

      goto done;
   }


   /* Call ESM Modules */
   PBlock->RETCODES.DISCRETE.safpb_api_rc     = saf78_SAF_RC_NOT_COMPLETE;
   PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
   PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;

   for (CurrEsm=0; CurrEsm < NumESMMods && !Resolved; CurrEsm++)
   {
      const char *ErrType = NULL;

      /* Set ESM index in parameter block */
      PBlock->safpb_safesm_index = (unsigned char) CurrEsm + 1;

      /* Call ESM Module */
      EsmRet = SafEsmCVerify(CurrEsm, PBlock);

      /* Handle non-zero return codes */
      /* TODO: Refactor translation of return codes to text */
      switch (EsmRet)
      {
         case SafESMRC_OK:
            /* Did we get a definite response? */
            if (PBlock->RETCODES.DISCRETE.safpb_api_rc !=
                saf78_SAF_RC_NOT_COMPLETE)
            {
               /***
               If the request failed, we're done.  If the request is still
               indeterminate, continue.  If the request succeeded, then
               there are two possibilities:
               
               - By default, we continue to call other ESMs, but with the
               parameter block's safpb_api_rc set to RC_SUCCESS.  ESMs
               should recognize this as an opportunity to update the ACEE,
               but should not attempt to verify the user again.  We ignore
               results from the other ESMs, unless they fail.

               - If VerifyAllESMs is set, we log a tentative success, but
               continue to call other ESMs as if the user had not been
               verified.  This implements a librum veto - any ESM can
               reject a user.

               The first case is actually a bit broken, because ESMs that
               have a higher priority than the one that allows the user
               don't have a chance to update the ACEE.  We should make
               this "update the ACEE" function a separate one - possibly
               by calling another ESM function after a successful verify.
               ***/

               if (Allowed)
               {
                  /* User already verified; reset SAF return code */
                  PBlock->RETCODES.DISCRETE.safpb_api_rc = saf78_SAF_RC_SUCCESS;
               }
               else if (PBlock->RETCODES.DISCRETE.safpb_api_rc !=
                        saf78_SAF_RC_SUCCESS)
               {
                  /* Verify failed */
                  Resolved = 1;
                  Tentative = 0;
               }
               else if (VerifyAllESMs)
               {
                  /* If no one else rejects, accept */
                  Tentative = 1;
                  PBlock->RETCODES.DISCRETE.safpb_api_rc =
                     saf78_SAF_RC_NOT_COMPLETE;
               }
               else
               {
                  /* Verify succeded; let other ESMs update ACEE */
                  Allowed = 1;
               }
            }

            /* Increment number of ESMs called successfully */
            NumCalled++;
            break;

         case SafESMRC_NOTIMPL:
            /* Not a definite response; keep trying */
            break;

         /* All other cases represent an ESM Module failure */
         case SafESMRC_PARAM:
            ErrType = "parameter error";
            break;
         case SafESMRC_RESOURCE:
            ErrType = "resource unavailable";
            break;
         case SafESMRC_EXTERNAL:
            ErrType = "ESM error";
            break;
         case SafESMRC_MGRFAIL:
            ErrType = "ESF Manager failure";
            break;
         case SafESMRC_FAIL:
            ErrType = "miscellaneous failure";
            break;
         default:
            ErrType = "unknown error";
            break;
      }

      /* Check for failure */
      if (ErrType)
      {
         mf_uns32 esmnum;
         const char* esmname;

         /* Log this */
         SafLog
         (
            110
          , SafMsgERR
          , "ESM Module %d (%s) returned error code %d (%s) from Verify"
          , CurrEsm+1
          , SafEsmName(CurrEsm)
          , (int)EsmRet
          , ErrType
         );
         
         /* TODO: Audit this */
          esmnum=CurrEsm+1;
          esmname=SafEsmName(CurrEsm);

         /* AUDITEVENTCALL Verify ESM Error*/
         SafRaiseAuditEvent
         (
            AUDIT_EVENT_VERIFY_ESM_ERROR
          , AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR
          , 4
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_COMP5
             , (void*)&esmnum
             , sizeof(esmnum)
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_STRING
             , (void*)esmname
             , (int)strlen(esmname)
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_COMP5
             , (void*)&EsmRet
             , sizeof(EsmRet)
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_STRING
             , (void*)ErrType
             , (int)strlen(ErrType)
            ) 

         );   
                

         /* Convert to failure result */
         PBlock->RETCODES.DISCRETE.safpb_api_rc = saf78_SAF_RC_FAILURE;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return =
            saf78_RC_DATABASE_ERROR;
         Resolved = 1;
      }
   }


   /***
   Convert a tentative resolution (used when call-all-ESMs mode is enabled)
   to a definite one, now that all ESMs have been called (or we have a
   rejection, in which case this is a no-op).
   ***/

   if (Tentative || Allowed)
   {
      Resolved = 1;
      if (PBlock->RETCODES.DISCRETE.safpb_api_rc == saf78_SAF_RC_NOT_COMPLETE)
      {
         /* We were tentatively allowing this user, so make that official */
         PBlock->RETCODES.DISCRETE.safpb_api_rc = saf78_SAF_RC_SUCCESS;
      }
   }


   /* Handle indefinite response */
   if (! Resolved)
   {
      /* Indicate decision made by SAF Manager */
      PBlock->safpb_safesm_index = 0;

      if (NumCalled == 0)
      {
         /* No enabled ESMs that implement Verify; accept everything */
         PBlock->RETCODES.DISCRETE.safpb_api_rc = saf78_SAF_RC_SUCCESS;
      }
      else
      {
         /***
         Default action based on configuration, except that we always
         allow unknown if verify-no-password is set.
         ***/

         if (AllowUnknownUsers || IsSysUser)
         {
            PBlock->RETCODES.DISCRETE.safpb_api_rc = saf78_SAF_RC_SUCCESS;

            /* AUDITEVENTCALL Verify allowed for unknown*/
            SafRaiseAuditEvent
            (
              AUDIT_EVENT_VERIFY_ALLOW_UNKNOWN
            , AUDIT_EVENT_CATEGORY_SEC_API_RES_ALLOW
            , 1
            , SafEventData
              (
                 AUDIT_RECORD_DATA_TYPE_STRING
               , (void*)UserBuf
               , (int)strlen(UserBuf)
              )
            );
         }
         else
         {
            /* Note this is audited below */
            PBlock->RETCODES.DISCRETE.safpb_api_rc = saf78_SAF_RC_FAILURE;
            PBlock->RETCODES.DISCRETE.safpb_mgr_return =
               saf78_RC_NO_USER_PROFILE;
         }
      }
   }


   /* Set Ret from final ESF return code */
   Ret = PBlock->RETCODES.DISCRETE.safpb_api_rc;


   /* If verify failed, we're done */
   if (Ret) goto done;


   /* Create ACEE, if none of the ESMs did */
   if (! PBlock->REQUESTS.VERIFY.safpb_verify_ACEE_ptr)
   {
      /* Allocate ACEE */
      /* TODO: Use default name mapping here */
      SRet = SafAceeAlloc(UserBuf, *GroupBuf? GroupBuf : NULL, &Acee, NULL);
      if (SRet)
      {
         Ret = saf78_SAF_RC_FAILURE;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
      }

      if (SafCasOldAcee)
      {
         unsigned char *TmpPtr;
         TmpPtr = (unsigned char *)Acee;
         TmpPtr -= 8;                        /* back up to SAA area */
         PBlock->REQUESTS.VERIFY.safpb_verify_ACEE_ptr = (void *)TmpPtr;
      }
      else
         PBlock->REQUESTS.VERIFY.safpb_verify_ACEE_ptr = Acee;

      /* TEMPORARY: set access flags to "update" for CICS 1.7 security */
      memset(Acee->SecurityKeys, 0xff, sizeof Acee->SecurityKeys);
      memset(Acee->ResourceKeys, 0xff, sizeof Acee->ResourceKeys);
      memset(Acee->UserResourceKeys, 0xff, sizeof Acee->UserResourceKeys);
      memset(Acee->RdAccessFlags, 1, sizeof Acee->RdAccessFlags);

      /* TODO: Finish populating ACEE */

      /* TEMPORARY: Special settings for system users */
      if (IsSysUser)
      {
         if (SafSTRCMP(UserBuf, ==, "mfuser"))
         {
            Acee->Flag3 |= SafACEE_F3_DUID;        /* default user */
            memcpy(Acee->OperId, "mfu", 3);
            Acee->OperClass[2] = '\x01';
         }
         else
         {
            Acee->Flag3 |= SafACEE_F3_NPWR;        /* special user */
         }
      }
   }

   else
   {
      /***
      If CAS wants old-style ACEEs, and an ESM Module assigned a new-style
      ACEE to the parameter block, adjust the pointer.
      ***/

      unsigned char *AceePtr;

      AceePtr = (unsigned char *)PBlock->REQUESTS.VERIFY.safpb_verify_ACEE_ptr;

      if (SafCasOldAcee && memcmp(AceePtr, "ACEE", 4) == 0)
      {
         AceePtr -= 8;
         PBlock->REQUESTS.VERIFY.safpb_verify_ACEE_ptr = (void *)AceePtr;
      }
   }



   /* Clean up and return */
done:

   if (PBlock)
   {
      /* Set return code in parameter block */
      PBlock->RETCODES.DISCRETE.safpb_api_rc = Ret;

      /* Raise audit events depending on return value */
      if (Ret >= saf78_SAF_RC_FAILURE)
      {
         switch (PBlock->RETCODES.DISCRETE.safpb_mgr_return)
         {
            case saf78_RC_PWRD_INVALID:
               /* AUDITEVENTCALL Verify Deny - invalid password */
               SafRaiseAuditEvent
               (
                  AUDIT_EVENT_VERIFY_PWD_INVALID
                , AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY
                , 2
                , SafEventData
                  (
                    AUDIT_RECORD_DATA_TYPE_STRING
                   ,PBlock->REQUESTS.VERIFY.safpb_verify_USERID_ptr
                   ,PBlock->REQUESTS.VERIFY.safpb_verify_USERID_len
                  )
                , SafEventData
                  (
                    AUDIT_RECORD_DATA_TYPE_STRING
                   ,PBlock->REQUESTS.VERIFY.safpb_verify_group
                   ,sizeof(PBlock->REQUESTS.VERIFY.safpb_verify_group)
                  )
               );
               break;
              
            case saf78_RC_PWRD_EXPIRED:
               /* AUDITEVENTCALL Verify Deny - password expired */
               SafRaiseAuditEvent
               (
                  AUDIT_EVENT_VERIFY_PWD_EXPIRED
                , AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY
                , 2
                , SafEventData
                  (
                    AUDIT_RECORD_DATA_TYPE_STRING
                   ,PBlock->REQUESTS.VERIFY.safpb_verify_USERID_ptr
                   ,PBlock->REQUESTS.VERIFY.safpb_verify_USERID_len
                  )
                , SafEventData
                  (
                    AUDIT_RECORD_DATA_TYPE_STRING
                   ,PBlock->REQUESTS.VERIFY.safpb_verify_group
                   ,sizeof(PBlock->REQUESTS.VERIFY.safpb_verify_group)
                  )
               );
               break;

            case saf78_RC_PWRD_CHANGE_ERR:
               /* AUDITEVENTCALL Verify Deny - password change error */
               SafRaiseAuditEvent
               (
                  AUDIT_EVENT_VERIFY_PWD_CHANGE
                , AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY
                , 2
                , SafEventData
                  (
                     AUDIT_RECORD_DATA_TYPE_STRING
                   , PBlock->REQUESTS.VERIFY.safpb_verify_USERID_ptr
                   , PBlock->REQUESTS.VERIFY.safpb_verify_USERID_len
                  )
                , SafEventData
                  (
                     AUDIT_RECORD_DATA_TYPE_STRING
                   , PBlock->REQUESTS.VERIFY.safpb_verify_group
                   , sizeof(PBlock->REQUESTS.VERIFY.safpb_verify_group)
                  )
               );
               break;

            case saf78_RC_USER_NOT_IN_GROUP:
               /* AUDITEVENTCALL Verify Deny - user not in group */
               SafRaiseAuditEvent
               (
                  AUDIT_EVENT_VERIFY_USR_NOT_IN_GROUP
                , AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY
                , 2
                , SafEventData
                  (
                     AUDIT_RECORD_DATA_TYPE_STRING
                   , PBlock->REQUESTS.VERIFY.safpb_verify_USERID_ptr
                   , PBlock->REQUESTS.VERIFY.safpb_verify_USERID_len
                  )
                , SafEventData
                  (
                     AUDIT_RECORD_DATA_TYPE_STRING
                   , PBlock->REQUESTS.VERIFY.safpb_verify_group
                   , sizeof(PBlock->REQUESTS.VERIFY.safpb_verify_group)
                  )
               );
               break;
            case saf78_RC_NO_USER_PROFILE:
               /* AUDITEVENTCALL Verify denied for unknown*/
               SafRaiseAuditEvent
               (
                 AUDIT_EVENT_VERIFY_DENY_UNKNOWN
               , AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY
               , 2
               , SafEventData
                 (
                    AUDIT_RECORD_DATA_TYPE_STRING
                  , (void*)UserBuf
                  , (int)strlen(UserBuf)
                 )
               , SafEventData
                 (
                    AUDIT_RECORD_DATA_TYPE_STRING
                  , PBlock->REQUESTS.VERIFY.safpb_verify_group
                  , sizeof(PBlock->REQUESTS.VERIFY.safpb_verify_group)
                 )
               );
               break;
            default:
               /* AUDITEVENTCALL Verify Fail - unknown cause */
               SafRaiseAuditEvent
               (
                  AUDIT_EVENT_VERIFY_FAIL_UNKNOWN
                , AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY
                , 2
                , SafEventData
                  (
                     AUDIT_RECORD_DATA_TYPE_STRING
                   , PBlock->REQUESTS.VERIFY.safpb_verify_USERID_ptr
                   , PBlock->REQUESTS.VERIFY.safpb_verify_USERID_len
                  )
                , SafEventData
                  (
                     AUDIT_RECORD_DATA_TYPE_STRING
                   , PBlock->REQUESTS.VERIFY.safpb_verify_group
                   , sizeof(PBlock->REQUESTS.VERIFY.safpb_verify_group)
                  )
               );
            
         }
      }
      else if (Ret == saf78_SAF_RC_SUCCESS)
      {
         /* AUDITEVENTCALL Verify Success*/
         SafRaiseAuditEvent
         (
            AUDIT_EVENT_VERIFY_SUCCESS
          , AUDIT_EVENT_CATEGORY_SEC_API_RES_ALLOW
          , 2
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_STRING
             , PBlock->REQUESTS.VERIFY.safpb_verify_USERID_ptr
             , PBlock->REQUESTS.VERIFY.safpb_verify_USERID_len
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_STRING
             , PBlock->REQUESTS.VERIFY.safpb_verify_group
             , sizeof(PBlock->REQUESTS.VERIFY.safpb_verify_group)
            )
         );
      }
   }

   #if _DEBUG && SafLOG_ALL
      /* Log result */
      if (Ret) SafLog(2001, SafMsgINFO, "Verify failed for \"%s\"", UserBuf);
   #endif

   free(MUserBuf);
   return Ret;
}

int SafAuth(struct safpb_parameter_block *PBlock)
{
   int Ret;
   int Resolved = 0;
   mf_uns32 CurrEsm, EsmRet, NumCalled = 0;
   unsigned char *AceePtr;
   if (!PBlock)
     return 0;

   /***
   It's possible we'll get called with old-style ACEEs, which had 8 bytes
   of other data before the eye-catcher. Actually, this should never happen
   in current code (which is why it's not handled for new functions like
   Admin), but it was handled for backward compatibility while the
   transition was being made, so this code is still here.
   ***/

   AceePtr = (unsigned char *)PBlock->REQUESTS.AUTH.safpb_auth_ACEE_ptr;
   if (memcmp(AceePtr, SafACEE_NAME, 4) != 0) AceePtr += 8;

   /*AUDITEVENTCALL Check: Auth */
   SafRaiseAuditEvent
   (
     AUDIT_EVENT_CHECK_AUTH
   , AUDIT_EVENT_CATEGORY_SEC_API_REQ_CHECK
   , 3
   , SafEventData
     (
       AUDIT_RECORD_DATA_TYPE_STRING
     ,((SafACEE *)AceePtr)->User
     ,((SafACEE *)AceePtr)->UserLen
     )
   , SafEventData
     (
       AUDIT_RECORD_DATA_TYPE_STRING
      ,PBlock->REQUESTS.AUTH.safpb_auth_class
      ,sizeof(PBlock->REQUESTS.AUTH.safpb_auth_class)
     )
   , SafEventData
     (
       AUDIT_RECORD_DATA_TYPE_STRING
      ,PBlock->REQUESTS.AUTH.safpb_auth_ENTITY_ptr
      ,PBlock->REQUESTS.AUTH.safpb_auth_ENTITY_len
     )
   );
   

   /* Check state */
   if (SafState() != 1)
   {
      Ret = saf78_SAF_RC_FAILURE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
      goto done;
   }


   /* Make sure we have no pending shared update notices */
   HandlePendingUpdates(NULL);


   /* Call ESM Modules */
   PBlock->RETCODES.DISCRETE.safpb_api_rc     = saf78_SAF_RC_NOT_COMPLETE;
   PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
   PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;

   Ret = saf78_SAF_RC_NOT_COMPLETE;

   for (CurrEsm=0; CurrEsm < NumESMMods && !Resolved; CurrEsm++)
   {
      const char *ErrType = NULL;

      /* Set ESM index in parameter block */
      PBlock->safpb_safesm_index = (unsigned char) CurrEsm + 1;

      /* Call ESM Module */
      EsmRet = SafEsmCAuth(CurrEsm, PBlock);

      /* Handle non-zero return codes */
      switch (EsmRet)
      {

         case SafESMRC_OK:
            /* Did we get a definite response? */
            if (PBlock->RETCODES.DISCRETE.safpb_api_rc !=
                saf78_SAF_RC_NOT_COMPLETE)
            {
               Ret = PBlock->RETCODES.DISCRETE.safpb_api_rc;
               Resolved = 1;
            }

            /* Increment number of ESMs called successfully */
            NumCalled++;
            break;

         case SafESMRC_NOTIMPL:
            /* Not a definite response; keep trying */
            break;

         /* All other cases represent an ESM Module failure */
         case SafESMRC_PARAM:
            ErrType = "parameter error";
            break;
         case SafESMRC_RESOURCE:
            ErrType = "resource unavailable";
            break;
         case SafESMRC_EXTERNAL:
            ErrType = "ESM error";
            break;
         case SafESMRC_FAIL:
            ErrType = "miscellaneous failure";
            break;
         case SafESMRC_MGRFAIL:
            ErrType = "ESF Manager failure";
            break;
         default:
            ErrType = "unknown error";
            break;
      }

      /* Check for failure */
      if (ErrType)
      {
         mf_uns32 EsmNum = CurrEsm + 1;
         const char *EsmName = SafEsmName(CurrEsm);

         /* Log this */
         SafLog
         (
            111
          , SafMsgERR
          , "ESM Module %d (%s) returned error code %d (%s) from Auth"
          , EsmNum
          , EsmName
          , (int)EsmRet
          , ErrType
         );
          
         /* AUDITEVENTCALL Auth ESM Error*/
         SafRaiseAuditEvent
         (
            AUDIT_EVENT_AUTH_ESM_ERROR
          , AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR
          , 4
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_COMP5
             , &EsmNum
             , sizeof EsmNum
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_STRING
             , EsmName
             , (int)strlen(EsmName)
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_COMP5
             , &EsmRet
             , sizeof EsmRet
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_STRING
             , ErrType
             , (int)strlen(ErrType)
            )
         );

         /* Convert to failure result */
         Ret = saf78_SAF_RC_FAILURE;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
         Resolved = 1;
      }
   }


   /***
   Default based on configuration, though always allow if there are no
   enabled ESMs that implement Auth.
   ***/

   if (! Resolved)
   {
      /* Indicate decision made by SAF Manager */
      PBlock->safpb_safesm_index = 0;

      if (NumCalled == 0 || AllowUnknownResources)
      {
         Ret = saf78_SAF_RC_SUCCESS;

         /* Answer a permissions query with the highest possible level */
         if (PBlock->safpb_type == saf78_TYPE_ATTR_STATUS_ACC)
         {
            PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_ACCESS_INFO;
            PBlock->RETCODES.DISCRETE.safpb_mgr_reason = saf78_RS_ACCESS_ALTER;
         }
         else
         {
            /* Just a regular access check */
            PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
            PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;
         }
      }
      else
      {
         /* Is this a permissions query? */
         if (PBlock->safpb_type == saf78_TYPE_ATTR_STATUS_ACC)
         {
            Ret = saf78_SAF_RC_SUCCESS;
            PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_ACCESS_INFO;
            PBlock->RETCODES.DISCRETE.safpb_mgr_reason = saf78_RS_ACCESS_NONE;
         }
         else
         {
            Ret = saf78_SAF_RC_NOT_COMPLETE;
            PBlock->RETCODES.DISCRETE.safpb_mgr_return =
               saf78_RC_RESOURCE_NOT_PROT;
            PBlock->RETCODES.DISCRETE.safpb_mgr_reason =
               saf78_RS_NO_RESOURCE_PROF;
         }
      }
   }

   if (Ret)
   {
      char UserBuf[9], ClassBuf[9], ResourceBuf[32];
      SafACEE *Acee;
      unsigned char *AceePtr;
      size_t Len;

      AceePtr = (unsigned char *)PBlock->REQUESTS.AUTH.safpb_auth_ACEE_ptr;
      if (memcmp(AceePtr, SafACEE_NAME, 4) != 0) AceePtr += 8;
      Acee = (SafACEE *)AceePtr;
      memcpy(UserBuf, Acee->User, 8);
      UserBuf[Acee->UserLen] = '\0';

      memcpy(ClassBuf, PBlock->REQUESTS.AUTH.safpb_auth_class, 8);
      ClassBuf[8] = '\0';

      Len = PBlock->REQUESTS.AUTH.safpb_auth_ENTITY_len;
      if (Len > sizeof ResourceBuf - 1) Len = sizeof ResourceBuf - 1;
      memcpy(ResourceBuf, PBlock->REQUESTS.AUTH.safpb_auth_ENTITY_ptr, Len);
      ResourceBuf[Len] = '\0';

      /* AUDITEVENTCALL Auth Deny*/
      SafRaiseAuditEvent
      (
          AUDIT_EVENT_AUTH_DENY
        , AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY
        , 3
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_STRING
           , UserBuf
           , (int)strlen(UserBuf)
          )
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_STRING
           , ClassBuf
           , (int)strlen(ClassBuf)
          )
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_STRING
           , ResourceBuf
           , (int)strlen(ResourceBuf)
          )
      );

      #if _DEBUG && SafLOG_ALL
         SafLog
         (
            2003
          , SafMsgINFO
          , "Auth failed for user \"%s\", class \"%s\", entity \"%s\""
          , UserBuf
          , ClassBuf
          , ResourceBuf
         );
      #endif
   }

done:
   if (PBlock) PBlock->RETCODES.DISCRETE.safpb_api_rc = Ret;
   return Ret;
}



int SafXauth(struct safpb_parameter_block *PBlock)
{
   int Ret;
   int Resolved = 0;
   mf_uns32 CurrEsm, EsmRet, NumCalled = 0;

   unsigned char *AceePtr;
   if (!PBlock)
     return 0;

   AceePtr = (unsigned char *)PBlock->REQUESTS.AUTH.safpb_auth_ACEE_ptr;
   if (memcmp(AceePtr, SafACEE_NAME, 4) != 0) AceePtr += 8;

   /*AUDITEVENTCALL Check: XAuth */
   SafRaiseAuditEvent
   (
     AUDIT_EVENT_CHECK_XAUTH
   , AUDIT_EVENT_CATEGORY_SEC_API_REQ_CHECK
   , 3
   , SafEventData
     (
       AUDIT_RECORD_DATA_TYPE_STRING
     ,((SafACEE *)AceePtr)->User
     ,((SafACEE *)AceePtr)->UserLen
     )
   , SafEventData
     (
       AUDIT_RECORD_DATA_TYPE_STRING
      ,PBlock->REQUESTS.AUTH.safpb_auth_class
      ,sizeof(PBlock->REQUESTS.AUTH.safpb_auth_class)
     )
   , SafEventData
     (
       AUDIT_RECORD_DATA_TYPE_STRING
      ,PBlock->REQUESTS.AUTH.safpb_auth_ENTITY_ptr
      ,PBlock->REQUESTS.AUTH.safpb_auth_ENTITY_len
     )
   );

   /* Check state */
   if (SafState() != 1)
   {
      Ret = saf78_SAF_RC_FAILURE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
      goto done;
   }


   /* Make sure we have no pending shared update notices */
   HandlePendingUpdates(NULL);


   /* Call ESM Modules */
   PBlock->RETCODES.DISCRETE.safpb_api_rc     = saf78_SAF_RC_NOT_COMPLETE;
   PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
   PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;

   Ret = saf78_SAF_RC_NOT_COMPLETE;

   for (CurrEsm=0; CurrEsm < NumESMMods && !Resolved; CurrEsm++)
   {
      const char *ErrType = NULL;

      /* Set ESM index in parameter block */
      PBlock->safpb_safesm_index = (unsigned char) CurrEsm + 1;

      /* Call ESM Module */
      EsmRet = SafEsmCXAuth(CurrEsm, PBlock);

      /* Handle non-zero return codes */
      switch (EsmRet)
      {

         case SafESMRC_OK:
            /* Did we get a definite response? */
            if (PBlock->RETCODES.DISCRETE.safpb_api_rc !=
                saf78_SAF_RC_NOT_COMPLETE)
            {
               Ret = PBlock->RETCODES.DISCRETE.safpb_api_rc;
               Resolved = 1;
            }

            /* Increment number of ESMs called successfully */
            NumCalled++;
            break;

         case SafESMRC_NOTIMPL:
            /* Not a definite response; keep trying */
            break;

         /* All other cases represent an ESM Module failure */
         case SafESMRC_PARAM:
            ErrType = "parameter error";
            break;
         case SafESMRC_RESOURCE:
            ErrType = "resource unavailable";
            break;
         case SafESMRC_EXTERNAL:
            ErrType = "ESM error";
            break;
         case SafESMRC_FAIL:
            ErrType = "miscellaneous failure";
            break;
         case SafESMRC_MGRFAIL:
            ErrType = "ESF Manager failure";
            break;
         default:
            ErrType = "unknown error";
            break;
      }

      /* Check for failure */
      if (ErrType)
      {
         mf_uns32 EsmNum = CurrEsm + 1;
         const char *EsmName = SafEsmName(CurrEsm);

         /* Log this */
         SafLog
         (
            112
          , SafMsgERR
          , "ESM Module %d (%s) returned error code %d (%s) from XAuth"
          , EsmNum
          , EsmName
          , (int)EsmRet
          , ErrType
         );

         /* AUDITEVENTCALL XAuth ESM Error*/
         SafRaiseAuditEvent
         (
            AUDIT_EVENT_XAUTH_ESM_ERROR
          , AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR
          , 4
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_COMP5
             , &EsmNum
             , sizeof EsmNum
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_STRING
             , EsmName
             , (int)strlen(EsmName)
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_COMP5
             , &EsmRet
             , sizeof EsmRet
            )
          , SafEventData
            (
               AUDIT_RECORD_DATA_TYPE_STRING
             , ErrType
             , (int)strlen(ErrType)
            )
         );

         /* Convert to failure result */
         Ret = saf78_SAF_RC_FAILURE;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return =
            saf78_RC_DATABASE_ERROR;
         Resolved = 1;
      }
   }


   /***
   Default based on configuration, though always allow if there are no
   enabled ESMs that implement Auth.
   ***/

   if (! Resolved)
   {
      /* Indicate decision made by SAF Manager */
      PBlock->safpb_safesm_index = 0;

      if (NumCalled == 0 || AllowUnknownResources)
      {
         Ret = saf78_SAF_RC_SUCCESS;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
         PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;

         if (PBlock->safpb_type == saf78_TYPE_ATTR_STATUS_ACC)
         {
            PBlock->REQUESTS.XAUTH.safpb_xauth_PERMISSIONS =
               saf78_PERM_READ
             | saf78_PERM_UPDATE
             | saf78_PERM_EXECUTE
             | saf78_PERM_CONTROL
             | saf78_PERM_ALTER;
         }
      }
      else
      {
         /* Is this a permissions query? */
         if (PBlock->safpb_type == saf78_TYPE_ATTR_STATUS_ACC)
         {
            Ret = saf78_SAF_RC_SUCCESS;
            PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
            PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;
            PBlock->REQUESTS.XAUTH.safpb_xauth_PERMISSIONS = 0;
         }
         else
         {
            Ret = saf78_SAF_RC_NOT_COMPLETE;
            PBlock->RETCODES.DISCRETE.safpb_mgr_return =
               saf78_RC_RESOURCE_NOT_PROT;
            PBlock->RETCODES.DISCRETE.safpb_mgr_reason =
               saf78_RS_NO_RESOURCE_PROF;
         }
      }
   }

   if (Ret)
   {
      char UserBuf[9], ClassBuf[40], ResourceBuf[40];
      SafACEE *Acee;
      unsigned char *AceePtr;
      size_t Len;

      AceePtr = (unsigned char *)PBlock->REQUESTS.XAUTH.safpb_xauth_ACEE_ptr;
      if (memcmp(AceePtr, SafACEE_NAME, 4) != 0) AceePtr += 8;
      Acee = (SafACEE *)AceePtr;
      memcpy(UserBuf, Acee->User, 8);
      UserBuf[Acee->UserLen] = '\0';

      Len = PBlock->REQUESTS.XAUTH.safpb_xauth_CLASS_len;
      if (Len > sizeof ClassBuf - 1) Len = sizeof ClassBuf - 1;
      memcpy(ClassBuf, PBlock->REQUESTS.XAUTH.safpb_xauth_CLASS_ptr, Len);
      ClassBuf[Len] = '\0';

      Len = PBlock->REQUESTS.XAUTH.safpb_xauth_ENTITY_len;
      if (Len > sizeof ResourceBuf - 1) Len = sizeof ResourceBuf - 1;
      memcpy(ResourceBuf, PBlock->REQUESTS.XAUTH.safpb_xauth_ENTITY_ptr, Len);
      ResourceBuf[Len] = '\0';

      #if _DEBUG && SafLOG_ALL
         SafLog
         (
            2003
          , SafMsgINFO
          , "XAuth failed for user \"%s\", class \"%s\", entity \"%s\""
          , UserBuf
          , ClassBuf
          , ResourceBuf
         );
      #endif

      /* AUDITEVENTCALL XAuth Deny*/
      SafRaiseAuditEvent
      (
          AUDIT_EVENT_XAUTH_DENY
        , AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY
        , 3
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_STRING
           , UserBuf
           , (int)strlen(UserBuf)
          )
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_STRING
           , ClassBuf
           , (int)strlen(ClassBuf)
          )
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_STRING
           , ResourceBuf
           , (int)strlen(ResourceBuf)
          )
      );

   }

done:
   if (PBlock) PBlock->RETCODES.DISCRETE.safpb_api_rc = Ret;
   return Ret;
}



int SafStat(struct safpb_parameter_block *PBlock)
{
   int Ret = saf78_SAF_RC_NOT_COMPLETE;

   if (PBlock) PBlock->RETCODES.DISCRETE.safpb_api_rc = Ret;
   return Ret;
}



int SafAudit(struct safpb_parameter_block *PBlock)
{
   int Ret = saf78_SAF_RC_NOT_COMPLETE;

   if (PBlock) PBlock->RETCODES.DISCRETE.safpb_api_rc = Ret;
   return Ret;
}




int SafAdmin(struct safpb_parameter_block *PBlock)
{
   int Ret;
   mf_uns32 CurrEsm, EsmRet;
   const char *ErrType = NULL;
   int ReqType = -1, IsList = 0;
   SafACEE *AceePtr = NULL;
   const char *CmdName = "invalid";
   int CmdLen;


   if (!PBlock)
      return 0;

   /* Extract info for messages and audit events */
   AceePtr = PBlock->REQUESTS.ADMIN.safpb_admin_ACEE_ptr;

   if (PBlock->safpb_type > 0 &&
       PBlock->safpb_type < sizeof sSafCommands / sizeof *sSafCommands)
   {
      CmdName = sSafCommands[PBlock->safpb_type-1].safadmin_cmdname;
      CmdLen  = sSafCommands[PBlock->safpb_type-1].safadmin_cmdlen;
   }
   else
   {
      CmdLen = (int)strlen(CmdName);
   }

   /* Check state */
   if (SafState() != 1)
   {
      Ret = saf78_SAF_RC_FAILURE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
      goto done;
   }

   /* Determine request type */
   switch (PBlock->safpb_type)
   {
      case saf78_TYPE_ADMIN_LISTUSER:
      case saf78_TYPE_ADMIN_LISTGROUP:
      case saf78_TYPE_ADMIN_LISTRES:
      case saf78_TYPE_ADMIN_LISTCLASS:
         ReqType = AUDIT_EVENT_ADMIN_LIST;
         IsList = 1;
         break;
      case saf78_TYPE_ADMIN_ADDUSER:
      case saf78_TYPE_ADMIN_ADDGROUP:
      case saf78_TYPE_ADMIN_ADDRES:
      case saf78_TYPE_ADMIN_ADDCLASS:
         ReqType = AUDIT_EVENT_ADMIN_ADD;
         break;
      case saf78_TYPE_ADMIN_DELUSER:
      case saf78_TYPE_ADMIN_DELGROUP:
      case saf78_TYPE_ADMIN_DELRES:
      case saf78_TYPE_ADMIN_DELCLASS:
         ReqType = AUDIT_EVENT_ADMIN_DELETE;
         break;
      case saf78_TYPE_ADMIN_ALTUSER:
      case saf78_TYPE_ADMIN_ALTGROUP:
      case saf78_TYPE_ADMIN_ALTRES:
      case saf78_TYPE_ADMIN_ALTCLASS:
         ReqType = AUDIT_EVENT_ADMIN_ALTER;
         break;
      case saf78_TYPE_ADMIN_SETPSWD:
         ReqType = AUDIT_EVENT_ADMIN_SETPWD;
         break;
      case saf78_TYPE_ADMIN_SETOPTS:
         ReqType = AUDIT_EVENT_ADMIN_SETOPT;
         break;
   }

   if (PBlock->safpb_type == saf78_TYPE_ADMIN_FREELIST) IsList = 1;

   /* AUDITEVENTCALL Define */
   if (ReqType >= 0) 
   {
      Ret = AuditAdminReq(PBlock, ReqType, AceePtr, CmdName, CmdLen);

      if (Ret)
      {
         /* TODO: log this */
         goto done;
      }
   }

   /***
   Check ACEE. We don't allow an admin request using an ACEE that was
   allocated with no-password-required, unless it's a LIST request and
   the [Admin] / allow-list option was specified (RPI 548616). (This
   can also be set using the ES_ESF_ALLOW_LIST environment variable, 
   but that's undocumented and used only by Testing.)
   ***/

   if (AceePtr && (AceePtr->Flag3 & SafACEE_F3_NPWR))
   {
      static int AllowList = -1;
      char *ALVal = NULL;

      if (AllowList < 0)
      {
         /***
         No need to serialize this - the persistent assignment is atomic
         and all threads would compute the same value.
         ***/

         SafQueryCfg("Admin", "allow-list", &ALVal);
         AllowList = (ALVal && tolower((unsigned char)*ALVal) == 'y');
      }

      /***
      Error if this is a non-list request, or if anonymous list requests
      are not allowed.
      ***/

      if (!IsList || !AllowList)
      {
         SafLog
         (
            106
          , SafMsgERR
          , "Admin request denied for unauthenticated user"
         );
         Ret = saf78_SAF_RC_FAILURE;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DENIED;
         goto done;
      }
   }

   /***
   For LISTx requests, we need to allocate the array of response lists
   in the request control block.
   ***/

   if (ReqType == AUDIT_EVENT_ADMIN_LIST)
   {
      PBlock->REQUESTS.ADMIN.safpb_admin_LIST_ptr = malloc
      (
         SafESM_MAX * sizeof *PBlock->REQUESTS.ADMIN.safpb_admin_LIST_ptr
      );

      if (! PBlock->REQUESTS.ADMIN.safpb_admin_LIST_ptr)
      {
         Ret = saf78_SAF_RC_FAILURE;
         PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
         goto done;
      }
   }


   /* Make sure we have no pending shared update notices */
   HandlePendingUpdates(NULL);


   /* Was a specific module requested? */
   if (PBlock->safpb_safesm_index)
   {
      /***
      Set CurrEsm for error-reporting purposes.  Note that it's set to
      the ESM's index plus one (ie the value of safpb_safesm_index), to
      simulate what would happen if we exited the for-loop below with an
      error.
      ***/

      CurrEsm = PBlock->safpb_safesm_index;

      /* Call ESM Module */
      EsmRet = SafEsmCAdmin(PBlock->safpb_safesm_index - 1, PBlock);
      if (! EsmRet)
         Ret = PBlock->RETCODES.DISCRETE.safpb_api_rc;
   }

   else
   {
      /* Call all enabled ESM Modules */
      PBlock->RETCODES.DISCRETE.safpb_api_rc     = saf78_SAF_RC_NOT_COMPLETE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
      PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;

      Ret = saf78_SAF_RC_NOT_COMPLETE;

      for (CurrEsm=0, EsmRet = 0;
           CurrEsm < NumESMMods && Ret <= saf78_SAF_RC_NOT_COMPLETE && !EsmRet;
           CurrEsm++)
      {

         /* Set ESM index in parameter block */
         PBlock->safpb_safesm_index = (unsigned char) CurrEsm + 1;

         /* Call ESM Module */
         EsmRet = SafEsmCAdmin(CurrEsm, PBlock);

         /* Handle non-zero return codes */
         switch (EsmRet)
         {

            case SafESMRC_OK:
               /* Check for failure response */
               Ret = PBlock->RETCODES.DISCRETE.safpb_api_rc;
               break;

            case SafESMRC_NOTIMPL:
               /* Not a definite response; keep trying */
               EsmRet = 0;
               break;

            /* All other cases represent an ESM Module failure */
            default:
               break;
         }
      }
   }

   /* Check for ESM Module failure */
   if (EsmRet > SafESMRC_NOTIMPL) ErrType = EsmrcToString(EsmRet);
   if (ErrType)
   {
      /* Log this */
      SafLog
      (
         113
       , SafMsgERR
       , "ESM Module %d (%s) returned error code %d (%s) from Admin"
       , CurrEsm
       , SafEsmName(CurrEsm-1)
       , (int)EsmRet
       , ErrType
      );

      /* Convert to failure result */
      Ret = saf78_SAF_RC_FAILURE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return =
         saf78_RC_DATABASE_ERROR;
   }

done:
   /* Log / audit request failure */
   if (Ret && PBlock)
   {
      SafLog
      (
         103
       , SafMsgWARN
       , "Admin %.*s request failed: %d"
       , CmdLen
       , CmdName
       , (int) Ret
      );

      /* Audit Admin failure */
      if (AceePtr) SafRaiseAuditEvent
      (
        AUDIT_EVENT_ADMIN_ESM_ERROR
      , AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR
      , 3
      , SafEventData
        (
          AUDIT_RECORD_DATA_TYPE_STRING
        , CmdName
        , CmdLen
        )
      , SafEventData
        (
          AUDIT_RECORD_DATA_TYPE_COMP5
        , & PBlock->safpb_type
        , sizeof PBlock->safpb_type
        )
      , SafEventData
        (
          AUDIT_RECORD_DATA_TYPE_STRING
        , AceePtr->User
        , AceePtr->UserLen
        )
      );
   }

   if (! Ret)
   {
      /* Audit Admin success */
      if (AceePtr) SafRaiseAuditEvent
      (
        AUDIT_EVENT_ADMIN_SUCCESS
      , AUDIT_EVENT_CATEGORY_SEC_API_RES_SUCCESS
      , 3
      , SafEventData
        (
          AUDIT_RECORD_DATA_TYPE_STRING
        , CmdName
        , CmdLen
        )
      , SafEventData
        (
          AUDIT_RECORD_DATA_TYPE_COMP5
        , & PBlock->safpb_type
        , sizeof PBlock->safpb_type
        )
      , SafEventData
        (
          AUDIT_RECORD_DATA_TYPE_STRING
        , AceePtr->User
        , AceePtr->UserLen
        )
      );
   }

   if (PBlock) PBlock->RETCODES.DISCRETE.safpb_api_rc = Ret;
   return Ret;
}


/***
Helper for auditing admin requests: add an audit parameter.
***/

static SafRet AddAuditParam(struct TEventData *AuditParams[],
                            unsigned *IdxPtr,
                            int Type, const void *Data, int Length)
{
   AuditParams[*IdxPtr] = malloc(sizeof **AuditParams);
   if (! AuditParams[*IdxPtr]) return SafR_RESOURCE;

   AuditParams[*IdxPtr]->data     = Data;
   AuditParams[*IdxPtr]->datalen  = Length;
   AuditParams[*IdxPtr]->datatype = Type;

   *IdxPtr += 1;

   return SafR_OK;
}


/***
Helper for auditing admin requests: raises an audit event for the admin
request, including all the parameters - except password, if it's supplied.
***/

static SafRet AuditAdminReq(struct safpb_parameter_block *PBlock,
                            int ReqType, SafACEE *AceePtr,
                            const char *CmdName, int CmdLen)
{
   SafRet Ret = SafR_OK;
   struct TEventData **AuditParams = NULL;
   unsigned ParamIdx = 0, KVIdx = 0, TmpIdx;
   char **KeyValArray = NULL;

   /***
   Allocate audit parameter pointer array: entries for command name, command
   code, and username, plus one for each parameter.  Allocate array of
   key=val strings, which has one entry for each admin parameter.
   ***/

   AuditParams = malloc
   (
      sizeof *AuditParams
      * (3 + PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_count)
   );
   if (! AuditParams)
   {
      Ret = SafR_RESOURCE;
      goto done;
   }

   KeyValArray = malloc
   (
      sizeof *KeyValArray * PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_count
   );
   if (! KeyValArray)
   {
      Ret = SafR_RESOURCE;
      goto done;
   }


   /* Create the fixed parameters */
   Ret = AddAuditParam
   (
      AuditParams
    , &ParamIdx 
    , AUDIT_RECORD_DATA_TYPE_STRING
    , CmdName
    , CmdLen
   );
   if (Ret) goto done;


   Ret = AddAuditParam
   (
      AuditParams
    , &ParamIdx 
    , AUDIT_RECORD_DATA_TYPE_COMP5
    , & PBlock->safpb_type
    , sizeof PBlock->safpb_type
   );
   if (Ret) goto done;


   Ret = AddAuditParam
   (
      AuditParams
    , &ParamIdx 
    , AUDIT_RECORD_DATA_TYPE_STRING
    , AceePtr? AceePtr->User : "(anonymous)"
    , AceePtr? AceePtr->UserLen : 11
   );
   if (Ret) goto done;


   /* Create the parameters for the admin parameters */
   for (KVIdx = 0;
        KVIdx < PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_count;
        KVIdx++)
   {
      size_t KVStrLen;
      char *KVPtr;

      /* Allocate buffer for key=value string */
      KVStrLen =
         PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_ptr[KVIdx].KeyLen
       + 1
       + PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_ptr[KVIdx].ValLen;
      KeyValArray[KVIdx] = malloc(KVStrLen);
      if (! KeyValArray[KVIdx])
      {
         Ret = SafR_RESOURCE;
         goto done;
      }

      /* Create string */
      KVPtr = KeyValArray[KVIdx];
      memcpy
      (
         KVPtr
       , PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_ptr[KVIdx].KeyPtr
       , PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_ptr[KVIdx].KeyLen
      );
      KVPtr += PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_ptr[KVIdx].KeyLen;
      *KVPtr++ = '=';

      /* Special handling for PASSWORD */
      if (SafSTRCMP_CIN(KeyValArray[KVIdx], ==, "PASSWORD=", 9))
      {
         memset
         (
            KVPtr
          , '*'
          , PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_ptr[KVIdx].ValLen
         );
      }
      else
      {
         memcpy
         (
            KVPtr
          , PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_ptr[KVIdx].ValPtr
          , PBlock->REQUESTS.ADMIN.safpb_admin_ARGTBL_ptr[KVIdx].ValLen
         );
      }

      /* Add audit parameter */
      Ret = AddAuditParam
      (
         AuditParams
       , &ParamIdx
       , AUDIT_RECORD_DATA_TYPE_STRING
       , KeyValArray[KVIdx]
       , (int)KVStrLen
      );
      if (Ret) goto done;
   }

   /* Raise the event */
   Ret = SafRaiseAuditEventA
   (
      ReqType
    , AUDIT_EVENT_CATEGORY_SEC_API_REQ_DEFINE
    , ParamIdx
    , AuditParams
   );

   /* Clean up */
done:
   if (AuditParams)
   {
      for (TmpIdx = 0; TmpIdx < ParamIdx; TmpIdx++)
         free(AuditParams[TmpIdx]);
      free(AuditParams);
   }

   if (KeyValArray)
   {
      for (TmpIdx = 0; TmpIdx < KVIdx; TmpIdx++)
         free(KeyValArray[TmpIdx]);
      free(KeyValArray);
   }

   return Ret;
}


/***
Translate an "other" ESM return code to a string. Note these return codes
apply to eg Admin and Update, but not to eg Verify and Auth; see the ESM
Module Interface documentation for more information.
***/

static const char *EsmrcToString(mf_uns32 EsmRet)
{
   switch (EsmRet)
   {
      case SafESMRC_OK:          return "no error";
      case SafESMRC_NOTIMPL:     return "function not implemented";
      case SafESMRC_PARAM:       return "parameter error";
      case SafESMRC_RESOURCE:    return "resource unavailable";
      case SafESMRC_EXTERNAL:    return "ESM error";
      case SafESMRC_FAIL:        return "miscellaneous failure";
      case SafESMRC_MGRFAIL:     return "ESF Manager failure";
      default:                   return "unknown error";
   }
}



/* The private update sequence number for this process */
static mf_uns32 UpdateSequenceNumber;



int SafUpdate(struct safpb_parameter_block *PBlock)
{
   int Ret = saf78_SAF_RC_NOT_COMPLETE;
   int Locked = 0;
   struct UpdateCache *Cache = NULL;
   struct safpb_update *Update;
   mf_uns32 CurrEsm, EsmRet = 0;
   const char *ErrType = NULL;
   SafACEE *Acee;

   /* Sanity check */
   if (! PBlock) goto done;

   /* Check state */
   if (SafState() != 1)
   {
      Ret = saf78_SAF_RC_FAILURE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
      goto done;
   }

   /* Address parts of the request for convenience */
   Acee = PBlock->REQUESTS.UPDATE.safpb_update_ACEE_ptr;
   Update = &PBlock->REQUESTS.UPDATE;

   /* Is this is a multiprocess shared-memory environment? */
   Locked = LockUpdateArea();
   if (Locked)
   {
      size_t Len;

      /* Get the update cache area */
      Cache = GetUpdateCache();
      if (! Cache) goto done;

      /***
      Check for pending requests that we haven't processed, by comparing
      our last-update-processed sequence number with the sequence number
      of the current saved update:

      - If they're the same, we already processed the saved update.
      Continue with the request we were called with.

      - If they're different by one, we have not processed the saved
      update yet. Do so, then continue with this request.

      - If they're different by more than one, we missed at least one
      update. Flush everything, then continue with this request.
      ***/

      HandlePendingUpdates(Cache);

      /* Save this update request for other processes */
      Cache->PBlock = *PBlock;
      Cache->ACEE = *Acee;
      Cache->PBlock.REQUESTS.UPDATE.safpb_update_ACEE_ptr = &Cache->ACEE;
      if (Update->safpb_update_ENTITY_len > SafCACHE_MAX_ENTITY_LEN)
         Len = SafCACHE_MAX_ENTITY_LEN;
      else
         Len = Update->safpb_update_ENTITY_len;
      memcpy(Cache->Entity, Update->safpb_update_ENTITY_ptr, Len);
      Cache->PBlock.REQUESTS.UPDATE.safpb_update_ENTITY_len = Len;

      /* Update the global update-history sequence number */
      Cache->Sequence++;
   }


   /* TODO: Once caching is implemented, clear relevant cached data */

   /* Tell ESM module(s) to clear cached data */

   /* Was a specific module requested? */
   if (PBlock->safpb_safesm_index)
   {
      /***
      Set CurrEsm for error-reporting purposes.  Note that it's set to
      the ESM's index plus one (ie the value of safpb_safesm_index), to
      simulate what would happen if we exited the for-loop below with an
      error.
      ***/

      CurrEsm = PBlock->safpb_safesm_index;

      /* Call ESM Module */
      EsmRet = SafEsmCUpdate
      (
         SafESM_UPDATE
       , PBlock->safpb_safesm_index - 1
       , PBlock
      );

      if (! EsmRet) Ret = PBlock->RETCODES.DISCRETE.safpb_api_rc;
   }
   else
   {
      /* Call all enabled ESM Modules */
      PBlock->RETCODES.DISCRETE.safpb_api_rc     = saf78_SAF_RC_NOT_COMPLETE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = 0;
      PBlock->RETCODES.DISCRETE.safpb_mgr_reason = 0;

      Ret = 0;

      for (CurrEsm=0, EsmRet = 0;
           CurrEsm < NumESMMods && Ret <= saf78_SAF_RC_NOT_COMPLETE && !EsmRet;
           CurrEsm++)
      {
         /* Set ESM index in parameter block */
         PBlock->safpb_safesm_index = (unsigned char) CurrEsm + 1;

         /* Call ESM Module */
         EsmRet = SafEsmCUpdate(SafESM_UPDATE, CurrEsm, PBlock);

         /* Handle non-zero return codes */
         switch (EsmRet)
         {
            case SafESMRC_OK:
               /* Check for failure response */
               Ret = PBlock->RETCODES.DISCRETE.safpb_api_rc;
               break;
            case SafESMRC_NOTIMPL:
               /* Allowed */
               EsmRet = 0;
               break;
            /* All other cases represent an ESM Module failure */
            default:
               break;
         }
      }
   }

   /* A "not-complete" return code is not an error here */
   if (Ret == saf78_SAF_RC_NOT_COMPLETE) Ret = 0;

   /* If successful, update private history sequence number */
   if (! Ret && Cache) UpdateSequenceNumber = Cache->Sequence;


   /* Clean up and return */
done:

   /* Check for ESM Module failure */
   if (EsmRet > SafESMRC_NOTIMPL) ErrType = EsmrcToString(EsmRet);
   if (ErrType)
   {
      /* Log this */
      SafLog
      (
         114
       , SafMsgERR
       , "ESM Module %d (%s) returned error code %d (%s) from Update"
       , CurrEsm
       , SafEsmName(CurrEsm-1)
       , (int)EsmRet
       , ErrType
      );

      /* Convert to failure result */
      Ret = saf78_SAF_RC_FAILURE;
      PBlock->RETCODES.DISCRETE.safpb_mgr_return = saf78_RC_DATABASE_ERROR;
   }

   /* Unlock if necessary */
   if (Locked) UnlockUpdateArea();

   /* Logging and auditing */
   if (PBlock)
   {
      char UserBuf[9], ResourceBuf[40];
      size_t Len;
      int Category, Event;

      /* Set return code in parameter block */
      PBlock->RETCODES.DISCRETE.safpb_api_rc = Ret;

      /* Audit */
      memcpy(UserBuf, Acee->User, 8);
      UserBuf[Acee->UserLen] = '\0';

      Len = PBlock->REQUESTS.UPDATE.safpb_update_ENTITY_len;
      if (Len > sizeof ResourceBuf - 1) Len = sizeof ResourceBuf - 1;
      memcpy(ResourceBuf, PBlock->REQUESTS.UPDATE.safpb_update_ENTITY_ptr, Len);
      ResourceBuf[Len] = '\0';

      if (Ret)
      {
         Category = AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR;
         Event = AUDIT_EVENT_UPDATE_ESM_ERROR;

         /* Log the failure */
         SafLog
         (
            104
          , SafMsgWARN
          , "Update (%s) request failed: %d"
          , UpdateTypeToString(PBlock->safpb_type)
          , (int) Ret
         );
      }
      else
      {
         Category = AUDIT_EVENT_CATEGORY_SEC_API_RES_SUCCESS;
         Event = AUDIT_EVENT_UPDATE_SUCCESS;
      }

      SafRaiseAuditEvent
      (
          Event
        , Category
        , 4
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_STRING
           , UserBuf
           , (int)strlen(UserBuf)
          )
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_COMP5
           , &PBlock->safpb_safesm_index
           , (int)sizeof PBlock->safpb_safesm_index
          )
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_COMP5
           , &PBlock->REQUESTS.UPDATE.safpb_update_ACTION
           , (int)sizeof PBlock->REQUESTS.UPDATE.safpb_update_ACTION
          )
        , SafEventData
          (
             AUDIT_RECORD_DATA_TYPE_STRING
           , ResourceBuf
           , (int)strlen(ResourceBuf)
          )
      );
   }

   #if _DEBUG && SafLOG_ALL
      /* Log result */
      if (Ret) SafLog(2005, SafMsgINFO, "Update failed");
   #endif

   return Ret;
}



/***
Handle pending updates in a shared-memory environment.
In non-shared-memory environments, this function is a no-op.

Check for pending requests by comparing our last-update-processed
sequence number with the sequence number of the current saved update:

   - If they're the same, we already processed the saved update.

   - If they're different by one, we have not processed the saved
   update yet. Do so.

   - If they're different by more than one, we missed at least one
   update. Flush everything.

The input parameter UpdateCache can be null, for the normal behavior, or
a pointer to the shared update area if the caller has already addressed the
update area. In that case, the function assumes the caller has also already
acquired the global update-area lock.

Returns a SafRet error code.
***/

static SafRet HandlePendingUpdates(struct UpdateCache *Cache)
{
   SafRet Ret = SafR_OK;
   mf_uns32 PendingUpdates;
   int CallerLocked = (Cache != NULL);
   mf_uns32 CurrEsm, EsmRet = 0, MaxEsmRet = 0;
   const char *ErrType = NULL;

   /* We need the cache */
   if (! Cache)
   {
      if (LockUpdateArea()) Cache = GetUpdateCache();
      if (! Cache) goto done;
   }

   /* See if we have pending updates */
   PendingUpdates = CheckForPendingSharedUpdate(Cache);

   if (PendingUpdates == 1)
   {
      /* TODO: When caching is implemented, need to update local cache */

      /* Notify appropriate ESM Module(s) */
      if (Cache->PBlock.safpb_safesm_index)
      {
         EsmRet = SafEsmCUpdate
         (
            SafESM_UPDATED
          , Cache->PBlock.safpb_safesm_index - 1
          , & Cache->PBlock
         );
         if (! EsmRet) Ret = Cache->PBlock.RETCODES.DISCRETE.safpb_api_rc;
      }
      else
      {
         Cache->PBlock.RETCODES.DISCRETE.safpb_api_rc     = 0;

         for (CurrEsm=0, EsmRet = 0; CurrEsm < NumESMMods; CurrEsm++)
         {
            Cache->PBlock.safpb_safesm_index = (unsigned char) CurrEsm + 1;
            EsmRet = SafEsmCUpdate(SafESM_UPDATED, CurrEsm, &Cache->PBlock);
            switch (EsmRet)
            {
               case SafESMRC_OK:
                  /* Convert failure response to EsmRet code for logging */
                  if (Cache->PBlock.RETCODES.DISCRETE.safpb_api_rc >
                      saf78_SAF_RC_NOT_COMPLETE)
                     EsmRet = SafESMRC_FAIL;
                  break;
               case SafESMRC_NOTIMPL:
                  /* Allowed */
                  EsmRet = 0;
                  break;
               /* All other cases represent an ESM Module failure */
               default:
                  break;
            }
            if (EsmRet > MaxEsmRet) MaxEsmRet = EsmRet;
         }

         EsmRet = MaxEsmRet;
      }
   }

   else if (PendingUpdates > 1)
   {
      /* TODO: When caching is implemented, need to flush local cache */

      /* Flush all ESMs */
      for (CurrEsm=0, EsmRet = 0; CurrEsm < NumESMMods; CurrEsm++)
      {
         EsmRet = SafEsmCUpdate(SafESM_REFRESH, CurrEsm, NULL);
         if (EsmRet == SafESMRC_NOTIMPL) EsmRet = 0;
         if (EsmRet > MaxEsmRet) MaxEsmRet = EsmRet;
      }

      EsmRet = MaxEsmRet;
   }

   /* Log any error */
   if (EsmRet > 0)
   {
      ErrType = EsmrcToString(EsmRet);
      SafLog
      (
         105
       , SafMsgWARN
       , "ESM Module %d (%s) returned error code %d (%s) from Update"
         " (%s)"
       , CurrEsm
       , SafEsmName(CurrEsm-1)
       , (int)EsmRet
       , ErrType
       , PendingUpdates == 1? "single update" : "refresh all"
      );

      /* Set Ret based on EsmRet */
      switch (EsmRet)
      {
         case SafESMRC_PARAM:    Ret = SafR_PARAM;    break;
         case SafESMRC_RESOURCE: Ret = SafR_RESOURCE; break;
         case SafESMRC_EXTERNAL: Ret = SafR_EXFAIL;   break;
         case SafESMRC_MGRFAIL:  Ret = SafR_INTERNAL; break;
         case SafESMRC_FAIL:     Ret = SafR_ESM;      break;
         default:                Ret = SafR_ESM;      break;
      }
   }

   /* Update the private update-history sequence number */
   UpdateSequenceNumber = Cache->Sequence;

done:
   /* Unlock shared area if the caller didn't do the locking for us */
   if (! CallerLocked) UnlockUpdateArea();
   return Ret;
}


/***
Helper functions to acquire and release the global locks for the shared
update cache area. These are stubs in non-shared-memory environments.

They return 1 if the action actually took place, 0 if locking is unnecessary.
***/

static int LockUpdateArea(void)
{
   if (SafIsSharedMemory())
   {
      SafLockEnq
      (
         "#ESFMgr"
       , "AdminUpd"
       , SafESM_LCK_NONE
       , 1
       , SafESM_LCK_PROC
      );
      return 1;
   }

   return 0;
}

static int UnlockUpdateArea(void)
{
   if (SafIsSharedMemory())
   {
      SafLockDeq("#ESFMgr", "AdminUpd");
      return 1;
   }

   return 0;
}


/***
Helper to get (or allocate, if this is the first update request) the shared
update cache area.

We need to allocate an area big enough for PBlock, plus the indirect
separately-allocated data (eg entity name, ACEE), plus the cache header.
The entity name length can vary. We impose a maximum length to avoid
having to reallocate the update cache area; if we get a request that
exceeds that length, we truncate the entity name in the cache. (We could
force other processes to flush all their private cached data in this case
by incrementing the sequence number by two, but frankly I'm not very
worried about this case. If people create unreasonable security data, they
get suboptimal behavior.)
***/

static struct UpdateCache *GetUpdateCache(void)
{
   struct UpdateCache *Cache = NULL;
   SafRet Ret;
   size_t CacheSize;

   CacheSize = sizeof *Cache;
   Ret = SafShmOpen("#SafCache", &CacheSize, (void **)&Cache);
   if (Ret || !Cache || CacheSize != sizeof *Cache)
   {
      /* TODO: Log this. */
      Cache = NULL;
   }

   return Cache;
}



/***
Helper function to check to see if there's a pending administrative update
in shared memory. In non-shared-memory environments, this function always
returns false.

The input parameter UpdateCache can be null, for the normal behavior, or
a pointer to the shared update area if the caller has already addressed the
update area. In that case, the function assumes the caller has also already
acquired the global update-area lock.

Possible return values are 0 (no shared update pending), 1 (an update is
present and needs to be processed), and >1 (multiple updates were missed,
and all cached data needs to be flushed). If the return code is nonzero,
this function will leave the global update-area lock aquired, and the caller
must at least release that lock.
***/

static mf_uns32 CheckForPendingSharedUpdate(struct UpdateCache *Cache)
{
   mf_uns32 Result = 0;
   int Locked = 0;

   /* If caller didn't get shared area and lock, do that */
   if (! Cache)
   {
      Locked = LockUpdateArea();

      /* Only need to look for shared area if lock succeeded */
      if (Locked) Cache = GetUpdateCache();
   }

   /* If we have an update cache area, check it */
   if (Cache)
   {
      /* Check the global update sequence number against ours */
      Result = Cache->Sequence - UpdateSequenceNumber;

      /* Update our sequence number so we know what we've seen */
      UpdateSequenceNumber = Cache->Sequence;
   }

   /* If we're up to date, and we locked the area, release the lock */
   if (! Result && Locked) UnlockUpdateArea();

   /* Let caller know result */
   return Result;
}


/***
Translate update types to strings.
***/

static const char *UpdateTypeToString(unsigned char Type)
{
   static const char *Types[] =
   {
      "all"
    , "user"
    , "group"
    , "resource"
    , "users"
    , "groups"
    , "resources"
   };

   if (Type < sizeof Types / sizeof *Types)
      return Types[Type];
   else
      return "unknown";
}



/* end of source module saf-process.c */