This document provides programming aids relevant to EntireX Security programming. It assumes you are familiar with the basics of EntireX Broker ACI programming. See EntireX Broker ACI Programming. It covers the following topics:
See Introduction to EntireX Security for overview of concepts and installation.
If your applications are using ACI versions 1 to 7, you will decide at installation time whether they are to communicate with a secured Broker. Your administrator will probably have installed components of EntireX Security into the Broker stub environment(s) and into the Broker kernel.
If your environment is configured using components of EntireX Security, your applications can communicate only with secured Broker kernels. If you attempt to communicate with both secured and non-secured Broker kernels, you will receive ACI response code 00200379, indicating "inconsistent security installation".
To achieve greater flexibility, particularly when migrating applications
from development to production, ACI version 8 introduces the new functionality
described in the following table. For ACI version 8 and above, the application
may assign to the broker control block field KERNELSECURITY
one of the following values:
| Value | Description |
|---|---|
| N | Application does not intend to communicate with a secured Broker kernel. |
| Y | Application intends to communicate with a Broker kernel which is secured using EntireX Security. |
| U | Application intends to communicate with a Broker kernel which is secured with the customer's own security exits. |
This information indicates the application's intention and ensures that
the correct execution occurs in the Broker stub and the Broker kernel. If the
stub and the field KERNELSECURITY do not match,
the application will receive ACI response code
00200379.
If an improper value is assigned, it is treated as a blank. To make this
assignment seamless, use an initial KERNELVERS
command when communicating with each Broker kernel so that the field is
assigned automatically.
Note:
The default value (binary zero or space) specified in this field
will result in the behavior being determined by the security configuration
rather than programmatically. It is therefore possible to communicate either
with a secure or non-secure Broker.
Issuing a KERNELVERS
command will return information in the
KERNELSECURITY
field of the broker control block structure to indicate whether the
application is communicating with a secure or non-secure Broker Kernel. This
information can be important for ensuring the security of transactions and when
making decisions such as prompting for user ID and password credentials. Providing user ID and password in ACI-based Programming is described under Broker ACI fields USER‑ID, PASSWORD, LONG-PASSWORD-LENGTH, and the COBOL Example using Long Password.
For user ID and password handling with RPC clients, refer the documentation of the wrapper in use; see EntireX Wrappers in the Designer documentation.
The following values are returned in the
KERNELSECURITY field for ACI version 8 and above:
| Value | Description |
|---|---|
| N | This is not a secured Broker kernel. |
| Y | This is a secured Broker kernel which is using EntireX Security. |
| U | This is a secured Broker kernel which is using the customer's own written security exits. |
By issuing a KERNELVERS
command, the appropriate value of KERNELSECURITY is
automatically assigned to the control block structure; the user
application does not need to take any further action other than supplying the
correct USER‑ID and
PASSWORD. The application
must maintain the contents of the control block structure for
the duration of communication with the Broker kernel in order to retain the
correct value of the
KERNELSECURITY
field. See Broker ACI Control Block Layout for Assembler | C | COBOL | Natural | PL/I | RPG.
Notes:
USER-ID and TOKEN if
specified). Furthermore, if the application communicates with different Broker
kernels, a separate copy of the Broker control block must be maintained for
each user and each Broker ID.
The application is responsible for assigning the correct user ID and password credentials, except when Trusted User ID (z/OS only) is used.
This information is normally communicated through the LOGON command, since this command initiates the user's session with the Broker kernel.
Starting with a LOGON command is called an Explicit Logon.
An Implicit Logon is possible where the attribute file contains AUTOLOGON=YES
the first command issued by a user does not have to be LOGON,
in which case the application must supply user ID and password credentials for the commands SEND or
REGISTER.
The user ID must be supplied with all commands. The password is required only for the first command and should not be supplied subsequently, except when executing multiple instances of the same application.
Supplying the user ID and password credentials could subsequently be required if the
user times out due to expiration of either
CLIENT-NONACT or
SERVER-NONACT
time limits. If the user context has timed out due to these inactivity limits
being exceeded, one of the following events will occur when the application
attempts to issue the next command:
Application must perform another Explicit Logon with correct credentials in the USER-ID and PASSWORD fields:
AUTOLOGON=NO in the attribute file, or AUTOLOGON=YES and FORCE-LOGON=YES.
Application must supply correct credentials in USER-ID and PASSWORD
fields:
AUTOLOGON=YES in attribute file, FORCE-LOGON=YES not specified in the control block.
Subsequent commands do not require Explicit Logon to be issued.
Application has attempted to transfer control to a different thread,
or process, without correctly transferring the necessary values of USER-ID, TOKEN
and STOKEN:
The application transferring control must make values of USER, TOKEN
and STOKEN available to the application that is delegated to continue thread of
execution.
Application has not correctly maintained the value of security token
(STOKEN) in the control block structure:
The application must maintain the value of STOKEN in order to
communicate securely with Broker kernel without sending PASSWORD with
each command.
The passwords are always communicated in an encrypted format.
Providing user ID and password in ACI-based Programming is described under Broker ACI fields USER‑ID, PASSWORD, LONG-PASSWORD-LENGTH, and the COBOL Example using Long Password.
For user ID and password handling with RPC clients, refer the documentation of the wrapper in use; see EntireX Wrappers in the Designer documentation.
Note:
Caution should be taken when repeating a failed authentication
attempt for both an explicit and an implicit logon. Repeating the attempt
several times can lead to a revocation of the user ID, depending on the
configuration of your security system.
The application is able to change the password by assigning a user ID, password and new password. This must be done at the time of initial authentication or at a subsequent time when authentication is repeated due to timeout. It cannot be done at an arbitrary time by assigning a new password.
The passwords are always communicated in an encrypted format.
For details on how to provide user ID, password and new password, refer to
USER‑ID,
PASSWORD,
NEWPASSWORD,
LONG-PASSWORD-LENGTH and
LONG-NEWPASSWORD-LENGTH under Broker ACI Fields.
EntireX Security automatically generates a non-repeated security token,
which is placed in the ACI control block of the calling application. A unique
security token is generated on behalf of all Broker participants only after
successful authentication has occurred, and is used to ensure nobody can
"tap in" to a participant's session. The calling application is
responsible for maintaining the contents of the control block
structure for the duration of its communication with the Broker kernel in order
to ensure the correct value of security token is available on subsequent
commands. An incorrect value of security token will cause access to be denied.
Security token avoids the need for applications to supply a password except for
presenting this once during the LOGON command, or
the first command (excluding KERNELVERSION), if
AUTOLOGON=YES is defined.
If a LOGOFF command is issued or a participant is
timed out, the password must be reentered so that a new unique security token
can be generated.
An additional benefit of the security token is that it enables an
application to transfer its execution to a different thread or even to a
different process. This requires the application to make available the
following fields of the control block structure to the program
which is delegated to continue the thread of execution:
USER, TOKEN and
STOKEN. However, it is not necessary for the program
transferring control to make its password available.
Note:
If an application is unwilling or does not want to maintain the
security token field (STOKEN) in the control block structure, it is possible for the systems administrator to
configure the following field in the EntireX Security configuration module:
BKISTK=Y. See Ignore Security Token.
This mechanism is available where the application and Broker kernel are executing on the same z/OS machine, and communication is handled locally through Entire Net-Work (Adabas SVC).
Trusted User ID is an optional mechanism with which EntireX Security determines the identity under which the application is executing, without the application having to provide the user ID and password.
The benefit of this mechanism is that application components executing on the same z/OS machine as the Broker kernel never have to provide credentials for authentication. This is because the identity under which execution occurs has already been verified when initially accessing the machine in each of these cases:
online users
batch jobs or started tasks.
All subsequent security authorization checks - for example
SEND
or REGISTER -
are then performed under the known user ID under which the application
executes.
Application components intending to utilize Trusted User ID must provide the user ID only. The value assigned to this field is arbitrary for security purposes but required in order to satisfy execution the stub. No password must be provided if Trusted User ID is used. See the following example:
USER-ID = 'SERVER123' /* arbitrary value: used by Broker but not
significant for security purposes */
PASSWORD = ' ' /* password field must be
set to blanks or binary zeros */
LONG-PASSWORD-LENGTH=0
If a password is provided, EntireX Security will assume that the application does not want to use Trusted User ID. Therefore valid credentials must be supplied as user ID and password in order to perform conventional authentication. This causes EntireX Security to ignore the trusted user ID in favor of the supplied credentials and allows you to override the trusted user ID. Applications must therefore ensure that they do not assign an incorrect user ID or spurious password where "trusted" user ID is implemented.
The CLIENT-ID as conveyed to the server component of the application represents the client's verified user ID,
derived either from valid user ID/password credentials or from the trusted user ID itself.
See also Trusted User ID under EntireX Security under z/OS. Providing user ID and password in ACI-based Programming is described under Broker ACI fields USER‑ID, PASSWORD, LONG-PASSWORD-LENGTH, and the COBOL Example using Long Password.
For user ID and password handling with RPC clients, refer the documentation of the wrapper in use; see EntireX Wrappers in the Designer documentation.
Server applications are able to determine the user ID under which the
partner client is executing by examining the content of the
CLIENT-USERID field exposed in the Broker control block.
Specifically, the CLIENT-USERID field should be examined
on the first RECEIVE command of each new
conversation to obtain the identity of the client. When EntireX Security is
active, the server application is able to rely on the accuracy of the client
user identity since it is derived from the user ID and password credentials
supplied by the client.
See also Trusted User ID (z/OS only) and Verified Client User ID under Configuration Options for Broker in the EntireX Security documentation for z/OS.
FORCE‑LOGON
is used to override the AUTOLOGON feature of the
Broker, with the result that the user does not log on to the Broker kernel
implicitly with the first command issued but instead requires an Explicit Logon.
When this option is used, it is necessary for the client and server to issue
explicit LOGON function calls - even after the
expiration of a client timeout
CLIENT-NONACT
or server timeout
SERVER-NONACT.
See Timeout Parameters.
FORCE-LOGON can be useful in cases where an
Implicit Logon would be undesirable, for example when attempting to
authenticate a user. Specifically, unless the password was communicated with
every command, an implicit logon - after a period of inactivity - would fail
because of a missing password.
When FORCE-LOGON is set - and in the case of
a client/server inactivity timeout - error
00200134
is returned instead of an implicit logon being performed automatically.
Therefore, the specification of FORCE-LOGON can be
used to give the programmer the opportunity to provide the password, which is needed for successful
authentication.
Providing user ID and password in ACI-based Programming is described under Broker ACI fields USER‑ID, PASSWORD, LONG-PASSWORD-LENGTH, and the COBOL Example using Long Password.
For user ID and password handling with RPC clients, refer the documentation of the wrapper in use; see EntireX Wrappers in the Designer documentation.
Client applications are automatically subject to authorization requests if security is installed for EntireX Broker.
For clients, an authorization check based on class, server and service is performed
for the first SEND of a
conversation and on every SEND if there is only one
message in the conversation (CONV‑ID).
Messages are transmitted through to the server application only if the
authorization check is successful; otherwise an ACI response is given to the
client.
For servers, an authorization
check based on class/server/service is performed when the server application
issues a REGISTER command.
The server is allowed to register only if the authorization check is successful;
otherwise an ACI response code is returned to the server application.
The ACI error response codes encountered for authorization failures are: 00080009 | 00080010.
For more information refer to
Resource Profiles in EntireX Security under EntireX Security under z/OS
Authorization Rules (Linux and Windows)