ICSF Dynamic Service Update
IBM’s Integrated Cryptographic Service Facility, known as ICSF for short, works with the hardware cryptographic feature and z/OS Security Server (RACF element) to provide secure, high-speed cryptographic services in the z/OS environment. ICSF provides an application programming interface via cryptographic services to access the cryptographic hardware.
In this article we talk about our experiences configuring and using the ICSF function known as Dynamic Service Update. This new function, available on ICSF FMID HCR77D0 and above, allows for dynamically loading new ICSF service without the need to IPL a system.
Dynamic Service Update, described in the Cryptographic Services Integrated Cryptographic Service Facility System Programmer's Guide for HCR77D1 in Chapter 4: Operating ICSF, Section Dynamic service update, allows you to apply service updates to ICSF with minimal impact to ICSF availability. It allows ICSF to activate service without a manual stop and start of ICSF. These updates include service updates as well as changes to the options data set that cannot be applied via the SETICSF OPT, REFRESH command. Additionally, dynamic service updates can be used to recycle ICSF when there are problems that are not resolving. For any service to be applied to ICSF using the dynamic service update method, there must be a + +HOLD(DYNACT) with the PTF. Otherwise, the service cannot be applied using dynamic service update.
NOTE: Dynamic service update cannot be used to migrate ICSF to a new ICSF FMID.
Configuration
When using dynamic service update, ICSF will have to be restarted after the SETICSF PAUSE command is issued. The ICSF System Programmer’s Guide outlines a couple of methods to use when restarting ICSF after termination from a SETICSF PAUSE command. We chose to configure automations to restart ICSF after receiving the CSFM401I CRYPTOGRAPHY SERVICES ARE NO LONGER AVAILABLE message. In our environment we configured a one second delay to ensure that the ICSF address space has fully terminated before issuing the start command.
Our Test Experience
- We started by updating the ICSF PARMLIB options data set with the following keywords:
SERVSCSFMOD0(CSF.SCSFMOD0,PETPH0)
SERVICELIBS(YES)
NOTE: The SERVSCSFMOD0 Dataset must be APF authorized in order to be loaded using Dynamic Service Update.
- We then issued:
SETICSF OPT,REFRESH
This command not only refreshes the options data set so that SERVSCSFMOD0 is set to CSF.SCSFMOD0 but it also verifies there are no syntax errors in the options data set and validates that servicelib, CSF.SCSFMOD0, is correctly defined and accessible. At this point, the SERVSCSFMOD0 value is the new service to load ICSF from.
- Next we issued:
DISPLAY ICSF,SERVICELIBS,SYSPLEX=Y
Here you can see the dynamic service we want to load has been loaded into the SCSFMOD0 Next value, and the Current value is still what is specified in the LNKLST.
- To initiate the dynamic service update process, we issued:
SETICSF PAUSE
The results of this command can be seen in the SYSLOG indicating that the service update started. At this point ICSF allows all in process requests to complete and any new requests are paused.
- We next verified that we saw the following message in the system log:
Once the CSFM401I message was received, we can see that automations restarts ICSF:
- Next we see that ICSF resumes all paused requests and completes initialization. This is represented by the messages below.
- We also verified the Current service we are running with by issuing the DISPLAY ICSF,SERVICELIBS We verified that the current and next values for this LPAR now match and are the target service specified in the ICSF PARMLIB options data set.
An issue we encountered when using this new function was being unable to utilize the function when running with CSF stubs prior to HCR7770 in the ICSF Wait List. We encountered an ICSF 0C4 and the CICS transactions failed. APAR OA56605 was opened to prevent the system from executing SETICSF PAUSE and instead it will fail the command. With this fix, if you are running with CSF stubs from releases prior to HCR7770, the SETICSF PAUSE command will fail and the user will receive one of the following two messages:
CSFM670I SETICSF command failed: Pre-HCR77A0 CVG stub used in CICS.
Explanation: The SETICSF PAUSE command has been disabled due to a pre-HCR77A0 CSNBCVG (CSFCVG) callable service stub being used in a CICS application.
CSFM670I SETICSF command failed: Pre-HCR77A0 PKB stub used in CICS.
Explanation: The SETICSF PAUSE command has been disabled due to a pre-HCR77A0 CSNDPKB (CSFPKB) callable service stub being used in a CICS application.
If you want to utilize the Dynamic service update function but are hitting the above errors it is suggested that the stubs be updated to a newer release that supports the function. Alternatively, if the workloads utilizing the older stubs are not critical and are not run frequently, a user can stop all workloads utilizing the stubs. Once all the stubs have been updated or workloads utilizing them have been stopped, ICSF will need to be restarted or an IPL performed on the system for the function to be enabled.
Note that APAR OA56605 has PTFs available for HCR77C1 and HCR77D0. The fix is included in HCR77D1 and above.
Documentation reference:
z/OS Cryptographic Services Integrated Cryptographic Service Facility System Programmer's Guide
Authors
Dominic Rossillo (Dominic.Rossillo@ibm.com)
Sue Marcotte (samarcot@us.ibm.com)