New server functions

UTM as HTTP-Server

A UTM application can also act as an HTTP server.

GET, PUT, POST and DELETE are supported as methods. In addition to HTTP, access via HTTPS is also supported.

The following interfaces have been changed:

• Generation

  All systems:
  

  • KDCDEF statement BCAMAPPL: 

    • Additional specification for the transport protocol for the operand T-PROT= with value SOCKET
      

      *USP:	The UTM socket protocol is to be used on connections from this access point.
      *HTTP:	The HTTP protocol is to be used for connections from this access point.
      *ANY:	Both the UTM socket protocol and the HTTP protocol are supported on connections from this access point.

    • Additional specification for encryption for the operand T-PROT= with value SOCKET
      

      SECURE:

      On connections from this access point, communication takes place using transport layer security (TLS).

    • New operand USER-AUTH = *NONE | *BASIC. Herewith you can specify which authentication mechanism HTTP clients must use for this access point.

    • KDCDEF statement HTTP-DESCRIPTOR:
      This statement defines a mapping of the path received in an HTTP request to a TAC and additional processing parameters can be specified.

  BS2000 systems:
  
  • KDCDEF statement CHAR-SET:
    With this statement, each of the four UTM code conversions provided by openUTM can be assigned up to four character set names.

• Programming

• KDCS communication area (KB):
  In the header of the KDCS communication area, there are new indicators for the client protocols HTTP, USP-SECURE, and HTTPS in the kccp/KCCP field.

• KDCS call INIT PU:

• The version of the interface has been increased to 7.
  

• To obtain the complete available information, the value 372 must be specified in the KCLI field.

• New fields for requesting (KCHTTP/http_info) and returning (KCHTTPINF/httpInfo) HTTP-specific information.

• Administration interface KDCADMI

• The data structure version of KDCADMI has been changed to version 11 (field version_data in the parameter area).

• New structure kc_http_descriptor_str in the identification area to support the HTTP descriptor.

• New structure kc_character_set_str in the identification area for supporting the HTTP character set.

• New fields secure_soc and user_auth in structure kc_bcamappl_str for the support of HTTP access points.

• UTM-HTTP program interface
  

  In addition to the KDCS interface, UTM provides an interface for reading and writing HTTP protocol information and handling the HTTP message body.
  The functions of the interface are briefly listed below:

• • Function kcHttpGetHeaderByIndex() 
    This function returns the name and value of the HTTP header field for the specified index.
    

  • Function kcHttpGetHeaderByName() 
    The function returns the value of the HTTP header field specified by the name.

  • Function  kcHttpGetHeaderCount()  
    This function returns the number of header fields contained in the HTTP request, that can be read by the program unit.

  • Function  kcHttpGetMethod()  
    This function returns the HTTP method of the HTTP request.   

  • Function kcHttpGetMputMsg() 
    This function returns the MPUT message generated by the program unit. 

  • Function kcHttpGetPath() 
    This function returns the HTTP path of the HTTP request normalized with KC_HTTP_NORM_UNRESERVED.

  • Function kcHttpGetQuery() 
    This function returns the HTTP query of the HTTP request normal ized with KC_HTTP_NORM_UNRESERVED.

  • Function kcHttpGetRc2String() 
    Help function to convert a function result of type enum into a printable zero terminated string.

  • Function kcHttpGetReqMsgBody() 
    This function returns the message body of the HTTP request.

  • Function kcHttpGetScheme() 
    This function returns the schema of the HTTP request.

  • Function kcHttpGetVersion() 
    This function returns the version of the HTTP request.

  • Function kcHttpPercentDecode() 
    Function to convert characters in percent representation in strings to their normal one-character representation.

  • Function kcHttpPutHeader() 
    This function passes an HTTP header for the HTTP response.

  • Function kcHttpPutMgetMsg() 
    This function passes a message for the program unit, which can be read with MGET.

  • Function  kcHttpPutRspMsgBody()  
    This function passes a message for the message body of the HTTP response.

  • Function  kcHttpPutStatus()
    This function passes a HTTP status code for the HTTP response.

