ESF ESM Module Interface

ESF ESM Modules implement this interface. It's similar to the one defined for ES Request Handlers, and is designed to be easy to implement in C or COBOL (and so in most other languages that support C-style linkage and function/procedure pointers).

There are four main aspects to the interface:

ESM Module format: ESM Modules must be OS loadable objects (DLLs on Windows or CSOs on Unix) or COBOL loadable objects (int or gnt files). The pathname of each module is specified in the ESF Manager's configuration; for security reasons, if it is not absolute, it is interpreted relative to the default directory, which is the "bin" (on Windows) or "lib" (on Unix) subdirectory of the product installation directory. (So, for example, an ESM Module specified as myesm in the configuration could refer to product_dir\Base\Bin\myesm.dll on Windows or $COBDIR/lib/myesm.cso on Unix.)
Unix: Currently only CSOs are supported.
Initial entry point: Each ESM Module should be linked (for shared objects) or compiled (for COBOL int or gnt code) so that it exports an initial entry point that conforms to the definition given below (see Initial Entry Point). ESF Manager will call this entry point each time it loads the ESM Module.
Unix: Currently the initial entry point name must match the module filename. See Initial Entry Point.
Procedure table: The initial entry point will return to ESF Manager a table of function pointers (procedure pointers in COBOL), which will point to the entry points in the module which implement the various services specified by the ESM Module interface. These are the functions that answer security queries, etc. See Procedure Table below.
Manager services: These are not part of the interface provided by the ESM Module, but services made available to ESM Modules by the ESF Manager. See the ESM Module API.

This page also describes return codes for the various functions and what parts of the interface can be omitted from an ESM Module's implementation.

See also:: The Procedure Table definition

Initial Entry Point

All ESM Modules must be built with a default entry point.

For COBOL loadable files (int or gnt modules), this is the beginning of the procedure division. For DLLs and CSOs, the initial entry point is set when the object is linked. If you are using the cbllink program on Windows, the initial entry point is set with the -m option; for the cob command on Unix, use the -e option. For other tools, consult your documentation.

Unix: Currently, the initial entry point's name must match the module's filename, because the Unix loader cannot determine the initial entry point automatically. ESF takes the basename of the module filename, removes any extensions, and looks for an entry point with that name. If that entry point is not found, and the name ends in "_t", it will remove the "_t" suffix and try again.

: For example, if the module is named /some/path/some_mod_t.so, ESF will look for an entry point named some_mod_t, and then for one named some_mod.

The initial entry point must be defined to take no parameters and return a pointer to an ESM Module Procedure Table.

Syntax

   #include "saf-esm.h"
   struct SafPTab *MyESM(void)

COBOL:

   copy "saf-esm.cpy" replacing ==()== by ==esm==
   ...
   procedure division returning by reference esm-proc-table  *> see SafPTab

The initial entry point should set the function pointers (procedure-pointers in COBOL) in a procedure table it defines in static storage and return a pointer to it. ESF Manager will use the procedure table for the life of the process.

Simple C Example

struct SafPTab * osesm(void)
{
   static struct SafPTab PTab =
   {
      SafESM_PT_VER
    , Init              /* Init */
    , Info
    , Verify
    , NULL              /* Auth */
    , NULL              /* XAuth */
    , NULL              /* Update */
    , NULL              /* Status */
    , NULL              /* Control */
    , Exit              /* Exit */
    , NULL              /* Admin */
    , NULL              /* Reserved */
   };

   return &PTab;
}

Procedure Table

The procedure table is an array of function pointers (procedure-pointers in COBOL) that point to functions (entry points in COBOL) in the ESM Module. The ESM Module returns a pointer to its procedure table from its initial entry point. ESF Manager will use the module's procedure table to invoke the module to perform various functions. In other words, ESM Modules are invoked by ESF Manager through a set of callback functions.

Implementing the ESM Module interface is a matter of creating the functions specified by the interface and setting the appropriate pointers to them in the procedure table.

