EntireX Version 9.7
 —  EntireX Broker ACI Programming  —

Writing Applications using EntireX Security

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:

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.


General Programming Considerations

See Overview of EntireX Security for overview of concepts and installation.

ACI Versions and Security

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.

Is Broker Kernel Secure?

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 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 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:

  1. Only applications using ACI version 7 or above can determine whether Broker is executing with security. In version 8 or above, the necessary information is automatically set up in the Broker control block.
  2. We strongly recommend that applications maintain a separate copy of the Broker control block for each user ID (or 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.

Top of page

Authentication

Authentication with User ID and Password

The application is responsible for assigning the correct USER-ID and PASSWORD values to the 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.

Reason for ACI Error Action

The application is able to change the password by assigning both PASSWORD and NEWPASSWORD fields of the 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.

Role of Security Token (STOKEN) during Authentication

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.

Trusted User ID

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. See Trusted User ID.

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:

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.

See also Trusted User ID.

Client User ID

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.

FORCE-LOGON

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

Top of page

Authorization

Publish and Subscribe

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. See Writing Applications: Command and Information Services.

The ACI error response codes encountered for authorization failures are: 00080009 | 00080010.

See also publish-and-subscribe example under Resource Profiles in EntireX Security and Writing Applications: Client and Server.

Client and Server

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). 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 under Resource Profiles in EntireX Security and Writing Applications: Client and Server.

Authorization Rules

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.

Top of page

Encryption

Introduction

Encryption of the message data with the EntireX Security encryption is configured in the broker and in client and server applications. The ENCRYPTION-LEVEL attribute configured in the broker attribute file is a service-specific attribute. Allowed values are 0, 1, and 2. Using ENCRYPTION-LEVEL 1 or 2 requires SECURITY=YES in the DEFAULTS = BROKER section.

Encryption Level Description
0 No encryption requested, but allowed.
1 Encryption for server requested, client can encrypt.
2 Encryption for client and server requested.

Example:

DEFAULTS = SERVICE
  CONV-NONACT      = 5M
  DEFERRED         = YES
  SERVER-NONACT    = 10M
  ENCRYPTION-LEVEL = 2
  CLASS = RPC,   SERVER = SRV1, SERVICE = CALLNAT, TRANSLATION = SAGTCHA

Applications can configure the encryption level by setting the broker ACI field ENCRYPTION-LEVEL or using the methods of the Java ACI. Allowed values are 0, 1, and 2. 0 does not encrypt the message, 1 encrypts the message to the broker, while 2 encrypts the message to the broker and requests that the partner application also encrypts the message. To guarantee end-to-end encryption from client to server, use encryption level 2.

The broker controls the encryption and issues one of the error codes 00200401 | 00200419 | 00200420 | 00200421 | 00200422 if encryption levels do not match.

In all cases encryption requires broker connections secured with EntireX Security. Broker returns error code 00210402 if this is violated.

Encryption behavior is slightly different depending on whether the application is Java-based or not. For non-Java-based applications, the behavior depends on the ACI version. These differences are described below.

Encryption for non-Java Applications

For non-Java applications, Encryption behavior depends on the ACI version:

Note:
In the sections below, "EL" refers to the field ENCRYPTION-LEVEL in the ACI control block.

ACI Version 8 and Above

Encryption is configured by the application per message. The table shows allowed combinations of ENCRYPTION-LEVEL and EL.

ENCRYPTION-LEVEL in Broker Attribute File Server Client
0 (or undefined) EL= 0 or 1 EL= 0 or 1
1 EL= 1 EL= 0 or 1
2 EL= 2 EL= 2

ACI Version 6 and 7

Encryption is configured by installing the security exit for the application (security exit is secuexit.dll on windows, secuexit.so on UNIX, SECUEXI0 on z/OS) and the environment variable NA2_BKPRIV (or ETB_ENCRPYT) is set to 1. The table shows allowed combinations of ENCRYPTION-LEVEL and EL.

ENCRYPTION-LEVEL in Broker Attribute File Server Client
0 (or undefined) EL= 0 EL= 0 or 1
1 EL= 1 EL= 0 or 1
2 EL= 2 EL= 2

ACI Version 1 to 5

Encryption is configured by installing the security exit for the application (security exit is secuexit.dll on windows, secuexit.so on UNIX, SECUEXI0 on z/OS) and the environment variable NA2_BKPRIV (or ETB_ENCRPYT) is set to 1. Only ENCRYPTION-LEVEL in the broker attribute file is available. Field EL for the stub is not available.

Encryption for Java-based Applications (ACI and RPC)

On the Broker object, use the methods setSecurity(...) or useEntireXSecurity(...) to enable EntireX Security and set the encryption level. See Broker in the Javadoc for details.

RPC Servers

For RPC servers, the encryption level is set in the configuration. See documentation of the configuration for the specific RPC server.

RPC Clients

Top of page