EntireX Broker ACI for Natural

ACI stands for Advanced Communication Interface. ACI-based programming is the base technology of EntireX. It uses a traditional Application Programming Interface (API) approach for conducting client/server and peer-to-peer dialog between distributed processes.

This document describes the EntireX Broker ACI from the perspective of the programming language Natural. It covers the following topics:

See also EntireX Broker ACI Programming for an introduction to ACI programming, a description of ACI fields and functions, and information on writing ACI applications.


Call Format

Calls to EntireX Broker use the following arguments:

  1. The ACI control block is the first argument.

  2. The send buffer is the second argument.

  3. The receive buffer is the third argument.

  4. The error text buffer is the last argument. It can provide a short text with the error code, if desired. Sufficient buffer length must be supplied to allow the standard 40-byte-long message to be returned by EntireX Broker. For ACI version 9 and above, the error text buffer can be greater than 40 bytes as specified in the ACI field ERRTEXT-LENGTH.

The send buffer and the receive buffer must always be provided. If they are not required by the selected EntireX Broker function, you can set them as short A1 fields.

The API is called with a statement such as the following for all platforms:

CALL 'BROKER' #ETBCB  #SEND-AREA #RECEIVE-AREA #ERROR-TEXT

Natural applications can access the last four bytes of the error code through the RET function.

If 00000000 (zeros) are returned in the ERROR-CODE field in the EntireX Broker control block, the operation has been performed successfully. However, function results other than 00000000 (zeros) do not necessarily indicate an error. See Error Handling.

Note for UNIX and Windows

On UNIX and Windows, the length of fields #SEND-AREA and #RECEIVE-AREA cannot exceed 65535. If you want to send and/or receive more data, redefine #SEND-AREA and/or #RECEIVE-AREA with a value of, say, A1 and use these fields in the CALL statement. For example:

01 #SEND-AREA (A65536)
01 REDEFINE #SEND-AREA
02 #SEND-AREA-R (A1)
01 #RECEIVE-AREA (A65536)
01 REDEFINE #RECEIVE-AREA
02 #RECEIVE-AREA-R (A1)
.
CALL 'BROKER' #ETB-CB #SEND-AREA-R #RECEIVE-AREA-R #ERROR-TEXT

Broker ACI Control Block Layout

The following table shows the Broker fields in the order of the physical layout of the Broker ACI control block and provides a brief description of each field. See the actual copycode for Natural below in Broker ACI Control Block Data Area.

See Broker ACI Fields for more information.

Broker ACI Field Natural Definition Description /
Related Information
API
Vers.
Notes
API-TYPE #TYPE (I1) API type. See API-TYPE and API-VERSION. 1  
API-VERSION #VERSION (I1) API version. 1  
FUNCTION #FUNCTION (I1) See Broker ACI Functions to perform Broker function. 1  
OPTION #OPTION (I1) See Option Descriptions. 1  
  #RESERVED (I4/4) Reserved for future use. 1 1
