Application Programming Interfaces

This section describes the application programming interfaces (APIs) provided by Natural SAF Security. It covers the following topics:

Overview of Application Programming Interfaces

Natural SAF Security provides the following application programming interfaces (APIs):

Function Invoked Subprogram Example Program of how to Invoke the Subprogram
User and password authentication. NSFNPAS PGMSFU01
NSFNPASZ PGMSFU02
NSFNPAX PGMSFU03
Check resource access to a dedicated API class. NSFNAPC PGMSFCnn
Maintain resource profiles. NSFNRES PGMSFRnn
Check access rights to a resource. NSFNRES, NSFNREX PGMSFXnn
Obtain miscellaneous information from the SAF server. NSFNINF PGMSFInn
Maintain user definitions in RACF. NSFADM PGMSAFnn

The example programs are provided in the Natural Security library SYSSEC.

APIs for User and Password Authentication

NSFNPAS

The subprogram NSFNPAS can be called from any Natural library to verify the authentication of a user (*USER) and, optionally, establish that the user was already logged on.

Five different sub-calls are available:

PPAS-FUNC Action
INDQVER Verify user ID (not password) and create ACEE.
INDQVPW Verify user ID and password, creating new ACEE.
INDQVPO Verify user ID and password without creating new ACEE (CA Top Secret only).
INDQVPT Verify user ID and password without creating ACEE (CA Top Secret only).
INDQVPC Verify user ID and password and change password creating new ACEE.

The parameter data area NSFAPAS is available to invoke this subprogram. Its fields are:

Field Format/Length Description
PPAS-FUNC B1 Indicates type of verification check required.
PPAS-RETC I2 Return code: 8 = error; 16 = severe error.
PPAS-POLD A8 Existing (old) password.
PPAS-PNEW A8 New password.
PPAS-ACCN A8 Accounting information - for future use.
PPAS-SERR B8 Return code (as described in the SAF Security Kernel documentation).

NSFNPASZ

To verify the password of any other user ID, the subprogram NSFNPASZ is provided.

The parameters are the same as described for subprogram NSFNPAS above.

In addition, the parameter data area NSFAPAS contains the following fields for NSFNPASZ:

Field Format/Length Description
PPAS-PUSER A8 User ID of user whose password is to be changed.
PPAS-PMSG A40 Message text returned from the SAF server.

NSFNPAX

To verify and change the password of *USER, the subprogram NSFNPAX is provided.

The parameters are the same as described for the subprogram NSFNPAS above.

In addition, the parameter data area NSFAPAS contains the following fields for NSFNPAX:

Field Format/Length Description
PPAS-PUSER A8 Not used.
PPAS-PMSG A40 Message text returned from the SAF server.

API for Checking Resource Access to Dedicated API Class

The subprogram NSFNAPC can be called from any Natural library to check the access to a general resource profile.

Input Parameters:

Parameter Content
PRES-PROF Name of desired profile.
PRES-CLAS Name of desired class.
PRES-ATTR

Access level to be checked:

H'02' = READ access
H'04' = UPDATE access
H'08' = CTL access
H'80' = ALTER access

If you specify H'00', the highest access level will be returned.

Output Parameters:

Parameter Content
PRES-ATTR If H'00' was specified as input, this field returns the highest acceptable access level.
PRES-RETC Return code:
0 = Profile allowed for given access level.
8 = Error (in this case, the field PRES-SERR contains the SAF error code).

APIs for Maintaining Resource Profiles

NSFNRES

The subprogram NSFNRES can be called from any Natural library to read and maintain security-profile information.

RACF, CA Top Secret and CA-ACF2 enable different levels of functionality to be achieved. The different functions are shown below:

PRES-FUNC Action
INDQRTV Retrieve field(s) from user, group, and general profiles of the security system. CA Top Secret and CA-ACF2 allow fields such as PGMRNAME to be read from a base segment.
INDQRDN Retrieve next resource profile in collating sequence. The name of the resource and selected field(s) can be retrieved. CA Top Secret permits only the USER class to be retrieved in this way. This functionality is currently not available with CA-ACF2.