You do not have to implement all of the functions; see Omitting Optional Procedures. Set process table entries to the null (0) pointer value to indicate that an ESM Module does not implement the associated procedure.

New procedures may be added to the table in future releases. The procedure table includes a version number field (SafPTab::Version) which tells the ESF Manager what procedures are listed in the ESM Module's procedure table.

Init Procedure

The Init procedure is used to initialize and configure the ESM Module. Typically a module will use this function to connect to its ESM. It's also how ESF Manager passes the module its configuration data and pointers to the functions of the ESM API, which are services ESM Modules can use for various purposes.

Syntax

   #include "safmgr.h"
   #include "saf-esm.h"
   mf_uns32 Init(const mf_uns32 *Index, struct cas_esm_config_internal *Config,
                 const struct SafEsmApi *Api, void *Reserved)

COBOL:

   copy ???
   ...
   entry "Init" using
       by reference esm-index
       by reference esm-cfg
       by reference esm-api

Parameters:

`[in]`	Index	Points to an area containing the index of this ESM in the ESM list, starting from 0.
`[in]`	Config	Points to a cas_esm_config_internal structure containing the module's configuration data.
`[in]`	Api	Points to a SafEsmApi structure containing pointers to the ESM API service functions that the module can call.
	Reserved	Reserved for future use.

Return Codes: The Init procedure should return zero for success, non-zero for error. See Return Codes for Other Procedures.

Simple C Example