SEND-LENGTH #SEND-LEN (I4) Send length. See Using Send and Receive Buffers. 1  
RECEIVE-LENGTH #RECEIVE-LEN (I4) Receive length. 1  
RETURN-LENGTH #RETURN-LEN (I4) Return length. 1  
ERRTEXT-LENGTH #ERRTEXT-LEN (I4) Error text length. 1  
BROKER-ID #BROKER-ID (A32) Broker ID. See Using the Broker ID in Applications. 1  
SERVER-CLASS
SERVER-NAME
SERVICE
#SERVER-CLASS (A32)
#SERVER-NAME (A32)
#SERVICE (A32)
Service. See Control Block Fields and Verbs. 1 3,5
USER-ID #USER-ID (A32) User ID. See USER-ID and TOKEN. 1  
PASSWORD #PASSWORD (A32) Password. See Authentication. 1 4,5
TOKEN #TOKEN (A32) Reconnection token. See USER-ID and TOKEN. 1 3,5
SECURITY-TOKEN #SECURITY-TOKEN (B32) Security token. See Role of Security Token (STOKEN) during Authentication. 1 4,5
CONV-ID #CONV-ID (A16) Conversation ID. See Conversational and Non-conversational Mode. 1 3,5
WAIT #WAIT (A8) Wait value. See Blocked and Non-blocked Broker Calls. 1 3,5
ERROR-CODE #ERROR-CODE (A8) Error code. See Error Handling and Error Messages and Codes. 1  
ENVIRONMENT #ENVIRONMENT (A32) Pass additional information to Translation User Exit. For more information see ACI field ENVIRONMENT. 1 3,5
ADCOUNT #ADCOUNT (I4) Attempted delivery count. See Writing Applications: Units of Work. 2  
USER-DATA #USER-DATA (B16) Conversation User Data. See Managing Conversation Contexts. 2 3,5
Not used. #MSG-ID (B32) Message ID. 2 4,5
Not used. #MSG-TYPE (A16) Message type. 2 3,5
NEWPASSWORD #NEWPASSWORD (B32) New password. See Changing your Password. 2 4,5
Not used. #ADAPTER-ERROR (A8) Adapter error. 2  
CLIENT-UID #CLIENT-UID (A32) Client user ID. See Client User ID. 2  
CONV-STAT #CONV-STAT (I1) Conversation status. See Conversational and Non-conversational Mode. 2  
STORE #STORE (I1) Persistence or non-persistence of a UOW. See Writing Applications: Units of Work. 2  
UOWSTATUS #UOWSTATUS (I1) UOW Status. 3 3,5
UWTIME #UOWTIME (A8) UOW lifetime. 3 3,5
UOWID #UOWID (A16) UOW unique identifier. 3 3,5
USTATUS #USERSTATUS (A32) User status. 3  
UOW-STATUS-PERSIST #UOWSTATUSPERSIST (I1) Multiplier for persistent status lifetime. 3 2
LOCALE-STRING #LOCS (A40) Locale string. To be used to override or provide a codepage name to tell the broker the encoding of the data. For more information see ACI field LOCALE-STRING. 4  
FORCE-LOGON #FLOG (A1) Override Broker AUTOLOGON. See FORCE-LOGON. See Writing Applications using EntireX Security. 6  
  #ENCL (I1) Encryption level. Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See Using the Broker ACI with SSL/TLS. 6 2
KERNELSECURITY #KERNELSECURITY (A1) Kernel security. See Is Broker Kernel Secure?. 7  
COMMITTIME #COMMITTIME (A17) Commit time. See Writing Applications: Units of Work. 7  
COMPRESSLEVEL #COMPRESSLEVEL (A1) Compression level. See Data Compression. 7  
UWSTAT-LIFETIME #UWSTATUSLIFE (A8) Add value for persistent status lifetime. See UWSTAT-LIFETIME. 8  
CLIENT-ID #CLIENT-ID (I4) Returns to a server application the unique instance number of a client application. It is returned on receipt of a message (RECEIVE or SEND with WAIT). See also Tracing. 9  
LOG-COMMAND #LOG-COMMAND (A1) Log the current command. See also Programmatically Turning on Command Logging. 9  
CREDENTIALS-TYPE #CREDENTIALS-TYPE (A1) Indicates the credentials type to be used to authenticate a user. The default is to use user ID and password. 9  
VARLIST-OFFSET #VARLIST-OFFSET (I4) Internal Software AG field. 10  
LONG-BROKER-ID-LENGTH #LONG-BROKER-ID-LENGTH (I4) See LONG-BROKER-ID-LENGTH. 10  
MESSAGE-ID #MESSAGE-ID (A64) See Unique Message ID under Broker ACI Functions. 11  
CORRELATION-ID #CORRELATION-ID (A64) CORRELATION-ID. 11  
USE-SPECIFIED-MESSAGE-ID #USE-SPECIFIED-MESSAGE-ID (I1) Use supplied MESSAGE-ID for SEND. 11  
USE-SPECIFIED-CORRELATION-ID #USE-SPECIFIED-CORRELATION-ID (I1) Send supplied CORRELATION-ID to Broker. 11  
  #RESERVED6 (A3) Reserved for future use. 11  
  #RESERVED7 (I4) Reserved for future use. 11  
LONG-PASSWORD-LENGTH #LONG-PASSWORD-LENGTH(I4) Length of long password. See Authentication. 12  
LONG-NEWPASSWORD-LENGTH #LONG-NEW-PASSWORD-LENGTH(I4) Length of long new password. See Changing your Password. 12  

