The installation options data set is an intended programming interface.
When specifying parameter values within parentheses, leading and trailing blanks are ignored. Embedded blanks may cause unpredictable results.
DOMAIN(&PARDOM.)
When
the Installation Options Data Set is processed during the start of
ICSF, the value of the system symbol PARDOM will be substituted as
the value of the DOMAIN parameter.For the first start, you specified an empty VSAM data set name for the CKDS in the CKDSN option, an empty VSAM data set name for the PKDS in the PKDSN option, and SSM(YES). You may want to change these and other options for subsequent starts. Here is a complete list of installation options:
There may be any number of BEGIN/END pairs in the data set, but they cannot be nested within each other. A BEGIN must have a matching END before another BEGIN can be specified.
If the release of ICSF you are running is at this release or later, the keywords will be parsed and processed. If release of ICSF you are running is an earlier release, the keywords will be ignored.
It recommended that when your systems are all running releases that support newer keywords that the BEGIN/END pair be removed.
The following FMIDs are supported: HCR7740, HCR7750, HCR7751, HCR7770, HCR7780, HCR7790, HCR77A0, HCR77A1, and HCR77B0.
keyword4 /* keyword4 is supported by all releases */
BEGIN(HCR7751)
keyword1 /* keyword1 added in HCR7751 */
keyword3 /* keyword3 added in HCR7751 */
END
BEGIN(HCR7770)
keyword2 /* keyword2 added in HCR7770 */
END
keyword5 /* keyword5 is supported by all releases */
If you do not specify the CHECKAUTH option, the default is CHECKAUTH(NO).
If you configure CHECKAUTH(YES) in the ICSF options dataset, the Health Checker address space user identity must be authorized to the CSFRKL profile in class CSFSERV for the ICSFMIG7731_ICSF_RETAINED_RSAKEY migration check to successfully execute. However, you have no action to take if you choose not to run the migration check. If you configure CHECKAUTH(NO), there is no requirement to authorize the Health Checker user identity for any ICSF profiles or classes, since the check routine executes in supervisor state. This is not an implementation consideration, but rather a check deployment or activation time customer administration consideration.
If you do not specify this keyword, ICSF does not become active. There is no default for this option, so you must specify a value.
See Steps to create the installation options data set for the data set naming format requirements.
In compatibility mode, you can run a PCF application on ICSF because ICSF supports the PCF macros. You do not have to reassemble PCF applications to do this. You cannot start PCF at the same time as ICSF on the same operating system.
You should use noncompatibility mode unless you are migrating from PCF to ICSF.
In coexistence mode, you can run a PCF application on PCF, or you can reassemble the PCF application to run on ICSF. To do this, you reassemble the application against coexistence macros that are shipped with ICSF. You can start PCF at the same time as ICSF on the same operating system.
If you do not specify the COMPAT option, the default value is COMPAT(NO). See Running PCF and z/OS ICSF on the same system for a complete description of the COMPAT options.
When you initialize ICSF for the first time, noncompatibility mode must be active. Therefore, at first-time startup, you must specify COMPAT(NO)
or allow the default to be used.This parameter is optional. If the specified PARMLIB member is incorrect or absent, ICSF CTRACE will attempt to use the default CTICSF00 PARMLIB member. If the CTICSF00 PARMLIB member is incorrect or absent, ICSF CTRACE will perform tracing using an internal default set of trace options. By default, ICSF CTRACE support will trace with the KdsIO, CardIO, and SysCall filters using a 2M buffer. For more information refer to Creating an ICSF CTRACE configuration data sets.
DOMAIN is an optional parameter. The DOMAIN parameter is only required if more than one domain is specified as the usage domain on the PR/SM panels. If specified in the options data set, it will be used and it must be one of the usage domains for the LPAR.
If DOMAIN is not specified in the options data set, ICSF determines which domains are available in this LPAR. If only one domain is defined for the LPAR, ICSF will use it. If more than one is available, ICSF will issue error message CSFM409E.
For more information about partitions and running different configurations, see z/OS Cryptographic Services ICSF Overview.
If you run ICSF in compatibility or coexistence mode, you cannot change the domain number without re-IPLing the system. A re-IPL ensures that a program does not access a cryptographic service with a key that is encrypted under a different master key. If you are certain that no cryptographic applications are still running, you can:
The ICSF -name is the identifier for each exit. Table 1 lists all the ICSF exit names and explains when ICSF calls each exit. The load module name is the name of the module that contains the exit. The name can be any valid name your installation chooses.
Using the FAIL keyword of the EXIT statement, you specify the action ICSF, the KGUP, or the PCF conversion program takes if the exit ends abnormally. The fail action that you specify applies to subsequent calls of the exit. If an exit ends abnormally, ICSF takes a system dump. The exit is protected with an ESTAE or the ICSF service functional recovery routine (FRR).
Exit identifiers | Exit invocations |
---|---|
CSFAPG | Gets control during the Authentication Parameter Generate callable service. |
CSFCKC | Gets control during the CVV key combine callable service. |
CSFCKDS | Gets control when a callable service retrieves an entry from the CKDS. |
CSFCKI | Gets control during the clear key import callable service. |
CSFCKM | Gets control during the multiple clear key import callable service. |
CSFCONVX | Gets control when you run the PCF CKDS conversion program. |
CSFCPA | Gets control during the clear PIN generate alternate callable service. |
CSFCPE | Gets control during the clear PIN encrypt callable service. |
CSFCSG | Gets control during the VISA CVV service generate callable service. |
CSFCSV | Gets control during the VISA CVV service verify callable service. |
CSFCTT2 | Gets control during the cipher text translate2 service. |
CSFCTT3 | Gets control during the cipher text translate2 (with alet) service. |
CSFCVE | Gets control during the cryptographic variable encipher callable service. |
CSFCVT | Gets control during the control vector translate callable service. |
CSFDCO | Gets control during the decode callable service. |
CSFDDPG | Gets control during the DK Deterministic PIN Generate callable service. |
CSFDEC | Gets control during the decipher callable service. |
CSFDEC1 | Gets control during the decipher (with ALET) callable service. |
CSFDKG | Gets control during the diversified key generate callable service. |
CSFDKG2 | Gets control during the Diversified Key Generate2 callable service. |
CSFDKX | Gets control during the data key export callable service. |
CSFDKM | Gets control during the data key import callable service. |
CSFDMP | Gets control during the DK Migrate PIN callable service. |
CSFDPC | Gets control during the DK PIN Change callable service. |
CSFDPCG | Gets control during the DK PRW CMAC Generate callable service. |
CSFDPMT | Gets control during the DK PAN Modify in Transaction callable service. |
CSFDPNU | Gets control during the DK PRW Card Number Update callable service. |
CSFDPT | Gets control during the DK PAN Translate callable service. |
CSFDRP | Gets control during the DK Regenerate PRW callable service. |
CSFDPV | Gets control during the DK PIN Verify callable service. |
CSFDRPG | Gets control during the DK Random PIN Generate callable service. |
CSFDSG | Gets control during the digital signature generate service. |
CSFDSV | Gets control during the digital signature verify callable service. |
CSFECO | Gets control during the encode callable service. |
CSFEDC | Gets control during the compatibility service for the PCF CIPHER macro. |
CSFEDH | Gets control during the ECC Diffie-Hellman callable service. |
CSFEMK | Gets control during the compatibility service for the PCF EMK macro. |
CSFENC | Gets control during the encipher callable service. |
CSFENC1 | Gets control during the encipher (with ALET) callable service. |
CSFEPG | Gets control during the encrypted PIN generate callable service. |
CSFEXIT1 | Gets control after
the operator issues the START command, but before processing takes
place. Note: You must not specify an EXIT statement for the first
mainline exit, CSFEXIT1.
|
CSFEXIT2 | Gets control after ICSF reads and interprets the installation options data set. |
CSFEXIT3 | Gets control before ICSF completes initialization. |
CSFEXIT4 | Gets control after the operator issues the STOP command to stop ICSF. |
CSFEXIT5 | Gets control when the operator issues the MODIFY command to modify ICSF. |
CSFFPED | Gets control during the FPE decipher callable service. |
CSFFPEE | Gets control during the FPE encipher callable service. |
CSFFPET | Gets control during the FPE translate callable service. |
CSFGKC | Gets control during the compatibility service for the PCF GENKEY macro. |
CSFHMG | Gets control during the HMAC generate callable service. |
CSFHMV | Gets control during the HMAC Verify callable service. |
CSFKDSL | Gets control during the Key Data Set List callable service. |
CSFKDMR | Gets control during the Key Data Set Metadata Read callable service. |
CSFKDMW | Gets control during the Key Data Set Metadata Write callable service. |
CSFKEX | Gets control during the key export callable service. |
CSFKGN | Gets control during the key generate callable service. |
CSFKGN2 | Gets control during the key generate2 callable service. |
CSFKGUP | Gets control during key generator utility program initialization, processing, and termination. |
CSFKIM | Gets control during the key import callable service. |
CSFKPI | Gets control during the key part import callable service. |
CSFKPI2 | Gets control during the key part import2 callable service. |
CSFKRC | Gets control during the CKDS key record create callable service. |
CSFKRC2 | Gets control during the CKDS key record create2 callable service. |
CSFKRD | Gets control during the CKDS key record delete callable service. |
CSFKRR | Gets control during the CKDS key record read callable service. |
CSFKRR2 | Gets control during the CKDS key record read2 callable service. |
CSFKRW | Gets control during the CKDS key record write callable service. |
CSFKRW2 | Gets control during the CKDS key record write2 callable service. |
CSFKTR | Gets control during the key translate callable service. |
CSFKTR2 | Gets control during the key translate2 callable service. |
CSFKYT | Gets control during the key test callable service. |
CSFKYT2 | Gets control during the key test2 callable service. |
CSFKYTX | Gets control during the key test extended callable service. |
CSFMDG | Gets control during the MDC generate callable service. |
CSFMDG1 | Gets control during the MDC generate (with ALET) callable service. |
CSFMGN | Gets control during the MAC generate callable service. |
CSFMGN1 | Gets control during the MAC generate (with ALET) callable service. |
CSFMGN2 | Gets control during the MAC Generate2 callable service. |
CSFMGN3 | Gets control during the MAC Generate3 callable service. |
CSFMPS | Gets control during the ICSF Multi-Purpose Service. |
CSFMVR | Gets control during the MAC verify callable service. |
CSFMVR1 | Gets control during the MAC verify (with ALET) callable service. |
CSFMVR2 | Gets control during the MAC Verify2 callable service. |
CSFMVR3 | Gets control during the MAC Verify3 callable service. |
CSFPGN | Gets control during the Clear PIN generate callable service. |
CSFPTR | Gets control during the encrypted PIN translate callable service. |
CSFPVR | Gets control during the encrypted PIN verify callable service. |
CSFRTC | Gets control during the compatibility service for the PCF RETKEY macro. |
CSFSKM | Gets control during the multiple secure key import callable service. |
CSFSRRW | Gets control when an access to a single record in the CKDS is made using the key entry hardware. |
CSFOWH | Gets control during the one-way hash generate callable service. |
CSFOWH1 | Gets control during the one-way hash generate (with ALET) callable service. |
CSFPCI | Gets control during the PCI interface callable service. |
CSFPCU | Gets contol during the PIN Change/Unblock callable service |
CSFPEX | Gets control during the prohibit export callable service. |
CSFPEXX | Gets control during the prohibit export extended callable service. |
CSFPFO | Gets control during the Recover PIN From Offset callable service. |
CSFPKD | Gets control during the PKA decrypt callable service. |
CSFPKE | Gets control during the PKA encrypt callable service. |
CSFPKG | Gets control during the PKA key generate callable service. |
CSFPKI | Gets control during the PKA key import callable service. |
CSFPKT | Gets control during the PKA key translate callable service. |
CSFPKTC | Gets control during the PKA key token change callable service. |
CSFPKRC | Gets control during the PKDS key record create callable service. |
CSFPKRD | Gets control during the PKDS key record delete callable service. |
CSFPKRR | Gets control during the PKDS key record read callable service. |
CSFPKRW | Gets control during the PKDS key record write callable service. |
CSFPKX | Gets control during the PKA Public Key Extract callable service. |
CSFRKA | Gets control during the restrict key attribute callable service. |
CSFRKD | Gets control during the retained key delete callable service. |
CSFRKL | Gets control during the retained key list callable service. |
CSFRKX | Gets control during the remote key export callable service. |
CSFRNG | Gets control during the random number generate callable service. |
CSFRNGL | Gets control during the random number generate long callable service. |
CSFSBC | Gets control during the SET block compose callable service. |
CSFSBD | Gets control during the SET block decompose callable service. |
CSFSKI | Gets control during the secure key import callable service. |
CSFSKI2 | Gets control during the secure key import2 callable service. |
CSFSKY | Gets control during the secure messaging for keys callable service. |
CSFSMG | Gets control during the symmetric MAC generate callable service. |
CSFSMG1 | Gets control during the symmetric MAC generate (with ALET) callable service. |
CSFSMV | Gets control during the symmetric MAC verify callable service. |
CSFSMV1 | Gets control during the symmetric MAC verify (with ALET) callable service. |
CSFSPN | Gets control during the secure messaging for PINs callable service. |
CSFSXD | Gets control during the Symmetric Key Export with Data callable service. |
CSFSYG | Gets control during the symmetric key generate callable service. |
CSFSYI | Gets control during the symmetric key import callable service. |
CSFSYI2 | Gets control during the symmetric key import2 callable service. |
CSFSYX | Gets control during the symmetric key export callable service. |
CSFT31I | Gets control during the TR-31 import callable service. |
CSFT31X | Gets control during the TR-31 export callable service. |
CSFTBC | Gets control during the trusted block create callable service. |
CSFTRV | Gets control during the transaction validation callable service |
CSFUKD | Gets control during the Unique Key Derive callable service |
See Installation exits for a detailed description of each ICSF exit, including the valid fail options.
By configuring z/OS PKCS #11 services to operate in compliance with FIPS 140-2 specifications, installations or individual applications can use the z/OS PKCS #11 services in a way that allows only the cryptographic algorithms (including key sizes) approved by the standard, and restricts access to the algorithms that are not approved. For more information, seez/OS Cryptographic Services ICSF Writing PKCS #11 Applications.
ICSF initialization will test that it is running on an IBM system z model type and version/release of z/OS that supports FIPS. If so, ICSF initialization will also perform a series of cryptographic known answer self tests. Should a test fail, the action ICSF initialization takes is dependent on the fail option.
If you do not specify the HDRDATE option, the default value is HDRDATE(YES). When configured this way ICSF will continue to accrue header record timestamp updates and performance will remain consistent.
For example: If KDSREFDAYS(7) was specified and a key was referenced on Monday, January 1st at 8 AM, and the reference date/time for the key was updated at that time, then any key reference before Monday, January 8th at 8 AM (7 days) will not update the reference date/time in the key record. If the key is referenced again at 7:50 AM on Monday, January 8th, the reference date/time for the key in the KDS will remain January 1st at 8 AM because fewer than seven days have passed. The reference date/time will not be updated until the next time the key is used again Monday, January 8th at 8 AM or after.
KDSREFDAYS applies to all KDS that are in the format that supports key reference tracking. In an environment of mixed KDS formats, where some support reference date tracking and some don't (e.g. the CKDS supports reference date tracking but the PKDS does not) key references will not be tracked for keys in a KDS does not support it, regardless on the value of KDSREFDAYS, until that KDS is updated to the new format. In a SYSPLEX, all systems must be started with the same value of KDSREFDAYS to ensure proper tracking of reference date/times.
KDSREFDAYS(0) means that ICSF will not keep track of key reference dates. The default is KDSREFDAYS(1). The maximum value allowed is KDSREFDAYS(30).
The MAXLEN parameter may still be specified in the options data set, but only the maximum value limit will be enforced (2147483647). If a value greater than this is specified, an error will result and ICSF will not start.
If you do not specify this keyword, ICSF does not become active. There is no default for this option, so you must specify a value.
See Steps to create the installation options data set for the data set naming format requirements.
If you specified REASONCODES(ICSF) and your service was processed on a CCA coprocessor, a cryptographic coprocessor reason code may be returned if there is no corresponding ICSF reason code.
If you do not specify the RNGCACHE option, the default value is RNGCACHE(YES).
ICSF allows an installation to define its own service similar to an ICSF callable service. The service-number specifies a number that identifies the service to ICSF. The valid service numbers are 1 through 32767, inclusive. This set of service numbers is valid for both installation-defined services and UDX services. The service number of an installation-defined service must not be the same as the service number of a UDX service. The load-module-name is the name of the module that contains the service. During ICSF startup, ICSF loads this module and binds it to the service-number you specified.
The fail-option is YES or NO, indicating the action ICSF should take if loading the service ends abnormally.
If the service itself ends abnormally, ICSF does not end, but takes a system dump instead. The ICSF service functional recovery routine (FRR) protects the service.
See Installation-defined Callable Services for a description of how to write and run an installation-defined callable service.
If you do not specify the SSM option, the default value is SSM(NO).
The SSM option can be changed from NO to YES while ICSF is running by defining the CSF.SSM.ENABLE SAF profile within the XFACILIT resource class. To revert to your startup option, delete the CSF.SSM.ENABLE profile. The XFACILIT class must be refreshed after each change for it to take effect.
If you do not specify the SYSPLEXCKDS option, the default value is SYSPLEXCKDS(NO,FAIL(NO)).
If you do not specify the SYSPLEXPKDS option, the default value is SYSPLEXPKDS(NO,FAIL(NO)).
If you do not specify the SYSPLEXTKDS option, the default value is SYSPLEXTKDS(NO,FAIL(NO)) is the default.
See Steps to create the installation options data set for the data set naming format requirements.
The fail-option is YES or NO, indicating the action ICSF should take if loading the service ends abnormally. If the service itself ends abnormally, ICSF does not end, but takes a system dump instead.
The User Defined Extension (UDX) is responsible for logging in SMF the results of any authorization checks that were made.
You must also ensure that any existing CICS applications which invoke any of these services are re-linked to ensure that the correct version of the stub is used: CSNBCKI, CSNBCKM, CSNBDEC, CSNBENC, CSNBKYTX, CSNBMGN, CSNBMVR, CSNBPEXX, CSNBRNG