Steps for retrieving partner security credentials

This topic describes how to retrieve partner security credentials to create a trusted TCP connection.

Before you begin

  • A TCP socket connection in a sysplex environment is required. For information about TCP/IP in a sysplex, see z/OS Communications Server: IP Configuration Guide.
  • You need to determine whether your application is APF authorized or is authorized to run in supervisor state, or you need to know which users run the application to retrieve partner security credentials.
  • You need to decide on a common security domain name for your sysplex or subplex. The security domain name is limited to 255 characters and is not case sensitive. It will be used in the EZBDOMAIN profile definitions as described in the Procedure below.
  • You need to determine whether your application can be suspended when you are retrieving partner security credentials.

Procedure

Perform the following steps to retrieve partner security credentials:

  1. Set up proper authorization for your application using one of the following methods:
    • Set up your application so that it is APF authorized or is authorized to run in supervisor state.
    • Provide access to specific users by defining security product authority in the SERVAUTH class for the following profile: 
      EZB.IOCTL.sysname.tcpprocname.PARTNERINFO

      The sysname value is the system name that is defined in the sysplex, and the tcpprocname value is the TCP/IP procedure name.

      Tip: You can specify a wildcard on segments of the profile name.
      Requirement: Grant at least READ access to this profile to permit a user to retrieve partner security credentials.
  2. Define security product authority for the profile EZBDOMAIN in the SERVAUTH class on every LPAR within the sysplex or subplex that is to use trusted TCP connections.
    Specify the same security domain name in the APPLDATA field for each EZBDOMAIN profile.
    RDEFINE SERVAUTH EZBDOMAIN APPLDATA('security_domain_name')
    Rules:
    • The security domain name is limited to 255 characters.
    • The security domain name is not case sensitive.
    Tip: The security domain name is not required when you are using the SIOCGPARTNERINFO ioctl to retrieve information from a partner on the same stack.
    Results:
    • If the security domain name is not defined or does not match, then the request fails and the partner security credentials are not returned.
    • Verification of the security domain name occurs only the first time that partner security credentials are retrieved by the SIOCGPARTNERINFO or SIOCSPARTNERINFO ioctl in each connection.
  3. Code the appropriate ioctl calls for the client and server applications.
    • For the client application:
      1. Optionally, issue the SIOCSPARTNERINFO ioctl before the connect call to avoid suspending your application while the partner security credentials are being retrieved.
      2. Issue the SIOCGPARTNERINFO ioctl after the connect call. Optionally, when you are using the SIOCSPARTNERINFO ioctl, specify the PI_Timeout value 0 on the SIOCGPARTNERINFO ioctl to indicate that your application cannot be suspended while the partner security credentials are being retrieved.
    • For the server application:
      1. Optionally, issue the SIOCSPARTNERINFO ioctl before the listen call to avoid suspending your application while the partner security credentials are being retrieved.
      2. Issue the SIOCGPARTNERINFO ioctl after the accept call. Optionally, when you are using the SIOCSPARTNERINFO ioctl, specify the PI_Timeout value 0 on the SIOCGPARTNERINFO ioctl to indicate that your application cannot be suspended while the partner security credentials are being retrieved.

    Issue the SIOCSPARTNERINFO ioctl with the value PI_REQTYPE_SET_PARTNERDATA. For more information about the SIOCSPARTNERINFO ioctl, see SIOCSPARTNERINFO (X'8004F613').

    You can issue the SIOCGPARTNERINFO ioctl with the PI_Reqtype value set to PI_REQTYPE_PARTNER_USERID, PI_REQTYPE_PARTNER_UTOKEN, or both, to retrieve the partner user ID, partner user security token (UTOKEN), or both. For more information about the SIOCGPARTNERINFO ioctl, see SIOCGPARTNERINFO (X'C000F612'). For information about what is provided in the UTOKEN by the ICHRUTKN macro, see z/OS® Security Server RACF® Data Areas.