Notes:

  1. Reserved for future use.
  2. You must set this field to a low value (X'00') if you do not intend to use it.
  3. The field is transmitted up to the first blank or low value (X'00'). It is not transmitted if the first character is a blank or a low value (X'00').
  4. All trailing low values (X'00') are truncated. The field is not transmitted if the entire field is a low value (X'00').
  5. If fields are not needed for a specific command function, suppress their transmission by initializing them to blanks or low value (X'00').

Broker ACI Control Block Data Area

Start of instruction setTo produce a Natural LDA object

  1. Cut and paste the data area below into a Natural program source.

  2. Append it with an END statement and STOW the module.

  3. Open the LDA editor and incorporate the data area using line command .i(program source-name).

  *  - -------------------------------- - ---------- --------------------------
  *    Product .....: EntireX Broker
  *    Copyright ...: (c) Software AG      1997-2021 All rights reserved.
  *    VERSION .....: ACI VERSION 12
  *    Description .: Natural language           ACI control block definitions.
  *
  *                   To call broker             use CALL 'BROKER' #ETBCB
  *                   To set CB fields           use ASSIGN #SDPA-CB.#xxxx = ..
  *
  *    * * * * * * * * * * * * * * * *  *  Attention * * * * * * * * * * * * *
  *    These statements do not work to               CALL 'BROKER' #SDPA-CB(*)
  *    call the broker                               CALL 'BROKER' #SDPA-API ..
  *    * * * * * * * * * * * * * * * *  *  Attention * * * * * * * * * * * * *
  *
  *  - -------------------------------- - ---------- --------------------------
  *    EntireX Broker API Function                   Constants ----------------
I    1 #FCT-SEND                        I          1
I    1 #FCT-RECEIVE                     I          1
I    1 #FCT-UNDO                        I          1
I    1 #FCT-EOC                         I          1
I    1 #FCT-REGISTER                    I          1
I    1 #FCT-DEREGISTER                  I          1
I    1 #FCT-VERSION                     I          1
I    1 #FCT-LOGON                       I          1
I    1 #FCT-LOGOFF                      I          1
I    1 #FCT-SET                         I          1
I    1 #FCT-GET                         I          1
I    1 #FCT-SYNCPOINT                   I          1
I    1 #FCT-KVER                        I          1
I    1 #FCT-LOCT                        I          1
I    1 #FCT-SSLP                        I          1
I    1 #FCT-SEND-P                      I          1
I    1 #FCT-RCVE-P                      I          1
I    1 #FCT-SUBS-P                      I          1
I    1 #FCT-USUB-P                      I          1
I    1 #FCT-CNTL-P                      I          1
I    1 #FCT-RPLY-E                      I          1
I    1 #FCT-GET-MESSAGE-ID              I          1
  *
  *    EntireX Broker API Option                     Constants ----------------
I    1 #OPT-MSG                         I          1
I    1 #OPT-HOLD                        I          1
I    1 #OPT-IMMED                       I          1
I    1 #OPT-QUIESCE                     I          1
I    1 #OPT-EOC                         I          1
I    1 #OPT-CANCEL                      I          1
I    1 #OPT-LAST                        I          1
I    1 #OPT-NEXT                        I          1
I    1 #OPT-PREVIEW                     I          1
I    1 #OPT-COMMIT                      I          1
I    1 #OPT-BACKOUT                     I          1
I    1 #OPT-SYNC                        I          1
I    1 #OPT-ATTACH                      I          1
I    1 #OPT-DELETE                      I          1
I    1 #OPT-EOCCANCEL                   I          1
I    1 #OPT-QUERY                       I          1
I    1 #OPT-SETSTATUS                   I          1
I    1 #OPT-ANY                         I          1
I    1 #OPT-TERMINATE                   I          1
I    1 #OPT-DURABLE                     I          1
I    1 #OPT-CHECKSVC                    I          1
  *
  *    EntireX Broker Conversation                   Status Constants ---------
I    1 #CONVSTAT-NEW                    I          1
I    1 #CONVSTAT-OLD                    I          1
I    1 #CONVSTAT-NONE                   I          1
  *
  *    EntireX Broker Store                          Constants ----------------
I    1 #STORE-OFF                       I          1
I    1 #STORE-BROKER                    I          1
I    1 #STORE-ON                        I          1
  *
  *    EntireX Broker Status                         Constants ----------------
