Retrieving technical and security information about an HTTP request

An application can obtain information about the TCP/IP environment for an HTTP request, including the security options that are in use, and about a client certificate that has been provided by a web client.

About this task

CICS® manages the TCP/IP connection between a web client and server, applies appropriate security measures, and manages the process of authenticating the identity of a web client. The actions taken by CICS for each connection are determined by the options that you set in the TCPIPSERVICE definition for the port on which the web client request is received. A user-written application can examine information obtained by this process, if this information is useful for determining how to process the request. For example, you can obtain the host name and IP address of the web client that sent the HTTP request, or check the level of security and encryption for the connection.

The EXTRACT TCPIP command provides information about the TCP/IP connection and about security options specified in the TCPIPSERVICE definition. The EXTRACT CERTIFICATE command provides information taken from any X.509 client certificate that was received from the web client during a Secure Sockets Layer (SSL) handshake.

Procedure

  • To obtain the host name and IP address of the web client that sent the HTTP request, use the EXTRACT TCPIP command with the CLIENTNAME and CLIENTADDR options.
    The IP address is available as a binary number or as a character string containing its colon hexadecimal or dotted decimal representation.
  • To obtain the host name and IP address of the host system on which the application is running (that is, CICS itself), use the EXTRACT TCPIP command with the SERVERNAME and SERVERADDR options.
    Again, the IP address is available as a binary number or as a character string containing its colon hexadecimal or dotted decimal representation.
  • To obtain the number of the port on which the request was received, you can use the EXTRACT TCPIP command with the PORTNUMBER option.
    The port number is available as a binary number or a character string. Alternatively, you can use the WEB EXTRACT command with the PORTNUMBER option.
  • To obtain the name of the TCPIPSERVICE resource definition associated with the request, use the EXTRACT TCPIP command with the TCPIPSERVICE option.
  • To identify the type of authentication (basic authentication, client certificate authentication, or no authentication) that was specified in the TCPIPSERVICE definition, use the EXTRACT TCPIP command with the AUTHENTICATE option.
    CICS(r) as an HTTP server: authentication and identification explains more about the different types of authentication.
  • To identify whether Secure Sockets Layer (SSL) support is specified in the TCPIPSERVICE definition, and the level of SSL encryption that is used, use the EXTRACT TCPIP command with the SSLTYPE and PRIVACY options.
    SSL with CICS web support explains more about SSL.
  • To retrieve information from an X.509 certificate that was received from the web client during an SSL handshake, use the EXTRACT CERTIFICATE command.
    CICS has already verified the supplied certificate by checking it against the security manager database and against a certificate revocation list that you can set up.
    A certificate contains fields that identify the subject (sometimes called the owner or the user) of the certificate and fields that identify the Certificate Authority that issued the certificate (the issuer). You can select the information that you require by specifying the OWNER or ISSUER option. You can also use the SERIALNUM and USERID options to retrieve the serial number of the certificate and the RACF® user ID associated with the certificate.
    Support for security protocols explains more about the content of certificates and how they are used.