SAF user mapping plug-in lookup function

Function

This function returns SAF user credentials when it can find a mapping from the source user credentials to a SAF user. The source user information and the returned user information can be a user ID, a user ID and password, or some other forms of user credentials. The plug-in implementation might be able to process all types of credentials or just a subset. The default plug-in implementation accepts a source user ID and returns a SAF user ID.

The first call to safMappingLookup() must be preceded by a call to safMappingInit().

Format

#include <irrspim.h>

int safMappingLookup(
  SafmapHandle * mh,
  SafmapCreds  * sUser,
  char         * aData,
  SafmapResult * mResult,
  SafmapErr    * mErr
  );

Requirements

Language: C or C++.
Authorization: Problem program or supervisor state, any key.
Dispatchable unit mode: Task.
Cross-memory mode: PASN=HASN.
AMODE: 31 bit.
RMODE: Any.
ASC Mode: Primary.
Serialization: Enabled for interrupts.
Locks: No locks held.
Control parameters: All storage must be in the primary address space.

RACF® authorization

The calling application does not require special authorization before calling safMappingLookup() when you use the default SAF user mapping plug-in implementation. However, the calling application requires authorization to create a mapping handle. See SAF user mapping plug-in initialization function – safMappingInit() for more information.

Note: Other SAF user mapping plug-in implementations might have different authorization requirements.

Usage notes

The safMappingLookup() parameters behave as follows:

Table 1. The parameters of the safMappingLookup() function
Parameter	Input/output	Description
`mh`	Input/output	(Required) A pointer to a SafmapHandle structure. The mh handle is used by the plug-in interface and implementations to anchor data that must persist across the calls to the plug-in interface.
`sUser`	Input	(Required) A pointer to a SafmapCreds structure. sUser contains the credentials for the known or source user. The credentials are assumed to be NULL terminated. A number of credential types can be used with the plug-in, however, not all plug-in implementations support all possible types. Documentation for the plug-in implementations describes the types that are recognized by the implementation. The default plug-in implementation recognizes credentials that are made up of an EIM registry name and a user name (credential type SAFMAP_REGISTRY_USER). The default plug-in implementation accepts character strings encoded in the IBM-1047 CCSID. Other plug-in implementations might support additional CCSIDs.
`aData`	Input	(Optional) A NULL terminated character string. The aData parameter contains additional information that a plug-in implementation can use to refine the selection of the SAF user credentials. This information is useful when there are multiple mappings from one set of source user credentials to several SAF user credentials. This pointer can be NULL. There are no default values. The default SAF user mapping plug-in implementation can use this value. However, plug-in implementations are not required to support it. See z/OS Integrated Security Services EIM Guide and Reference for information about how this string can be used with the eimGetTargetFromSource() API. The default plug-in implementation accepts character strings encoded in the IBM-1047 CCSID. Other plug-in implementations might support additional CCSIDs.
`mResult`	Input/output	(Required) A pointer to a SafmapResult structure that is immediately followed by storage containing the returned credentials. The mResult structure contains the SAF user credentials. A number of credential types can be returned; however, not all plug-in implementations support all possible types. Documentation for the plug-in implementation describes the types that are recognized by the implementation. The default SAF user mapping plug-in implementation returns a SAF user ID (SAFMAP_USER_ONLY). The bytesAvailable field contains the length of the storage following the SafmapResult structure. When the credential type is SAFMAP_USER_ONLY, the recommended value is 9, that is, eight bytes for the maximum length of the SAF user ID and one byte for the NULL terminator. The credentialLen field is set to the length of the credential found during the mapping lookup. It includes the NULL terminators in the length. A credential is returned when it meets the criteria set by the plug-in implementation. For the default plug-in implementation, a credential is returned when it is no longer than eight characters. The pointers in the credential are set to NULL when a credential is not returned. The default plug-in implementation only returns credentials encoded in the IBM-1047 CCSID. Other plug-in implementations might support additional CCSIDs.
`mErr`	Input/output	(Required) A pointer to a SafmapErr structure. The mErr structure contains more detailed information about the success or failure of the request to the plug-in interface. The mErr structure contains a return code, a reason code provided by the plug-in implementation, and an error string that gives more information about the results of the request. The maximum length of the error string is 256 bytes. The error string is NULL terminated. The mErr structure might also contain information about the version of the plug-in implementation and the plug-in implementation specific data such as the configuration settings. Any strings in the mErr structure are encoded in IBM-1047 CCSID.

Function return values

The safMappingLookup() function returns a number of pieces of information to help you with problem determination. The SAF return value, the plug-in return code (mErr->mpiReturnCode), the plug-in reason code (mErr->mpiReasonCode), and an error string (mErr->message) are returned by the plug-in interface code or the plug-in implementation. In addition, the version of the plug-in interface (mErr->mpiVersion) and any plug-in implementation specific data (mErr->mpiInfo) can be found in the SafmapErr structure.

Special processing occurs for parameter errors (mErr->mpiReturnCode == SAFMAP_ERROR_PARMERR) and unsupported credential types (mErr->mpiReturnCode == SAFMAP_ERROR_NOTSUP). The plug-in reason code (mErr->mpiReasonCode) contains a number identifying which parameter in the parameter list is in error.

The cleanup of the connection with the plug-in implementation occurs when the SAF return value is SAFMAP_ERROR or SAFMAP_SEVERE.

The SAF return values and the plug-in return codes (mErr->mpiReturnCode) are listed in the following table. These SAF return values and plug-in return codes are standard across the plug-in implementations. The plug-in reason code (mErr->mpiReasonCode) is unique to the plug-in implementation, except as previously noted.

Table 2. The SAF return values and the plug-in reason codes for the safMappingLookup() function
SAF return value	Plug-in Return Code (mErr->mpiReturnCode)	Explanation
0	SAFMAP_ONE_RETURNED (1)	One of the SAF user credentials was returned.
SAFMAP_WARNING (4)	SAFMAP_NONE_RETURNED (0)	No user credential mapping was found, or the user portion of the credential is longer than 8 characters when the default plug-in implementation is used.
SAFMAP_WARNING (4)	SAFMAP_MANY_FOUND (2)	More than one set of SAF user credentials were found for the source user credentials.
SAFMAP_WARNING (4)	SAFMAP_ERROR_NOTSUP (24)	One of the parameters contains a credential type that is not supported. Check mErr->mpiReasonCode to identify the parameter that is in error.
SAFMAP_ERROR (8)	SAFMAP_ERROR_NOTCONN (20)	The plug-in implementation lost the connection with its data source during a credential lookup. Call the safMappingInit() function again to reestablish the connection.
SAFMAP_SEVERE (12)	SAFMAP_ERROR_INTERFACE(16)	The plug-in interface detected a problem internal to the irrspim dll.
SAFMAP_SEVERE (12)	SAFMAP_ERROR_PARMERR (28)	The parameter list for the plug-in contains an error. Check mErr->mpiReasonCode to identify the parameter that is in error.
SAFMAP_SEVERE (12)	SAFMAP_ERROR_PLUGIN (32)	An error internal to the plug-in implementation occurred.
SAFMAP_SEVERE (12)	SAFMAP_ERROR_SETUP (36)	The plug-in detected a problem in how the plug-in implementation is configured.