I    1 #STAT_OFF                        I          1
I    1 #STAT_STORED                     I          1
I    1 #STAT_DELIVERY-ATTEMP            I          1
I    1 #STAT_DELIVERED                  I          1
I    1 #STAT_PROCESSED                  I          1
I    1 #STAT_DEAD                       I          1
  *
  *    EntireX Broker UOW Status                     Constants ----------------
I    1 #RECV-NONE                       I          1
I    1 #RECEIVED                        I          1
I    1 #ACCEPTED                        I          1
I    1 #DELIVERED                       I          1
I    1 #BACKEDOUT                       I          1
I    1 #PROCESSED                       I          1
I    1 #CANCELLED                       I          1
I    1 #TIMEOUT                         I          1
I    1 #DISCARDED                       I          1
I    1 #RECV-FIRST                      I          1
I    1 #RECV-MIDDLE                     I          1
I    1 #RECV-LAST                       I          1
I    1 #RECV-ONLY                       I          1
I    1 #POSTPONED                       I          1
  *
  *    EntireX Broker Locale String                  Constants ----------------
I    1 #ETB-CODEPAGE-USE-DEFAULT        A          5
  *
  *    EntireX Broker Force Logon                    Constants ----------------
I    1 #FLOG-YES                        A          1
I    1 #FLOG-NO                         A          1
I    1 #FLOG-S                          A          1
  *
  *    EntireX Broker                                Constants ----------------
I    1 #ENCLEVEL-NONE                   I          1
I    1 #ENCLEVEL-TO-BROKER              I          1 /* deprecated
I    1 #ENCLEVEL-TO-TARGET              I          1 /* deprecated
  *
  *    EntireX Broker KernelSecurity                 Constants ----------------
I    1 #KERNEL-SECURITY-NO              A          1
I    1 #KERNEL-SECURITY-YES             A          1
I    1 #KERNEL-SECURITY-USER            A          1
I    1 #KERNEL-SECURITY-LIGHT           A          1
  *
  *    EntireX Broker Compression Level              Constants ----------------
I    1 #COMPRESS-LEVEL-0                A          1
I    1 #COMPRESS-LEVEL-1                A          1
I    1 #COMPRESS-LEVEL-2                A          1
I    1 #COMPRESS-LEVEL-3                A          1
I    1 #COMPRESS-LEVEL-4                A          1
I    1 #COMPRESS-LEVEL-5                A          1
I    1 #COMPRESS-LEVEL-6                A          1
I    1 #COMPRESS-LEVEL-7                A          1
I    1 #COMPRESS-LEVEL-8                A          1
I    1 #COMPRESS-LEVEL-9                A          1
I    1 #COMPRESS-LEVEL-NO               A          1
I    1 #COMPRESS-LEVEL-YES              A          1
  *
  *    EntireX Broker Credential Type                Constants ----------------
