This section describes the application programming interfaces (APIs) provided by Natural SAF Security. It covers the following topics:
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
.
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). |
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. |
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. |
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:
If you specify |
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).
|
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. |
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
.
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). |
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. |
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
.
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:
subprogram
NSCXR
with parameters POBJ-TYPE='US'
and
SUB-TYPE='GR'
, 'GP'
and 'GM'
.