• Communication via the Secure Socket Layer (SSL)
  BS2000 systems:

• • If a BCAMAPPL with T-PROT=(SOCKET,...,SECURE) has been generated for a UTM application, an additional task is started with a reverse proxy when UTM starts the application. The reverse proxy acts as the TLS Termination Proxy for the application and handles all SSL communication.

    Unix, Linux and Windows systems :

• • Another network process of the type utmnetssl is available for secure access with TLS. 

    If BCAMAPPL is generated with T-PROT=(SOCKET,...,SECURE) for a UTM application, a number of utmnetssl processes are started when UTM is started. The number of these processes depends on the value LISTENER-ID of these BCAMAPPL objects. All TLS communication for the assigned BCAMAPPL port numbers is handled in a utmnetssl process.

Encryption

The encryption functionality in UTM between a UTM application and a UPIC client has been revised. Security gaps have been closed, modern methods have been adopted and delivery has been simplified as follows:

• UTM-CRYPT variant
  

  Previously, the encryption functionality in UTM was only available if the product UTM-CRYPT had been installed. With UTM V7.0 this is no longer necessary. As of this version, the decision as to whether or not to use the encryption functionality is made via generation or at the time of application start.
  

• Security
  A vulnerability has been fixed in the communication between a UTM application and a UPIC client.

  This means that encrypted communication with a UTM application V7.0 is only possible together with UPIC client applications as of UPIC V7.0!

• Encryption Level 5 (Unix, Linux and Windows systems)

  KDCDEF statements PTERM, TAC and TPOOL
  The operand ENCRYPTION-LEVEL has an additional level 5, where the Diffie-Hellman method based on Elliptic Curves is used to agree the session key and input/output messages are encrypted with the AES-GCM algorithm.

OSI-TP communication and port numbers

BS2000 systems:

• KDCDEF statement OSI-CON
  The operand LISTENER-PORT can also be specified on BS2000 systems.
  

• Administration  interface KDCADMI
  In the structure kc_osi_con_str, the port number is also displayed in the listener-port field on BS2000 systems.
  

Subnets

In a UTM application, subnets can also be generated on BS2000 systems in order to restrict access to UTM applications to defined IP address ranges. In addition, name resolution can be controlled via DNS.

The following interfaces have been changed for this purpose:

• Generation
  BS2000 systems:

  • KDCDEF statement SUBNET:
    The SUBNET statement can also be specified on BS2000 systems.

  All systems:

  • KDCDEF statement SUBNET: 

    RESOLVE-NAMES=YES/NO can be used to specify whether or not a name resolution via DNS is to take place after a connection is established.

    If name resolution takes place, the real processor name of the communication partner is displayed via the administration interface and in messages. Otherwise, the IP address of the communication partner and the name of the subnet defined in the generation are displayed as the processor name.

• Administration interface KDCADMI
  The structures kc_subnet_str and kc_tpool_str contain a new field resolve_names.
  
  

Access data for the XA database connection

A modified but not yet activated user name for the XA database connection can be read by Administration (KDCADMI):

• • Operation code KC_GET_OBJECT:
    Data Structure kc_db_info_str: New field db_new_userid.

Reconnect for the XA database connection

If an XA action to control the transaction detects that the connection to the database has been lost, the system tries to renew the connection and repeat the XA action.

Only if this is not successful, the affected UTM process and the UTM application are terminated abnormally.  Previously, the UTM application was terminated abnormally, if a XA-Connection was lost without trying to reconnect.

Other changes

• XA messages 
  The messages regarding the XA interface were extended by the inserts UTM-Userid and TAC. The messages K204-K207, K212-K215 and K217-K218 are affected.

• UTM-Tool KDCEVAL
  In the TRACE 2 record of KDCEVAL the type of the last order (bourse announcement) was recorded in the WAITEND record (first two bytes can be printed).