I    1 #CREDENTIAL-TYPE-UID-PWD         I          1
  *
  *    EntireX Broker API Control Block              Definition ---------------
  *
     1 #SDPA-CB                         B        128 (8)
  R  1 #SDPA-CB                                      /* V1
     2 #ETBCB                           A          1 /* V1 to pass CB to stub
  R  1 #SDPA-CB
     2 #ETBAPI                          A          1 /* V1 don't use/deprecated
  R  1 #SDPA-CB
     2 #SDPA-API                                     /* V1 don't use/deprecated
     3 #TYPE                            I          1 /* V1 type of ETBCB
  R  3 #TYPE
     4 #API-TYPE                        I          1 /* V1 alternative name
     3 #VERSION                         I          1 /* V1 version of ETBCB
  R  3 #VERSION
     4 #API-VERSION                     I          1 /* V1 alternative name
     3 #FUNCTION                        I          1 /* V1 function
     3 #OPTION                          I          1 /* V1 option
     3 #RESERVED                        I          4 (4) /* V1 reserved
     3 #SEND-LEN                        I          4 /* V1 length of send data
  R  3 #SEND-LEN
     4 #SEND-LENGTH                     I          4 /* V1 alternative name
     3 #RECEIVE-LEN                     I          4 /* V1 max. len. rec. data
  R  3 #RECEIVE-LEN
     4 #RECEIVE-LENGTH                  I          4 /* V1 alternative name
     3 #RETURN-LEN                      I          4 /* V1 length of rec.data
  R  3 #RETURN-LEN
     4 #RETURN-LENGTH                   I          4 /* V1 alternative name
     3 #ERRTEXT-LEN                     I          4 /* V1 max. len. error text
  R  3 #ERRTEXT-LEN
     4 #ERRTEXT-LENGTH                  I          4 /* V1 alternative name
     3 #BROKER-ID                       A         32 /* V1 target broker ID
     3 #SERVER-CLASS                    A         32 /* V1 part of service name
     3 #SERVER-NAME                     A         32 /* V1 part of service name
     3 #SERVICE                         A         32 /* V1 part of service name
     3 #USER-ID                         A         32 /* V1 user ID of caller
     3 #PASSWORD                        B         32 /* V1 password of caller
  R  3 #PASSWORD
     4 #PASSWORD-C                      A          1 (32)
     3 #TOKEN                           A         32 /* V1 special purposes
     3 #SECURITY-TOKEN                  B         32 /* V1 security purposes
  R  3 #SECURITY-TOKEN
     4 #SECURITY-TOKEN-C                A          1 (32)
     3 #CONV-ID                         A         16 /* V1 conv./non-conv.
     3 #WAIT                            A          8 /* V1 blocked/non-blocked
     3 #ERROR-CODE                      A          8 /* V1 error class/number
  R  3 #ERROR-CODE
     4 #ERROR-CLASS                     N          4 /* V1 error class
     4 #ERROR-NR                        N          4 /* V1 error number
  R  3 #ERROR-CODE
     4 #ERROR-CODE-CLASS                N          4 /* V1 alternative name
     4 #ERROR-CODE-NR                   N          4 /* V1 alternative name
     3 #ENVIRONMENT                     A         32 /* V1 translation purposes
     3 #ADCOUNT                         I          4 /* V2 attempt deliv. count
     3 #USER-DATA                       B         16 /* V2 user data field
  R  3 #USER-DATA
     4 #USER-DATA-C                     A          1 (16)
     3 #MSG-ID                          B         32 /* V2 not used by broker
  R  3 #MSG-ID
     4 #MSG-ID-C                        A          1 (32)
     3 #MSG-TYPE                        A         16 /* V2 not used by broker
     3 #PTIME                           A          8 /* V2 not used by broker
     3 #NEWPASSWORD                     B         32 /* V2 new passwd of caller
  R  3 #NEWPASSWORD
     4 #NEWPASSWORD-C                   A          1 (32)
     3 #ADAPTER-ERROR                   A          8 /* V2 not used by broker
     3 #CLIENT-UID                      A         32 /* V2 userid for security
     3 #CONV-STAT                       I          1 /* V2 conversation status
     3 #STORE                           I          1 /* V2 flag for saving data
     3 #STATUS                          I          1 /* V2 not used by broker
     3 #UOWSTATUS                       I          1 /* V3 UOW's status
  R  3 #UOWSTATUS
     4 #UOWSTA                          I          1 /* V3 don't use/deprecated
     3 #UOWTIME                         A          8 /* V3 UOW lifetime in sec.
  R  3 #UOWTIME
     4 #UOWTIM                          A          8 /* V3 don't use/deprecated
     3 #UOWID                           A         16 /* V3 UOW ID
     3 #USERSTATUS                      A         32 /* V3 user status
  R  3 #USERSTATUS
     4 #USRSTA                          A         32 /* V3 don't use/deprecated
     3 #UOWSTATUSPERSIST                I          1 /* V3 UOW st. persist flag
  R  3 #UOWSTATUSPERSIST
     4 #UOWSTP                          I          1 /* V3 don't use/deprecated
     3 #UOWFILLER                       A          3 /* V3 alignment
  R  3 #UOWFILLER
     4 #FILL                            A          3 /* V3 don't use/deprecated
     3 #LOCS                            A         40 /* V4 callers set locale
     3 #DARCH                           I          1 /* V4 for future use
     3 #FLOG                            A          1 /* V6 force logon
     3 #ENCL                            I          1 /* V6 don't use/deprecated
     3 #KERNELSECURITY                  A          1 /* V7 security indicator
     3 #COMMITTIME                      A         17 /* V7 UOW commit time
     3 #COMPRESSLEVEL                   A          1 /* V7 compression level
     3 #RESERVED3                       B          2 /* V7 alignment
     3 #RESERVED4                       B          4 /* V7 reserved for future
     3 #UWSTATUSLIFE                    A          8 /* V8 UOWStLifeTime:adder
     3 #TOPIC                           A         96 /* V8 topic name
     3 #PUBLICATION-ID                  A         16 /* V8 publication ID
     3 #RESERVED-V99-1                  A         32 /* V9 reserved for future
     3 #RESERVED-V73-1                  I          4 /* V9 reserved for future
  R  3 #RESERVED-V73-1
     4 #EXTENSION-SEND-LENGTH           I          4 /* V9 don't use/deprecated
     3 #RESERVED-V73-2                  I          4 /* V9 reserved for future
  R  3 #RESERVED-V73-2
     4 #EXTENSION-RECEIVE-LENGTH        I          4 /* V9 don't use/deprecated
     3 #RESERVED-V73-3                  I          4 /* V9 reserved for future
  R  3 #RESERVED-V73-3
     4 #EXTENSION-RETURN-LENGTH         I          4 /* V9 don't use/deprecated
     3 #CLIENT-ID                       I          4 /* V9 unique client ID
     3 #RESERVED-V73-4                  A         32 /* V9 reserved for future
  R  3 #RESERVED-V73-4
     4 #SERVER-REPLICATION-GROUP        A         32 /* V9 don't use/deprecated
     3 #LOG-COMMAND                     A          1 /* V9 broker cmd logging
     3 #CREDENTIALS-TYPE                A          1 /* V9 credential type
     3 #RESERVED-V73-5                  A         32 /* V9 reserved for future
  R  3 #RESERVED-V73-5
     4 #VERIFIED-USERID                 A         32 /* V9 don't use/deprecated
     3 #RESERVED5                       B          2 /* V9 alignment
     3 #VARLIST-OFFSET                  I          4 /*V10 variable list offset
     3 #LONG-BROKER-ID-LENGTH           I          4 /*V10 Len long broker id
     3 #MESSAGE-ID                      A         64 /*V11 MSG ID SENT/RCVD MSG
     3 #CORRELATION-ID                  A         64 /*V11 MSG ID SENT MSG
     3 #USE-SPECIFIED-MESSAGE-ID        I          1 /*V11 No new MSG ID 4 SEND
     3 #USE-SPECIFIED-CORRELATION-ID    I          1 /*V11 Send COR ID 2 Broker
     3 #RESERVED6                       A          2 /*V11 reserved for future
     3 #RESERVED7                       I          4 /*V11 reserved for future
     3 #LONG-PASSWORD-LENGTH            I          4 /*V12 Len long password
     3 #LONG-NEW-PASSWORD-LENGTH        I          4 /*V12 Len long new passwd

