PERFORM SSL REBUILD
Refresh the SSL environment and the cache of certificates for the CICS® region.
Syntax
Conditions: INVREQ, IOERR, NOTAUTH
NOHANDLE, RESP, and
RESP2 are common options that can be added to all EXEC CICS
commands to process error conditions. They are not explicitly included in the command syntax diagram
and option descriptions. For information about these common options and EXEC CICS
command syntax, see EXEC CICS command format and programming considerations.
This command is threadsafe.
Description
The PERFORM SSL REBUILD command is a request to rebuild the SSL environment for the CICS region. z/OS® System SSL manages the SSL environment. The SSL environment includes a cache that contains copies of the certificates in the designated key ring for the CICS region.
Any SSL handshake that is in progress in the CICS region when the PERFORM SSL REBUILD command is issued continues based on the old certificate information, and existing SSL sessions are retained.
- The cache of certificates is rebuilt from the key ring for the CICS region, which is held in the RACF database. The new cache includes copies of the new or renewed certificates that were placed in the key ring after the previous build of the SSL environment. New SSL handshakes or sessions that begin in the CICS region after the rebuild is complete use the refreshed certificate information.
- If the SSL environment manages a local SSL cache for the CICS region, as specified by the SSLCACHE=CICS system initialization parameter in CICS, a new cache is created. The SSL cache holds session IDs for SSL sessions. The new cache is populated by new SSL sessions that are established in the CICS region. The old cache is removed when the last connection using it is dropped. If an SSL cache is held at sysplex level for multiple CICS regions (SSLCACHE=SYSPLEX), it is not affected.
- If the CICS region uses
an LDAP server for storing certificate revocation lists (CRLs), the
bind information that is held for the LDAP server in the SSL environment
is refreshed. The details of the LDAP server are taken from an LDAPBIND
definition held by RACF, which is referenced
by the CRLPROFILE system initialization parameter
in CICS. If the initial setup
of this profile was invalid and the CICS region
has therefore disabled its access to the LDAP server, as reported
by messages DFHSO0128 or DFHSO0129, the rebuild of the SSL environment
cannot restore access to the LDAP server. The refresh only takes place
for an LDAP server that is available to the CICS region at the time when the rebuild is
carried out. Note: Rebuilding the SSL environment does not refresh the certificate revocation lists on the LDAP server. For instructions to do this, see Running the CCRL transaction.
If the PERFORM SSL REBUILD command does not complete successfully, the old SSL environment and the old cache of certificates are retained and continue to be used by the CICS region. Errors from z/OS System SSL are returned on the command.
Message DFHSO0002 might be issued and a system dump is taken.
Options
- GSKRESP(data-area)
- Returns a fullword binary field containing the return code from z/OS System SSL. For an explanation of the return code, see SSL function return codes in z/OS Cryptographic Services System SSL Programming.
Conditions
- INVREQ
- RESP2 values:
- 1
- The CICS region does not use SSL.
- IOERR
- RESP2 values:
- 6
- Error returned from z/OS System SSL. The return code is in GSKRESP, if the option was used.
- NOTAUTH
- RESP2 values:
- 100
- The user associated with the issuing task is not authorized to use this command.