static mf_uns32 Init(const mf_uns32 *Index,
                     struct cas_esm_config_internal *Config,
                     const struct SafEsmApi *Api, void *Reserved)
{
   static const char
      *InitMsg = "OS ESM initialized"
    , *AllocFailMsg = "Could not allocate storage"
    , *LogonFailMsg = "Unrecognized logon type specified in configuration"
    , *ShmFailMsg = "Could not allocate shared memory";
   unsigned char *SptKey = NULL;
   mf_uns32 Ret;
   size_t SptKeyLen;
   int SafRC;
   struct SafStore *CustConfig;

   /* Save the SAF Manager ESM Module API information */
   if (! Api || Api->VerMajor != SafESM_API_VER_MAJ)
      return SafESMRC_PARAM;

   ModAPI = *Api;

   /* Parse custom configuration and get options */
   if (ModAPI.ParseConfig && Config && Config->config && *Config->config)
   {
      SafRC = ModAPI.ParseConfig(Config->config, &CustConfig, NULL);
      if (! SafRC)
      {
         char *CfgVal, *End;
         long LongVal;
         int HaveSecret = 0;

         /* See if an alternate domain is configured */
         SafRC = ModAPI.QueryConfig
         (
            CustConfig
          , "Operation"
          , "Domain"
          , &CfgVal
          , NULL
         );
         if (! SafRC) DftDomain = CfgVal;

         /* See if logon type is specified */
         SafRC = ModAPI.QueryConfig
         (
            CustConfig
          , "Operation"
          , "Type"
          , &CfgVal
          , NULL
         );
         if (! SafRC)
         {
            if (OsSTRCMP_CI(CfgVal, ==, "network"))
               LogonType = LOGON32_LOGON_NETWORK;
            else if (OsSTRCMP_CI(CfgVal, ==, "interactive"))
               LogonType = LOGON32_LOGON_INTERACTIVE;
            else
            {
               if (ModAPI.Log) ModAPI.Log
               (
                  1010
                , 8
                , LogonFailMsg
                , (mf_uns32)strlen(LogonFailMsg)
                , NULL
               );
               return SafESMRC_EXTERNAL;
            }

Info Procedure

The Info procedure is used by ESF Manager to query the ESM Module for identifying information (a string, typically containing a name and version) and the version of the ESM Module interface that it supports.

Syntax

   #include "saf-esm.h"
   mf_uns32 Info(const char **Name, mf_uns32 *IFVersion,
                 const unsigned char **Signature, void *Reserved)

COBOL:

   01  esm-name         pointer.
   01  esm-if-version   pic x(4) comp-5.
     78  esm-if-ver     value 1.
   01  esm-signature    pointer.
   01  esm-reserved     pointer.
   ...
   entry "Info" using by reference esm-name esm-if-version
                      by value     esm-signature esm-reserved

Parameters:

`[out]`	Name	Module name string. Set this to the address of a null-terminated string containing any information the ESM Module would like to use for identification.
`[out]`	IFVersion	Interface version. Set this to the interface version the module is compiled with (`SafESM_IF_VER` in C). Currently this is 1.
	Signature	Reserved for future use.
	Reserved	Reserved for future use.

Return Codes: The Info procedure should return zero for success, non-zero for error. See Return Codes for Other Procedures.

Simple C Example

static mf_uns32 Info(const char **Name, mf_uns32 *IFVersion,
                     const unsigned char **Signature, void *Reserved)
{
   *Name = "OS ESM version " OsVERSION_STRING;
   *IFVersion = SafESM_IF_VER;
   return 0;
}

Verify Procedure

The ESM Module's Verify procedure is invoked to process an ESF API VERIFY (user authentication) request.

The parameter to the Verify procedure is the ESF API control block. Some ESM Modules (particularly those written in COBOL) may use this parameter exclusively. Other ESM Modules (particularly those written in C or C++) may want to use the ExtractVerifyStrings service provided by ESF Manager to get C-style nul-terminated copies of the variable-length string data in the parameter block.

Syntax

   #include "safapi.h"
   #include "saf-esm.h"
   mf_uns32 Verify(struct safpb_parameter_block *Request, void *Reserved)

COBOL:

   copy "safapi.cpy" replacing ==()== by ==saf==
   ...
   entry "Verify" using by reference saf-safpb-parameter-block

Parameters:

`[in,out]`	Request	The Safpb_Parameter_Block structure containing the request as passed to the ESF API.
	Reserved	Reserved for future use.

Return Codes: See Return Codes for Security Procedures (Verify, Auth, XAUth, and Admin).

Implementation Notes

The ESF API control block (and the strings returned by EsmExtractVerifyStrings()) includes a "New Password" string. Some ESMs support changing a user's password as part of a successful Verify request; others do not, and should ignore this parameter. (Note that if the user's password is successfully changed, the ESM Module should indicate that in the return code fields in the ESF API control block. See Return Codes for Security Procedures (Verify, Auth, XAUth, and Admin).)

There is also a string called "Group". This is a short (up to 8 characters) string which can optionally be included in the Verify request. With some ESMs, if a group is specified, they may grant additional permissions for the session if the Verify request succeeds and additional checks (typically, that the user is a member of the group) pass. Other ESMs ignore this information. See User Groups and the Signon Group.

Already-Verified Status

Normally, ESF Manager only calls an ESM Module's Verify procedure if none of the higher-priority ESM Modules have already provided a definite response. However, ESF Manager can be configured to call all subsequent ESM Modules after one successfully verifies a user. This lets lower-priority ESM Modules reject a user that has already been verified by a higher-priority module, so that users are only granted access if all ESM Modules allow them in.

This mode is also useful if there is a lower-priority ESM Module which needs to update the ACEE following successful verification.

ESM Modules can determine whether another module has already verified the user by checking whether the safpb_api_rc field still has the value saf78_SAF_RC_NOT_COMPLETE (4).

Auth Procedure

The ESM Module's Auth procedure is invoked to process an ESF API AUTH (resource access authorization) request.

The parameter to the Auth procedure is the ESF API control block. Some ESM Modules (particularly those written in COBOL) may use this parameter exclusively. Other ESM Modules (particularly those written in C or C++) may want to use the ExtractAuthStrings service provided by ESF Manager to get C-style nul-terminated copies of the variable-length string data in the parameter block.

Syntax

   #include "safapi.h"
   #include "saf-esm.h"
   mf_uns32 Auth(struct safpb_parameter_block *Request, void *Reserved)

COBOL:

   copy "safapi.cpy" replacing ==()== by ==saf==
   ...
   entry "Auth" using by reference saf-safpb-parameter-block

Parameters:

`[in,out]`	Request	The Safpb_Parameter_Block structure containing the request as passed to the ESF API.
	Reserved	Reserved for future use.

Return Codes: See Return Codes for Security Procedures (Verify, Auth, XAUth, and Admin).

XAuth Procedure

The ESM Module's Auth procedure is invoked to process an ESF API XAUTH (extended resource access authorization) request. (XAUTH is similar to AUTH but uses a set of independent permissions rather than a single permission level. It is used by some non-MTO facilities, such as MFDS.)

The parameter to the XAuth procedure is the ESF API control block. Some ESM Modules (particularly those written in COBOL) may use this parameter exclusively. Other ESM Modules (particularly those written in C or C++) may want to use the ExtractAuthStrings service provided by ESF Manager to get C-style nul-terminated copies of the variable-length string data in the parameter block.

Syntax

   #include "safapi.h"
   #include "saf-esm.h"
   mf_uns32 XAuth(struct safpb_parameter_block *Request, void *Reserved)

COBOL:

   copy "safapi.cpy" replacing ==()== by ==saf==
   ...
   entry "XAuth" using by reference saf-safpb-parameter-block

Parameters:

`[in,out]`	Request	The Safpb_Parameter_Block structure containing the request as passed to the ESF API.
	Reserved	Reserved for future use.

Return Codes: See Return Codes for Security Procedures (Verify, Auth, XAUth, and Admin).

Update Procedure

The ESM Module's optional Update procedure is invoked to process an ESF API UPDATE (administrative update notification) request. These requests tell ESF that the security definitions in an External Security Manager have been changed, and ESF should update any cached or internal data that may be affected. See External Administrative Update Notification for more information.

The parameters to the Update procedure are an update-type indicator and the ESF API control block containing the request.

The update-type indicator is an integer that tells the ESM module whether this is a normal update, or if the Update callback is being invoked to tell the module that one or more updates have been handled by other processes. In the latter case, the module does not need to update any shared information (for example, data in shared memory), but does need to clear out any relevant local information. Only modules running in a multiprocess, shared-memory environment (currently, this means running under CAS) will receive update calls of this type.

The type codes are:

SafESM_UPDATE: This is a normal update request, and the ESF API control block parameter will contain the update request from the caller. See the definitions of the SAFROUTE Parameter Block and the UPDATE Request Structure.

SafESM_UPDATED: One update request has been handled by another process running in this environment. That process will have updated shared data, but the ESM Module should clear any affected locally-cached information. (If the module does not cache any security data locally, it can ignore this request.) The ESF API control block parameter will contain a copy of the update request that was processed.

SafESM_REFRESH: More than one update request has been handled by other processes since this process was last updated. The ESM Module should flush all locally-cached security information. (ESF does not keep copies of more than one pending update request, so if a process misses two or more update requests, it can't be notified of what specifically was affected.) As with UPDATED, if the module doesn't keep any security information cached locally, it can ignore this request. For this request, the ESF API control block parameter will not be supplied (the parameter will be null).

Syntax

   #include "safapi.h"
   #include "saf-esm.h"
   mf_uns32 Update(mf_s32 Type, struct safpb_parameter_block *Request,
                   void *Reserved)

COBOL:

   copy "safapi.cpy" replacing ==()== by ==saf==
   01  saf-update-type pic x(4) comp-5.
   ...
   entry "Update" using by value saf-update-type
                        by reference saf-safpb-parameter-block

Parameters:

`[in]`	Type	The request type; see ESF ESM Update Request Types.
`[in,out]`	Request	The Safpb_Parameter_Block structure containing the request as passed to the ESF API.
	Reserved	Reserved for future use.

Return Codes: See Return Codes for Other Procedures.

Status Procedure

To be defined.

Control Procedure

To be defined.

Exit Procedure

The ESM Module's Exit procedure is invoked when the calling process is about to exit. The module can use this opportunity to perform any final cleanup, detatch from its ESM, etc.

Syntax

   #include "saf-esm.h"
   mf_uns32 Exit(const mf_uns32 *Index, void *Reserved)

COBOL:

   entry "Exit" using
       by reference esm-index

Parameters:

`[in]`	Index	Points to an area containing the index of this ESM in the ESM list, starting from 0.
	Reserved	Reserved for future use.

Return Codes: The Exit procedure should return zero for success, non-zero for error. See Return Codes for Other Procedures.

Simple C Example

static mf_uns32 Exit(const mf_uns32 *Index, void *Reserved)
{
   static const char *ExitMsg = "MLDAP ESM exiting";
   struct MldInstance *Instance = NULL;

   Log(1002, 0, ExitMsg, strlen(ExitMsg), NULL);

   if (Index) Instance = &MldInstance[*Index];

   if (Instance && Instance->MldapHandle)
   {
      m_ldap_unbind(Instance->MldapHandle);
      Instance->MldapHandle = NULL;
   }

   return 0;
}

Admin Procedure

The ESM Module's Admin procedure is invoked to process an ESF Admin request. ESF Admin is an API provided by ESF to present a consistent interface for administrative actions, such as adding users, on External Security Managers. Not all ESMs will provide a programmatic interface for administrative updates, so some ESM Modules will not be able to implement the Admin procedure, and many modules will only support some possible ESF Admin requests. Also, it's likely that for security reasons an administrator will only grant limited permissions to an ESM Module (typically through the credentials it presents to the ESM when it connects), so even if an ESM Module implementes Admin it may not be able to process requests successfully, based on its configuration.

The parameter to the Admin procedure is the ESF API control block. The Admin request section of the control block is used for Admin requests. It contains a count of arguments and a pointer to an argument table, which is an array of struct safadmin_argtbl. Each structure has a keyword and value string pair; these name/value pairs describe the parameters for the requested action.

The specific action being requested is identified by the safpb_type field of the control block. See ESF API Admin Subcommands.

Currently, in order to get the definitions for the ESF Admin API, you must define saf78_SAFADMIN_DATA_AREAS before including safapi.h.

Further details to be provided.

Syntax

   #define saf78_SAFADMIN_DATA_AREAS
   #include "safapi.h"
   #include "saf-esm.h"
   mf_uns32 Admin(struct safpb_parameter_block *Request, void *Reserved)

COBOL:

   copy "safapi.cpy" replacing ==()== by ==saf==
   ...
   entry "Admin" using by reference saf-safpb-parameter-block

Parameters:

`[in,out]`	Request	The Safpb_Parameter_Block structure containing the request as passed to the ESF API.
	Reserved	Reserved for future use.

Return Codes: See Return Codes for Security Procedures (Verify, Auth, XAUth, and Admin).

Return Codes

An ESM Module's initial entry point returns a pointer to a procedure table (SafPTab).

ESM Module procedures return a 32-bit integer value which indicates success or failure, and for most functions can indicate additional information as well.

Return Codes for Security Procedures (Verify, Auth, XAUth, and Admin)

The security request processing procedures, Verify, Auth, and XAuth, and the administration procedure Admin, set their result information in the passed-in ESF API parameter block. They return zero to indicate that the result codes in the parameter block are valid, or non-zero to indicate that a processing error has occured. Any processing error is treated by ESF Manager as a failure, and the security request will be denied.

Note that this means that Verify should return zero even if the user's credentials were incorrect, and Auth / XAuth should return zero even if the requested access is denied. They indicate the success or failure of the caller's security request within the ESF API paramerer block, as described below.

Standard Return Codes for Verify, Auth, XAuth, and Admin

An ESM Module's Verify, Auth, XAuth, and Admin procedures can return the values described for the other ESM Module procedures; see ESM Module Procedure Return Codes.

Micro Focus recommends that ESM Module authors consider codes 1-999 reserved for future use; this range will be used to define additional standard return codes.

Result Codes in the ESF API Parameter Block

Verify, Auth, XAuth, and Admin indicate that a request was granted, was denied, or could not be processed (and in some cases indicate additional information such as password expiration) by setting values in the ESF API parameter block.

Result codes go in three one-byte values in the RETCODES structure in the parameter block. There are three fields, labelled safpb_api_rc, safpb_mgr_return, and safpb_mgr_reason. The safpb_api_rc codes depend on the function (Verify / Auth / XAuth) being invoked; the other two codes depend on the value of safpb_api_rc. Various valid combinations are listed in safapi.h.

Typical Result Codes for Verify

For a Verify request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules. For an explanation of the response classes (Allow, Deny, Fail, and Unknown), see the section ESF API Calls.

rc return reason Meaning

saf78_SAF_RC_SUCCESS (0) saf78_RC_NORMAL (0) saf78_RS_NORMAL (0) Verification succeeded, no additional information (this is an Allow result)

saf78_SAF_RC_NOT_COMPLETE (4) saf78_RC_NO_DECISION (0) saf78_RS_ESM_NOT_CALLED (0) The ESM Module does not implement this procedure, or it has decided that this request does not apply to it (this is an Unknown result)

saf78_SAF_RC_NOT_COMPLETE (4) saf78_RC_NO_USER_PROFILE (4) saf78_RS_NORMAL (0) The ESM does not have a record for this user (this is an Unknown result)

saf78_SAF_RC_FAILURE (8) saf78_RC_NORMAL (0) saf78_RS_NORMAL (0) The ESM rejected this request, and does not wish to provide any additional information (note this is a Deny result, not a Fail result, despite the name of the associated constant). This code can be used if the organization's security policy requires not revealing information about why a signon request was denied.

saf78_SAF_RC_FAILURE (8) saf78_RC_PWRD_INVALID (8) saf78_RS_NORMAL (0) Verification failed because the supplied password was incorrect (this is a Deny result)

saf78_SAF_RC_FAILURE (8) saf78_RC_PWRD_EXPIRED (12) saf78_RS_NORMAL (0) Verification failed because the supplied password has expired (this is a Deny result). Some ESM Modules will accept the request if it is repeated with a new password supplied in the optional new-password field.

saf78_SAF_RC_FAILURE (8) saf78_RC_PWRD_CHANGE_ERR (16) saf78_RS_NORMAL (0) Verification failed because the supplied new password was not accepted by the ESM (this is a Deny result)

saf78_SAF_RC_FAILURE (8) saf78_RC_USER_REVOKED (28) saf78_RS_NORMAL (0) Verification failed because signon is disabled for the user's account (this is a Deny result)

saf78_SAF_RC_FAILURE (8) saf78_RC_DATABASE_ERROR (92) saf78_RS_NORMAL (0) Verification failed because the ESM Module or its associated ESM was unable to process the request (this is a Fail result)

Typical Result Codes for Auth and XAuth

For an Auth or XAuth request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules. For an explanation of the response classes (Allow, Deny, Fail, and Unknown), see the section ESF API Calls.

Note that there is a special type of Auth / XAuth call that does not request specific access; instead, it asks the ESM to determine what access the user is permitted to the given resource. The caller uses the saf78_TYPE_ATTR_STATUS_ACC flag in the Safpb_Parameter_Block::safpb_type field to request this information. If successful, an Auth call of this type will return the user's permission level for the object as part of the return code (see below). The XAuth function, on the other hand, returns the information in the request-specific part of the parameter block.

rc return reason Meaning

saf78_SAF_RC_SUCCESS (0) saf78_RC_USER_IS_AUTH (0) saf78_RS_NORMAL (0) Authorization is granted, no additional information (this is an Allow result)

saf78_SAF_RC_SUCCESS (0) saf78_RC_ACCESS_INFO (20) saf78_RS_ACCESS_{NONE (0),
READ (4),
UPDATE (8),
CONTROL (12),
ALTER (16)} (Auth only) The user has the specified level of access to the resource

saf78_SAF_RC_NOT_COMPLETE (4) saf78_RC_NO_DECISION (0) saf78_RS_ESM_NOT_CALLED (0) The ESM Module does not implement this procedure, or it has decided that this request does not apply to it (this is an Unknown result)

saf78_SAF_RC_NOT_COMPLETE (4) saf78_RC_RESOURCE_NOT_PROT (4) saf78_RS_NO_RESOURCE_PROF (0) The ESM does not have a record for this resource (this is an Unknown result)

saf78_SAF_RC_FAILURE (8) saf78_RC_USER_NOT_AUTH (8) saf78_RS_NORMAL (0) Authorization is denied (this is a Deny result)

saf78_SAF_RC_FAILURE (8) saf78_RC_DATABASE_ERROR (92) saf78_RS_NORMAL (0) Authorization failed because the ESM Module or its associated ESM was unable to process the request (this is a Fail result)

Typical Result Codes for Admin

For an Admin request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules.

An Admin request can succeed or fail, or it can be ignored if the ESM Module does not implement the requested administration subcommand. (If the module determines that it cannot process the request because of an unsuitable or missing parameter, it can fail or ignore the request as the author feels is appropriate.) So the return codes below are classified as Success, Failure, or Ignored results.

rc return reason Meaning

saf78_SAF_RC_SUCCESS (0) saf78_RC_NORMAL (0) saf78_RS_NORMAL (0) The request was processed, no additional information (this is a Success result)

saf78_SAF_RC_NOT_COMPLETE (4) saf78_RC_NO_DECISION (0) saf78_RS_ESM_NOT_CALLED (0) The ESM Module does not implement this procedure (this is an Ignored result)

saf78_SAF_RC_NOT_COMPLETE (4) saf78_RC_NO_DECISION (0) saf78_RS_ESM_DECLINED (4) The ESM Module declined to process the request (this is an Ignored result)

saf78_SAF_RC_NOT_COMPLETE (4) saf78_RC_KEYWORD_ERROR (4) saf78_RS_KEYWORD_UNKNOWN (4) The request specified a parameter keyword that the ESM Module does not recognize (this is an Ignored result)

saf78_SAF_RC_FAILURE (8) saf78_RC_VALUE_ERROR (4) saf78_RS_VALUE_INVALID (4) The request specified a parameter value that is not valid for this ESM Module or its ESM (this is a Failure result)

saf78_SAF_RC_FAILURE (8) saf78_RC_VALUE_ERROR (4) saf78_RS_VALUE_LENGTH (8) The request specified a parameter value that was too long or short for this ESM Module or its ESM (this is a Failure result)

saf78_SAF_RC_FAILURE (8) saf78_RC_DATABASE_ERROR (92) saf78_RS_NORMAL (0) The ESM Module or its associated ESM was unable to process the request (this is a Failure result)

Return Codes for Other Procedures

For the other procedures defined in the ESM Module's procedure table (Init, Info, Update, Status, Control, and Exit), zero means normal success and any non-zero value indicates an error or some other unusual condition.

For the currently-defined return codes, see ESM Module Procedure Return Codes.

The range 1000-1999 is reserved for user-defined codes.

Omitting Optional Procedures

It's not necessary to implement all of the procedures listed in the procedure table. An ESM Module can set any of the pointers to null to indicate that it does not support that function; the ESF Manager will only call functions that a module implements.

Here are the effects of leaving each of the procedures unimplemented:

Init: The ESM Module will not receive any configuration information from ESF Manager when it is loaded, nor will it have access to the ESM API. ESF Manager will assume that it initialized successfully when its initial entry point was called after loading. Most non-trivial ESM Modules will need to implement this procedure.
Info: ESF Manager will use the name of the binary file it loaded for the module as the module's name. It will assume the module supports version 1 of the interface.
Verify: ESF Manager will not call the ESM to process VERIFY (user login) requests.
Auth: ESF Manager will not call the ESM to process AUTH (resource access check) requests.
XAuth: ESF Manager will not call the ESM to process XAUTH (extended resource access check) requests. Note that XAUTH is not used for MTO (mainframe emulation) resources.
Update: ESF Manager invokes the Update procedure to tell an ESM Module that ESF has been notified of an administrative update. This usually means that an administrator has used some other tool to change the security configuration in an external security repository, so the ESM Module may need to discard cached information, reconnect to its ESM, or take some other action specific to that ESM. Many ESM Modules will not need to implement this procedure.
Status: The Status procedure lets the ESF Manager query an ESM Module for status information, such as the state of its connection to its ESM. If a module omits this procedure, ESF Manager will simply report what it knows about the module's status (whether it is in use or not, basically).
Control: ESF Manager uses this procedure to notify a module that it is being enabled or disabled. A module that is disabled will not be called for VERIFY or AUTH requests.
Exit: ESF Manager invokes this procedure when it is exiting; it gives the module a chance to do any special cleanup it may want to perform. If the module omits this procedure it will not be notified when the manager is terminated.
Admin: The Admin procedure is used to make administrative requests from ES components (such as the MFDS administration user interface) to ESMs. ESM Modules may implement Admin to integrate ESM administration with ES administration. If they omit this procedure, administrators will have to make updates to the ESM (such as adding new users) using the tools provided with the ESM.

rc	return	reason	Meaning
saf78_SAF_RC_SUCCESS (0)	saf78_RC_NORMAL (0)	saf78_RS_NORMAL (0)	Verification succeeded, no additional information (this is an Allow result)
saf78_SAF_RC_NOT_COMPLETE (4)	saf78_RC_NO_DECISION (0)	saf78_RS_ESM_NOT_CALLED (0)	The ESM Module does not implement this procedure, or it has decided that this request does not apply to it (this is an Unknown result)
saf78_SAF_RC_NOT_COMPLETE (4)	saf78_RC_NO_USER_PROFILE (4)	saf78_RS_NORMAL (0)	The ESM does not have a record for this user (this is an Unknown result)
saf78_SAF_RC_FAILURE (8)	saf78_RC_NORMAL (0)	saf78_RS_NORMAL (0)	The ESM rejected this request, and does not wish to provide any additional information (note this is a Deny result, not a Fail result, despite the name of the associated constant). This code can be used if the organization's security policy requires not revealing information about why a signon request was denied.
saf78_SAF_RC_FAILURE (8)	saf78_RC_PWRD_INVALID (8)	saf78_RS_NORMAL (0)	Verification failed because the supplied password was incorrect (this is a Deny result)
saf78_SAF_RC_FAILURE (8)	saf78_RC_PWRD_EXPIRED (12)	saf78_RS_NORMAL (0)	Verification failed because the supplied password has expired (this is a Deny result). Some ESM Modules will accept the request if it is repeated with a new password supplied in the optional new-password field.
saf78_SAF_RC_FAILURE (8)	saf78_RC_PWRD_CHANGE_ERR (16)	saf78_RS_NORMAL (0)	Verification failed because the supplied new password was not accepted by the ESM (this is a Deny result)
saf78_SAF_RC_FAILURE (8)	saf78_RC_USER_REVOKED (28)	saf78_RS_NORMAL (0)	Verification failed because signon is disabled for the user's account (this is a Deny result)
saf78_SAF_RC_FAILURE (8)	saf78_RC_DATABASE_ERROR (92)	saf78_RS_NORMAL (0)	Verification failed because the ESM Module or its associated ESM was unable to process the request (this is a Fail result)