Using the Broker ACI with SSL/TLS

ACI applications can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. ACI-based clients or servers are always SSL clients. The SSL server can be either the EntireX Broker or the Broker SSL Agent. For an introduction see SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation. This section describes using the Broker ACI with SSL on the following platforms:

z/OS

SSL delivered on a z/OS mainframe will typically use the Resource Access Control Facility (RACF) as the certificate authority (CA). Certificates managed by RACF can only be accessed through the RACF keyring container. A keyring is a collection of certificates that identify a networking trust relationship (also called a trust policy). In an SSL client/server network environment, entities identify themselves using digital certificates called through a keyring. Server applications on z/OS that wish to establish network connections to other entities can use keyrings and their certificate contents to determine the trustworthiness of the client or peer entity. Note that certificates can belong to more than one keyring, and you can assign different users to the same keyring. Because of the way RACF internally references certificates, they must be uniquely identifiable by owner and label, and also unique by serial number plus data set name (DSN).

For establishing an SSL connection on z/OS, IBM's Application Transparent Transport Layer Security (AT-TLS) can be used, where the establishment of the SSL connection is pushed down the stack into the TCP layer.

Using IBM's Application Transparent Transport Layer Security (AT-TLS)

With the Broker ACI for Natural you can use IBM's Application Transparent Transport Layer Security, where the establishment of the SSL connection is pushed down the stack into the TCP layer.

