Client Version 1.3.3
 —  Installation and Administration  —

Accessing Secured z/OS Host Resources

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:

Thisdocument covers the following topics:


Specifying the ESI Method and Appropriate Adabas SAF Security Kernel Parameters

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.

Start of instruction setTo set ESI method and Adabas SAF Security Kernel parameters:

Make sure you have accessed the System Management Hub.

  1. Select and expand Entire Net-Work Client from the list in tree-view to access the Entire Net-Work Client administration area.

  2. 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.

  3. Select and expand the client machine on which the client is defined.

    The client configuration section becomes available in tree-view.

  4. Right-click on the client configuration whose parameters you want to maintain and select Set Client Parameters from the resulting drop-down list.

    The Set ADASAF Parameters panel appears in detail-view.

    graphics/wclsaf.png

  5. Modify the parameters on the ADASAF Parameters panel, as described in the following table. When all parameters are set as you want, click OK to save them.

    Parameter Description
    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).

    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).

    The parameters are updated in the appropriate Entire Net-Work Client configuration file.

Top of page

Accessing z/OS Resources Using the ESI Online Application

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:

Accessing the ESI Logon Dialog

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.

Start of instruction setIf you elect to access the ESI logon dialog manually, complete the following steps:

  1. 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.

    graphics/esilogon.png

  2. Supply a valid user ID and password in the User ID and Password fields and then click LOGON. 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.

  3. 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.

Automatic Logoff

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.

Encryption Method Modifications

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:

  1. Software AG strongly recommends that you modify the encryption/decryption code. The encryption/decryption algorithm you use must match the ones used on the mainframe.
  2. In past versions of ESI, an ADAESI.INI file and ADAESIX parameter were used to modify the encryption/decryption algorithms. This file and parameter are no longer supported. Instead, you must use the procedure described in this section. In addition, Entire Net-Work Client no longer supports changing the adacrypt.dll library name.

Start of instruction setTo modify the method used to encrypt and decrypt the ESI logon dialog information:

  1. 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.

  2. 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.

Top of page

Accessing z/OS Resources Using the ESI Security Exit

When you elect to use the ESI security exit to access 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.

Start of instruction setTo modify and use the ESI security exit:

  1. 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.

  2. Modify the user exit as required and then compile and link it using the files in the \examples\adasaf_uexit directory.

Top of page