Entire Net-Work Client includes an External Security Interface (ESI) for ADASAF support that provides access to secured Adabas resources on a z/OS host node. To secure these resources on the host node, Adabas interacts with the Adabas SAF Security Kernel (ADASAF), an Adabas add-on product. ADASAF links Adabas to the CA-ACF2, CA-Top Secret, or RACF external security packages installed on the host system. For more information about the Adabas SAF Security Kernel, refer to its documentation.
The External Security Interface (ESI) provides two methods you can used to access secured Adabas resources on a z/OS host node:
In Windows environments only, you can use an online application to log onto ESI.
In any environment, you can use an ESI security exit. This method should be used in any environment where you want full control of obtaining the logon information. A sample security exit is provided with Entire Net-Work Client called lnkxsaf.
This document covers the following topics:
To select the External Security Interface method you prefer to use, you must set some parameters in the System Management Hub. In addition, regardless of the ESI method selected, you must set parameters that identify the Adabas SAF Security Kernel library and function that should be used for access to secured z/OS host resources.
Note:
This section describes how to specify these parameters using the
System Management Hub, but you can also specify them as environment variables
instead.
To set ESI method and Adabas SAF Security Kernel parameters:
Make sure you have accessed the System Management Hub.
Select and expand Entire Net-Work Client from the list in tree-view to access the Entire Net-Work Client administration area.
Select and expand Clients from the Entire Net-Work Client sublist.
A list of machine names appears. The machines listed are computers on which clients managed by this installation of the System Management Hub are defined.
Select and expand the client machine on which the client is defined.
The client configuration section becomes available in tree-view.
Right-click on the client configuration whose parameters you want to maintain and select from the resulting drop-down list.
The Set ADASAF Parameters panel appears in detail-view.
Modify the parameters on the ADASAF Parameters panel, as described in the following table. When all parameters are set as you want, click to save them.
| Parameter | Description | Required? | Default |
|---|---|---|---|
| LNKADAESI |
This parameter is available for Windows systems only. Indicate whether the ESI online application should be used instead of a user exit. Valid values are "YES" (use the online application) or "NO" (use a user exit). The default is "NO". If LNKADAESI is set to "YES" and a value is given in LNKADASAF, the online application is used (LNKADAESI settings override LNKADASAF). |
No | No |
| LNKADASAF | Specify the library and function names of the
user exit that will provide access to the secured Adabas resource via the
Adabas SAF Security Kernel (ADASAF). The library and function names should be
specified with a space between them, using the following format:
library function If no names are specified, ("<not defined>" is listed) and the value "lnkxsaf lnkxsaf" is used. (The lnkxsaf library is either lnkxsaf.dll or lnkxsaf.so). |
No | A value of "lnkxsaf lnkxsaf" is used. |
The parameters are updated in the appropriate Entire Net-Work Client configuration file.
When you elect to use the ESI online application to access Adabas secured resources, your ESI access information (user ID and password) must be supplied via an ESI logon dialog. The user ID and password you specify on the ESI logon dialog are encrypted and stored on the local node to confirm that you have logged onto ESI. They are then used by the Adabas SAF Security Kernel (ADASAF) when you attempt to use an application that accesses a secured Adabas resource. You can elect to use the ESI online application by setting the LNKADAESI parameter (or environment variable) to "YES". For more information, read Specifying the ESI Method and Appropriate Adabas SAF Security Kernel Parameters.
Note:
Software AG strongly recommends that you modify the
encryption/decryption method used to encrypt your ESI access information. The
encryption/decryption algorithm you use must match the ones used on the
mainframe. For more information, read Encryption Method
Modifications.
This section covers the following topics:
You can access the ESI logon dialog either manually or dynamically.
If you elect to access the ESI logon dialog dynamically, the Adabas SAF Security Kernel will issue a response code when you first attempt to access an Adabas secured resource. When the response code is returned, it is intercepted by Entire Net-Work Client and the ESI logon dialog appears. After supplying the logon information requested by the dialog (as explained later in this section, Entire Net-Work Client resubmits the request to the Adabas secured resource.
The user ID and password you specify on the ESI logon dialog are encrypted and stored on the local node to confirm that you have logged onto ESI. They are then used for any Adabas security checks that occur when you execute an application that requests access to Adabas-secured resources.
If the security check is passed, the application is allowed to access those resources that are permitted according to your Adabas security user profile.
If the security check is not passed, an Adabas security response code is returned to the application.
If you elect to access the ESI logon dialog manually, complete the
following steps:
Run the ADAESI.EXE executable file in the Entire Net-Work Client code directory.
Note:
You may want to add this to your Startup
folder.
The ESI logon dialog appears, as shown below.
Supply a valid user ID and password in the User ID and Password fields and then click . The user ID and password must correspond to those known to the external security package on the z/OS node.
Your ESI access information is encrypted and stored.
If your password has expired, the dialog contains the message "New Password Required" appears. Enter a new password in the New Password field and confirm the update in the Confirmation field.
Once you have logged onto ESI, you can specify the amount of time, in minutes, that Adabas can remain inactive (no Adabas calls) before you are automatically logged out. This feature is provided to prevent unauthorized access to Adabas-secured resources when your PC is left unattended. To specify an automatic logoff time, specify a value from "0" (zero) to "1440" minutes (24 hours) in the Auto Logoff field on the ESI long dialog. The default value is 60 minutes.
If the Auto Logoff value is "60", you are logged off of Adabas security after 60 minutes of Adabas inactivity. When you log on again, the security check is performed as if you were logging on for the first time.
If the Auto Logoff value is "0", the automatic no automatic logoff occurs.
The user ID and password you specify on the ESI logon dialog are encrypted and stored on the local node to confirm that you have logged onto ESI.
Notes:
To modify the method used to encrypt and decrypt the ESI logon dialog
information:
Locate and edit the user exit code supplied with your Entire Net-Work Client installation. The user exit, the encryption and decryption source code, and the files required to compile and link the source code are provided in the \examples\adaesi_uexit directory of the installation.
Modify the encryption and decryption code as required and then compile and link it using the files in the \examples\adaesi_uexit directory.
Note:
Do not change the name of the DLL
(adacrypt.dll) or the procedure name used in the
encryption/decryption program.
When you elect to use the ESI security exit to access an Adabas secured resource, the user exit must be supply the logon and other access information to ESI. This ESI access information is then used when you attempt to use an application that accesses a secured Adabas resource. You can elect to use the ESI online application by setting the LNKADAESI parameter (or environment variable) to blank or "NO" and specifying the ESI user exit library and function name in the LNKADASAF parameter (or environment variable). There is no default. For more information, read Specifying the ESI Method and Appropriate Adabas SAF Security Kernel Parameters.
To modify and use the ESI security exit:
Locate and edit the user exit (the lnkxsaf.c file) supplied with your Entire Net-Work Client installation. The user exit and the files required to compile and link the source code are provided in the \examples\adasaf_uexit directory of the installation.
Modify the user exit as required and then compile and link it using the files in the \examples\adasaf_uexit directory.
Use the AdaSetSaf configuration tool to specify ESI access information to the user exit that will provide access to the secured Adabas resource via the Adabas SAF Security Kernel (ADASAF). This is the same information you supply using the ESI online application (read Accessing z/OS Resources Using the ESI Online Application ).