Configure the AT-TLS rules for the policy agent (PAGENT) graphics/no4.gif using an appropriate client graphics/no1.gif and the z/OS Management Facility (z/OSMF) graphics/no2.gif. Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by using the application graphics/no5.gif job name and remote TCP port number. If the rules match, the TCP connection is turned into an SSL connection graphics/no6.gif. Refer to your IBM documentation for more information, for example the IBM Redbook Communications Server for z/OS VxRy TCP/IP Implementation Volume 4: Security and Policy-Based Networking.

graphics/adminRpc_ssl_config-nat.png

graphics/no1.gif Client to interact with z/OS Management Facility (z/OSMF).
graphics/no2.gif AT-TLS rules are defined with z/OSMF policy management.
graphics/no3.gif Policy Repository with AT-TLS rules stored as z/OS files.
graphics/no4.gif Policy Agent, MVS task PAGENT, provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack.
graphics/no5.gif Application using TCP connection.
graphics/no6.gif If AT-TLS rules match, the TCP connection is turned into an SSL connection.

Notes:

  1. The client graphics/no1.gif may vary per operating system, for example a Web browser for z/OS 2.1.
  2. z/OSMF graphics/no2.gif includes other administration and management tasks in addition to policy management.
  3. Policy Management graphics/no3.gif includes other rules, such as IP filtering, network address translation etc.

Start of instruction setTo set up SSL with AT-TLS

  1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

  2. Set up the ACI application (client or server) for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example

    ETB024:1699:TCP
  3. Configure AT-TLS to turn the TCP/IP connection to an SSL connection, using a client to interact with the z/OS Management Facility (z/OSMF). The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files. This file is the configuration file for the Policy Agent, MVS task PAGENT.

  4. Make sure the SSL server to which the ACI application (client or server) connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in Integration Server (IS inbound). See:

z/VSE

Establishing an SSL connection on z/VSE requires BSI's Automatic Transport Layer Security (ATLS). This facility is similar to z/OS Application Transparent - Transport Layer Security (AT-TLS). ATLS is supported by the BSI stack only.

Using BSI's Automatic Transport Layer Security (ATLS)

Together with SSL parameters (to provide certificates), define ATLS rules for socket interception in the ATLS daemon startup job BSTTATLS graphics/no2.gif. If the rules match, the socket connection is turned into an SSL connection graphics/no5.gif. Refer to your IBM documentation for further information. For an overview, refer to the IBM Redbook Enhanced Networking on IBM z/VSE; for a more detailed description, refer to BSI SSL Installation, Programming and User's Guide.

graphics/adminRpc_ssl_config-vse.png

graphics/no1.gif BSI TCP/IP Stack, either BSTTINET (IPv4) or BSTT6NET (IPv6).
graphics/no2.gif ATLS rules are defined manually. See Sample ATLS Daemon Configuration below.
graphics/no3.gif BSTTATLS is associated with a TCP/IP stack.
graphics/no4.gif Application using TCP connection.
graphics/no5.gif BSTTATLS intercepts outbound TCP connection and converts it to SSL connection. For inbound, SSL connections can also be intercepted and converted to TCP connections.

Start of instruction setTo set up SSL with AT-TLS

  1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

  2. Set up the RPC component for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:

    ETB024:1699:TCP
  3. Configure AT-TLS to turn the TCP/IP connection to an SSL connection, using a client to interact with the z/OS Management Facility (z/OSMF). The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files. This file is the configuration file for the Policy Agent, MVS task PAGENT.

  4. Make sure the SSL server to which the RPC component connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). See:

Sample ATLS Daemon Configuration

* Converting inbound EntireX Broker connection 
* Converts listen port 1971 to SSL listen port 1972
OPTION SERVER 
ATTLS 1971 AS 2071 SSL
*
* Converting outbound client connection
* Converts connect to 192.168.2.100:1972:TCP to 192.168.2.100:2072:SSL
OPTION CLIENT
ATTLS 1972 TO 192.168.2.100 AS 2072 SSL

Note:
We recommend setting SETPARM value SUBTASK to a value greater than 0 in the ATLS daemon startup job (valid values 0-16, default=0). For example:

// SETPARM SUBTASK=8

See also BSI SSL Installation, Programming and User's Guide.

For additional information see also SSL/TLS, HTTP(S), and Certificates with EntireX.