PERFORM SSL REBUILD
Refresh the SSL environment and the cache of certificates for the CICS® region.
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 external security manager’s 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 the external security manager, 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 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.