The parameter data area NSFARES is available to invoke this subprogram. Its fields are:

Field Format/Length Description
PRES-FUNC B1 Indicates function type required.
PRES-ATTR B1 Not used for this call.
PRES-RETC I2 Return code: 0 = call successful ; 4 = profile not found/EOL; 8 = error.
PRES-CLAS A8 Required resource class/type.
PRES-GRUP A8 Default user group - returned.
PRES-PROF A32 Name of resource profile.
PRES-FLDA A8/1:4 Profile field names (array).
PRES-SERR B8 8-byte return code (as described in the SAF Security Kernel documentation).
PRES-SLOG A4 Reserved for future use.
PRES-DATA B16/1:16 Profile data input/output area. The data layout is described in detail in the IBM RACROUTE documentation.

NSFNREX

The subprogram NSFNREX is an extended version of the subprogram NSFNRES. It allows you to process up to 1024 bytes of data per request.

The parameter data area NSFAREX is available to invoke this subprogram. Its fields are identical to NSFARES (see above), except PRES-DATA, whose format/length is B16/1:64.

API for Checking Access Rights to a Resource

The subprogram NSFNRES can be called from any Natural library to test a user's authorization to any resource profile, including those used to protect Natural objects.

PRES-FUNC Action
INDQCHK (PRES-ATTR supplied) Check authorization at given level of access.
INDQCHK (PRES-ATTR zero) Determine user's maximum access level.

The parameter data area NSFARES is provided to invoke this subprogram. Its fields are:

Field Format/Length Description
PRES-FUNC B1 Indicates function type required.
PRES-ATTR B1 Access level to be tested; either zero or determine highest level (as described in the IBM RACROUTE documentation).
PRES-RETC I2 Return code: 0 = success; 8 = error.
PRES-CLAS A8 Resource class/type.
PRES-PROF A32 Name of resource profile.
PRES-SERR B8 8-byte return code (as described in the SAF Security Kernel documentation).

API for Obtaining Information from the SAF Server

The subprogram NSFNINF is provided to perform a number of functions which may be useful when using Natural SAF Security.

The different functions provided are:

PINFFUNC Action
INF-1 Determine last "access denied" message for this user.
INF-2 Determine last "access denied" message - internal format.
INF-3 Return invocation count.
INF-4 Return environment code.
INF-5 Read user name and group from values stored.
INF-6 Update user-name/group values; for example, if these are to be reformatted.
INF-7 Currently not available.
INF-8 Currently not available.
INF-9 Write SMF record.

The parameter data area NSFAINF is provided to invoke this subprogram. The local data area NSFLEQU defines the necessary equate values.

Field Format/Length Description
PINFFUNC B2 Indicates function type required.
PINFRETC I2 Return code: zero = success.
PINFDATA-SUBR I4 Error - sub-response.
PINFDATA-TEXT A72 Last error message.
PINF-COUNT I4 Invocation count.
PINF-ENV A1 Current environment code.
PINF-GROUP A8 Group.
PINF-NAME A32 User name.
PINF-SMFLEN B1 Length of SMF data to be written.
PINF-SMFTXT B255 Data to be written - A15 * 17.

API for Maintaining RACF User Definitions

The subprogram NSFADM can be invoked from any Natural library. It allows you to maintain user definitions contained in RACF from within Natural. It can only be applied to user definitions in RACF, not in other external security systems.

Performing any user maintenance function via NSFADM requires that in RACF you have the appropriate authorization to do so. That is, you can only perform these functions via Natural SAF Security if you are allowed to perform them in RACF itself.

The following functions are provided:

  • Add user

  • Connect user to a group

  • Remove user from a group

  • Delete user

For details on how to invoke the subprogram, and on the individual input and output parameters, see the source codes of the example programs PGMSAFnn.

Natural Security APIs

When Natural SAF Security is active, the evaluations made by some Natural Security APIs will be based not only on user data defined in Natural Security, but also on user data as defined in the external security system. This affects the following APIs: