Sample security exits are a user-written security solution for use only in exceptional processing situations. Example: If your organization wants to access its own user-written security system when operating EntireX Broker.

This document covers the following topics:

• Sample Security Exits as Alternative Security Solution

• Lightweight USRSEC

• Implementation of Sample Security Exits

• Glossary of Terms

See also Which EntireX Security Solution?

---

Sample Security Exits as Alternative Security Solution

Software AG intends sample security exits for Broker security to be only an alternative to EntireX Security, which is Software AG's standard security solution. Do not mix these two security solutions: do not use a stub secured with a sample exit against a kernel secured with EntireX Security or vice versa.

Most organizations that use Software AG's EntireX choose EntireX Security instead of sample security exits for Broker security. If your organization is deploying distributed computer systems encompassing mainframe, UNIX and Windows environments, you will use EntireX Security instead of sample security exits for Broker security.

Lightweight USRSEC

For compatibility with previous versions (API level 3 and below), a "lightweight" security exit is supplied as load module USRSEC in library EXX912.LOAD for Broker under z/OS. This "lightweight" version of USRSEC performs authentication only against RACF, CA ACF2 and CA Top Secret. It does not include the full functionality of the standard EntireX Security installation of USRSEC (e.g. resource authorization, etc.). The "lightweight" version of USRSEC does not require any security components, i.e. SECUEXIT, to be installed into the application (stub) environment. If you are using ACI version 1 to 7 and you intend to use the "lightweight" version of USRSEC, please ensure you do not have any security components installed into the application (stub) environment.

Implementation of Sample Security Exits

Sample security exits are a user-written security solution for use only in exceptional processing situations. The diagram below depicts the data flow which users can implement in their own user exits for Broker security.

Description of Steps in Data Flow

1. Broker stub calls security exit SECUEXIT, if present.

2. Security exit SECUEXIT encrypts the password and optionally the application data. See Encryption / Decryption. SECUEXIT accesses the ACI control block and the SEND/RECEIVE buffers. SECUEXIT returns call to the broker stub.

3. Broker stub communicates the call to the broker kernel.

4. Broker kernel calls security exit USRSEC for each specific event type:

   • Create security context for user; authentication is usually performed in this event. See Authentication.

   • Destroy security context for user.

   • Perform authorization for server to register a service. See Authorization.

   • Perform authorization for client to send request.

   • Optionally perform encryption of application data. See note below.

   • Optionally perform decryption of application data. See note below.

   • Perform optional processing if a user acquires a new physical user ID. Re-authentication can also be performed.

   • Perform optional processing if the value of a user's ACI security token changes. Re-authentication can also be performed.

5. Security exit USRSEC passes call to broker kernel.

6. Broker kernel communicates the call to the broker stub of the partner application.

7. The broker stub calls SECUEXIT. SECUEXIT determines whether decryption is to be performed, if correspondingly coded by user.

8. Security exit SECUEXIT returns call to broker stub.

Notes:

1. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.
2. See Using Sample Security Exits for Broker Security. This section describes implementation issues and how to use sample security exits on the operating system where Broker executes.

Glossary of Terms

• Authentication

• Authorization

• Broker and Kernel

• Broker Stub

• Encryption / Decryption

• Exits

Authentication

Authentication verifies whether the identity specified by the user ID in the ACI control block is the actual identity. Authentication is usually performed by checking the user's ID and password against a security system. The details of this check are specific to the specific operating system and security system.

Authentication is not needed with every call. It is required when the user's security context is created within the Broker kernel; it is also required, optionally, if the user's physical user ID or ACI security token changes.

Authorization

Authorization can be performed when:

• a client issues a request to a service in the case of the first SEND command in a conversation, or of each SEND command if CONV-ID=NONE;

• a server registers a service to the Broker;

Broker and Kernel

It is the location of the Broker kernel that determines the point at which the authentication and authorization checks can be performed. Authentication and Authorization can be performed in the kernel exit USRSEC.

See List of Components per Platform for where Broker kernel is supported.

Broker Stub

In EntireX Broker, a module that implements the ACI (Advanced Communication Interface) is commonly referred to as broker stub or stub. Stubs are installed on the client and the server side.

See Transport: Broker Stubs and APIs for where Broker stubs are supported.

Encryption / Decryption

Encryption is the process by which the information or data being sent back and forth between two computers (including the password submitted when logging on) is encoded, shielding it from view by unauthorized persons.

In the case of user-written security exits, encryption/decryption can be implemented in:

• the stub security exits (SECUEXIT or ETBUPRE / ETBUEVA);

• the kernel security exit (USRSEC).

Exits

• Kernel Exit USRSEC
  USRSEC is the name of the security exit which is invoked if SECURITY=YES is specified in the attribute file.

  In the case of user-written security exits, this exit will include functionality for authentication, authorization and optionally encryption/decryption ⁽²⁾.

• Stub Exit SECUEXIT
  SECUEXIT is the stub security exit for use with the broker stub for transports SSL and TCP. See Implementing Security Exits under z/OS | UNIX | Windows This module is executed during a Broker command if SECUEXIT is present in the path of execution.

  In the case of user-written security exits, this exit can optionally include functionality for encryption/decryption ⁽²⁾.

• Stub Exit ETBUPRE / ETBUEVA
  ETBUPRE / ETBUEVA are the stub security exits for use with the broker stub under z/OS for transport NET. See Implementing Security Exits under z/OS. These modules are executed during a Broker command if they are linked to the stub.

Notes:

1. See also List of Components per Platform for where Broker kernel and Broker Stub are supported.
2. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.