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 within your
sysplex or subplex.
- 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:
- 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.
- Define security product authority for the profile EZBDOMAIN
in the SERVAUTH class within the sysplex that is to use trusted TCP
connections. Specify the same security domain name in the
APPLDATA field.
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.
- Code the appropriate ioctl calls for the client and server
applications.
- For the client application:
- Optionally, issue the SIOCSPARTNERINFO ioctl before the connect
call to avoid suspending your application while the partner security
credentials are being retrieved.
- 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:
- Optionally, issue the SIOCSPARTNERINFO ioctl before the listen
call to avoid suspending your application while the partner security
credentials are being retrieved.
- 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.