This document provides programming aids relevant to EntireX Security programming. It assumes that the documentation user is familiar with the basics of EntireX Broker ACI programming. It covers the following topics:
Note:
ACI versions 1-7 apply to the communication model client and server
only. ACI version 8 and above apply to the communication models client and
server and publish and subscribe.
See Concepts of 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 EntireX 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
are mismatched, 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
KERNELVERSION
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 EntireX 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
values.
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
KERNELVERSION
command, the appropriate value of KERNELSECURITY is
automatically assigned to the EntireX Broker 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 EntireX Broker control block
structure for the duration of communication with the Broker kernel in order to
retain the correct value of the
KERNELSECURITY
field. See EntireX Broker control block structure:
Assembler |
COBOL |
C |
Natural |
PL/I |
RPG.
Notes:
The application is responsible for assigning the correct
USER-ID
and PASSWORD
values to the EntireX Broker control block structure. This information is
normally communicated through the
LOGON
command, since this command initiates the user's session with the Broker
kernel. 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.
Supplying the USER-ID and
PASSWORD could subsequently be required if the user
times out due to expiration of either
CLIENT-NONACT,
SERVER-NONACT,
PUBLISHER-NONACT
or SUBSCRIBER-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 attribute file, or if
AUTOLOGON=YES and
FORCE-LOGON=YES
in EntireX Broker control block
Application must supply correct credentials in USER-ID and PASSWORD fields:
AUTOLOGON=YES
in attribute file,
FORCE-LOGON=YES not specified in
the EntireX Broker 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 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 EntireX Broker control block structure:
The application must maintain the value of STOKEN in order to communicate securely with Broker kernel whilst avoiding sending PASSWORD with each command.
The application is able to change the password by assigning both PASSWORD and NEWPASSWORD fields of the EntireX Broker control block structure. 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 the NEWPASSWORD field.
The PASSWORD and NEWPASSWORD fields are always communicated in an encrypted format.
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 EntireX Broker 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 EntireX Broker 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 EntireX Broker
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 in the EntireX Security
documentation.
This mechanism is available where at least one application and Broker kernel are executing on z/OS and communication is 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 in the Broker control block.
The benefit of this mechanism is that application components executing on z/OS 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:
on-line 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 assign the Broker control block field USER-ID only. The value assigned to this field is arbitrary for security purposes but required in order to satisfy execution the stub. The application is not allowed to assign any value to PASSWORD if Trusted User ID is used. The following example is given:
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 */
If the application does not clear the PASSWORD field, EntireX Security will assume that the application does not want to use Trusted User ID. Therefore valid credentials must be supplied to the USER-ID and PASSWORD fields in order to perform conventional authentication.
Note:
Requests directed through the Relay Manager are not able to use the
Trusted User ID feature for security. Therefore, it is necessary for the
application to supply actual user ID and password information when
communicating from a z/OS application with a secured z/OS Broker kernel.
See also Configuration Options for Broker under z/OS.
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 and Verified Client User ID.
This topic does not apply to the publish-and-subscribe communication
model since this requires an explicit logon and cannot use
AUTOLOGON.
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 Using Broker 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 ACI field
PASSWORD, which is needed for successful
authentication.
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 Integrated Authentication Framework (IAF) is a token-based infrastructure that enables Software AG's enterprise single sign-on. In addition, it allows usage of a configurable authentication system (user database) with Software AG products across platforms.
Applications that create publications are subject to authorization
requests under EntireX Security. For every new publication, an authorization
check is performed based on the
TOPIC.
Publications are transmitted to subscriber applications only if the
authorization check is successful; otherwise an ACI response is returned to the
application issuing the
SEND_PUBLICATION
command.
Subscriber applications are subject to an authorization check if
security is installed for EntireX Broker. An authorization check based on the
topic is performed when the subscriber application issues a
SUBSCRIBE
command. The application is allowed to subscribe only if the authorization
check is successful; otherwise an ACI response code is returned to the
subscriber. Similarly, if the administrator performs third-party subscription
or unsubscription on behalf of a subscriber using command and information
services (CIS), an
authorization check is made, based on the topic.
The ACI error response codes encountered for authorization failures are: 00080009 | 00080010.
See also Publish-and-Subscribe Example and Writing Applications: Publish and Subscribe.
Client applications are automatically subject to authorization requests if security is installed for EntireX Broker.For UNIX and Windows, see Authorization Rules.
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=NONE).
Messages are transmitted through to the server application only if the
authorization check is successful; otherwise an ACI response is given to the
client.
Server applications are automatically subject to authorization requests
if security is installed for EntireX Broker. For UNIX and Windows, see
Authorization
Rules. 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. In a similar way, if the administrator terminates a server through
Command and Information Services (CIS), an authorization check is made based on
the class/server/service.
The ACI error response codes encountered for authorization failures are: 00080009 | 00080010.
See also Client-and-Server Example and Writing Applications: Client and Server.
For UNIX and Windows, Broker authorization checks are made using a set of definitions maintained in an LDAP repository (Lightweight Directory Access Protocol). Authorization rules are the mechanism by which authorization checks are performed for UNIX and Windows. For more information see Configuring Authorization Rules under UNIX | Windows.
If your applications are using ACI versions 1 to 7, you must decide at installation time whether your applications are going to exchange encrypted data. Your administrator will have configured parameters of EntireX Security to indicate encryption is performed. If your environment is configured in this way, your applications will then always communicate using encryption. Therefore it is not possible for applications to communicate with several Broker kernels, some of which are secured and some of which are not. To achieve greater flexibility, ACI version 8 provides the application with the choice of encrypting the data on a per-message basis as described below.
For ACI version 8 the application can assign the following values to the ENCRYPTION-LEVEL field of the EntireX Broker control block structure. Encryption of the message data occurs separately from any configuration settings made by the administrator at installation time.
| Value | Description |
|---|---|
| 0 | No encryption of message data. |
| 1 | Message data is encrypted between the application (Broker stub) and the Broker kernel. |
| 2 | Message data is encrypted between the application (Broker stub) and the Broker kernel. |
Note:
The application is able to control encryption of
SEND
/ RECEIVE
buffer using the ENCRYPTION-LEVEL field for ACI version
8 and above only. For ACI versions 1 to 7, the application is able to specify
only the requirements to encryption as described below, rather than activate
encryption programmatically.
ENCRYPTION-LEVEL can only be used in conjunction with EntireX Security and is not compatible when SSL transport is utilized.
For ACI version 7 and below, ENCRYPTION-LEVEL specifies the requirements for encryption for messages exchanged between client and server. In this way, client and server applications determine whether or not they require encryption to be configured. If the configuration does not match the requirement, an ACI return code is returned to the application and no messages are exchanged. This is referred to as "verification of client server connection" and is described below. See also error codes: 00200401 | 00200419 | 00200420 | 00200421 | 00200422.
For ACI version 8 and above, the ENCRYPTION-LEVEL field in the ACI control block is also used to activate encryption programmatically, thereby giving both client-server and publish-and-subscribe applications full control over encryption, relieving the administrator of configuration tasks.
The requirements for encryption can be set in the following locations:
Broker attribute file using the per-service attribute ENCRYPTION-LEVEL (set by administrator)
Broker control block field ENCRYPTION-LEVEL (set by application)
| Level | Description | |
|---|---|---|
| 0 | If an application component sets ENCRYPTION-LEVEL=0, no encryption is enforced. | |
| ACI version 1-7 |
Encryption will occur only if one of the following is set:
|
|
| ACI version 8 |
|
|
| 1 | If an application component sets ENCRYPTION-LEVEL=1, encryption of the send and/or receive data between this application component and the Broker kernel is enforced. | |
| ACI version 1-7 | For an application component that sets
ENCRYPTION-LEVEL=1,
|
|
| ACI version 8 |
|
|
| 2 | If an application component sets ENCRYPTION-LEVEL=2, encryption of the send and/or receive data between this application and the partner application component is enforced. This includes the route of the data from this application component, through the Broker kernel, and to the partner application component. | |
| ACI version 1-7 | For both application components,
|
|
| ACI version 8 | Encryption is automatically activated by the application if ENCRYPTION-LEVEL specified in the EntireX Broker control block is non-zero. The partner application must also specify a non-zero value for the ENCRYPTION-LEVEL. | |
Verification of client/server connection
When the Broker makes a connection between a client and a server, it checks the following:
if the client has ENCRYPTION-LEVEL=2, the server must have ENCRYPTION-LEVEL=2.
if the server has ENCRYPTION-LEVEL=2, the client must have ENCRYPTION-LEVEL=2.
Broker Attribute File
The value for the ENCRYPTION-LEVEL in the Broker attribute file must always match the EL= value of the server. See Service-specific Attributes in Broker attribute file.
When an encryption level is specified in the Broker attribute file, the program that registers this service must also specify the same encryption level.
For ACI version 8 or above, it is not necessary to specify the value of the ENCRYPTION-LEVEL in the Broker attribute file. This avoids updating all the attribute file service definitions when migrating to EntireX Broker version 8, in which new functionality to activate encryption through Broker control block field ENCRYPTION-LEVEL was introduced. However, if ENCRYPTION-LEVEL is specified in the attribute file, it will be honored as described above.