Parameters in the installation options data set

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.

Support is provided for the use of system symbols in the installation options data set. System symbols can be used as values for any of the parameters. System symbols are specified in the IEASYMxx member of SYS1.PARMLIB; the IEASYM statement of the LOADxx member of SYS1.PARMLIB specifies the IEASYMxx member or members to be used for the resolution of system symbols. This example shows the use of a system symbol for specifying the domain to be used for the start of ICSF:

 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:

BEGIN(fmid)

Specifies that keywords following this BEGIN keyword are supported in release fmid and later. There must be an END statement to complete the current section. If not, an error message will be issued and ICSF will terminate.

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.

Here is an example of the usage of the BEGIN/END keywords.

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 */

CHECKAUTH(YES or NO)

Indicates whether ICSF performs security access control checking of Supervisor State or System Key callers. If you specify CHECKAUTH(YES), ICSF issues RACROUTE calls to perform the security access control checking and the results are logged in RACF SMF records that are cut by RACF. If you specify CHECKAUTH(NO), the authorization checks against resources in the CSFSERV, CSFKEYS, and XCSFKEY classes are not performed.

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.

CKDSN(data-set-name)

Specifies the CKDS name the system uses to start ICSF. Whenever you restart ICSF, the CKDS named in the CKDSN option becomes the active in-storage CKDS. (At first-time startup, you should specify the name of an empty VSAM data set you created to use as the CKDS.)

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.

CKTAUTH(YES or NO)

This keyword is no longer supported but is tolerated.

COMPAT(YES, NO, or COEXIST)

Indicates whether ICSF runs in compatibility mode, non-compatibility mode, or coexistence mode with PCF.

YES: Indicates compatibility mode.
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.
NO: Indicates non-compatibility mode. In noncompatibility mode, you run PCF applications on PCF and ICSF applications on ICSF. You cannot run PCF applications on ICSF because ICSF does not support the PCF macros in this mode. PCF can be started at the same time as ICSF on the same operating system. You can start ICSF and then start PCF, or you can start PCF and then start ICSF.
You should use noncompatibility mode unless you are migrating from PCF to ICSF.
COEXIST: Indicates coexistence mode.
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.

COMPENC(DES or CDMF)

This keyword is no longer supported but is tolerated.

CTRACE(CTICSFxx)

Specifies the CTICSFxx ICSF CTRACE configuration data set to use from PARMLIB. CTICSF00 is the default ICSF CTRACE configuration data set that is installed with ICSF FMID HCR77A1 and later releases. CTICSF00 may be copied to create new PARMLIB members using the naming convention of CTICSFxx, where xx is a unique value specified by the user.

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.

DEFAULTWRAP(internal_wrapping_method,external_wrapping_method)

Specifies the default key wrapping for DES keys. Any token generated or updated by a service will be wrapped using the specified method unless overridden by rule array keyword or a skeleton token. The default wrapping method for internal and external tokens is specified independently.

Valid values for internal_wrapping_method and external_wrapping_method are:

ORIGINAL: Specifies the original CCA token wrapping be used: ECB wrapping for DES.
ENHANCED: Specifies the new X9.24 compliant CBC wrapping is used. The enhanced wrapping method is available only on IBM zEnterprise 196, IBM zEnterprise 114 and newer servers.

If the DEFAULTWRAP keyword is not specified, the default wrapping method will be ORIGINAL for both internal and external tokens.

DOMAIN(n)

Specifies the number of the domain that you want to use for this start of ICSF. You can specify only one domain in the options data set. The domain value must match the activation profile.

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.

The cryptographic processors support multiple sets of master key registers, which the specific domain values identify.

The PCIXCC/CEX2C has master key registers for the DES-MK, AES-MK and RSA-MK master keys. Each domain has a master key register for the current, new, and old DES-MK, AES-MK and RSA-MK.
CCA cryptographic coprocessors that are CEX3C or later have master key registers for the DES-MK, AES-MK, RSA-MK, and ECC-MK master keys. Each domain has a master key for the current, new, and old DES-MK, AES-MK, RSA-MK, and ECC-MK.
The PKCS #11 cryptographic coprocessors have master key registers for the P11-MK master key. Each domain has a master key for the current and new P11-MK.

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:

Stop CSF
Start CSF in COMPAT(NO) mode with a different domain number
Stop CSF
Start CSF in compatibility or coexistence mode with a different domain number.

END

Specifies the end of a section of keywords for the fmid from the BEGIN(fmid). There must be a BEGIN(fmid) prior to the END. There must be an END for each BEGIN(fmid). See the description for BEGIN for an example of the usage of the BEGIN and END keywords.

EXIT(ICSF-name,load-module-name,FAIL(fail-option))

Indicates information about an installation exit.

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).

In general, you can specify one of these values for a fail option:

NONE: No action is taken. The exit can be called again and will end abnormally again.
EXIT: The exit is no longer available to be called again.
SERVICE: The service or program that called the exit is no longer available to be called again.
ICSF: ICSF or the key generator utility program or the PCF conversion program is ended, depending on the exit.

Some fail options are not valid for a specific exit. If you specify a fail option that is not valid, ICSF uses the next valid fail option. For example, if SERVICE is not a valid fail option for an exit, ICSF uses the EXIT option. EXIT is responsible for logging in SMF the results of any authorization checks that are made.

Table 1. Exit identifiers and exit invocations
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.

Note: z/OS no longer ships IBM-supplied security exit routines; the security exit points remain. Users of z/OS should use the Security Server (RACF) or an equivalent product to obtain access checking of services and keys. ICSF no longer needs these exit routines.

FIPSMODE(YES or COMPAT or NO,FAIL(fail-option))

Indicates whether z/OS PKCS #11 services must run in compliance with the Federal Information Processing Standard Security Requirements for Cryptographic Modules, referred to as FIPS 140-2. FIPS 140-2, published by the National Institute of Standards and Technology (NIST), is a standard that defines rules and restrictions for how cryptographic modules should protect sensitive or valuable information. The standard is available at http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf.

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.

YES

Indicates that the z/OS PKCS #11 services will operate in FIPS standard mode. Any application using the PKCS #11 services will be forced to use those services in a FIPS-compliant manner. Applications will not have access to the algorithms or key sizes not approved by FIPS 140-2. In addition, ICSF initialization will test that it is running on an IBM System z model type, and a version and release of z/OS, that supports FIPS. If so, then ICSF will perform a series of cryptographic known answer tests as required by the FIPS 140-2 standard. If any of these initialization tests should fail, the action the ICSF initialization process takes will depend on the fail-option specified.

COMPAT

Indicates that the z/OS PKCS #11 services will operate in FIPS compatibility mode. This mode is intended for installations where only certain z/OS PKCS #11 applications must comply with the FIPS 140-2 standard, while other applications do not. In this mode, the PKCS #11 services can be further configured so that the applications that do not need to comply with the FIPS 140-2 standard are not restricted from using any of the PKCS #11 algorithms, while applications that must comply with the standard are restricted from using the non-approved algorithms. By default, the COMPAT option will have the same effect as the YES option, and all applications using the PKCS #11 services will be forced to use those services in a FIPS-compliant manner. However, additional specifications can be made:

at the PKCS #11 token and application level, by creating FIPSEXEMPT.token-label resource profiles in the CRYPTOZ class. A FIPSEXEMPT.token-label resource exists for each token. User IDs with READ access authority to a FIPSEXEMPT.token-label are exempt from FIPS compliance, while user IDs with access authority NONE can only use the PKCS #11 services in a FIPS-compliant manner.
within applications themselves for individual keys. When an application creates a key, the application can specify that the key must be used in a FIPS 140-2 compliant fashion. The application can specify this by setting the Boolean key attribute CKA_IBM_FIPS140 to TRUE.

When the COMPAT option is specified, ICSF initialization will test that it is running on an IBM System z model type, and a version and release of z/OS, that supports FIPS. If so, then ICSF will perform a series of cryptographic known answer tests as required by the FIPS 140-2 standard. If any of these initialization tests should fail, the action the ICSF initialization process takes will depend on the fail-option specified.

NO

Indicates that ICSF should operate in FIPS no enforcement mode, also known as FIPS on-demand mode. Applications may request strict adherence to FIPS 140 restrictions when requesting ICSF services. However, applications not requesting FIPS processing are not required to adhere to FIPS 140 restrictions. FIPSEXEMPT.token-label profiles, if they exist in the CRYPTOZ class, will not be examined. If ICSF is running on an IBM system z model type that does not support FIPS, requests to generate or use a key with CKA_IBM_FIPS140=TRUE or those requests that explicitly ask for FIPS processing will result in a failure return code.

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.

FIPSMODE(NO,FAIL(fail-option))

The fail-option is either YES or NO, and indicates what action the ICSF initialization process should take if any of the initialization tests should fail.

YES

Indicates ICSF is to terminate abnormally if there is a failure in any of the tests performed.

NO

Indicates ICSF initialization processing is to continue even if there is a failure in any of the tests performed. However, PKCS #11 support will be limited or nonexistent depending on the test that failed:

If ICSF is running on an IBM system z model type or with a version of z/OS that does not support FIPS, most FIPS processing is bypassed. PKCS #11 callable services will be available, but ICSF will not adhere to FIPS 140 restrictions. Requests to generate or use a key with CKA_IBM_FIPS140=TRUE or those requests that explicitly ask for FIPS processing will result in a failure return code.
If a known answer test failed, all ICSF PKCS #11 callable services will be unavailable.

If the FIPSMODE option is not specified, the default is FIPSMODE(NO, FAIL(NO)).

HDRDATE(YES or NO)

Indications whether or not an installation should update the data set header record timestamp information when performing CKDS, PKDS, and TKDS I/O update operations. Data set header record updates consume a significant portion of the record update overhead. When NO is specified for this option, a noticeable performance improvement will be realized by workloads performing a significant number of KDS updates.

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.

YES: ICSF should update the KDS header record with timestamp information for single record updates.

NO: ICSF should not update the KDS header record with timestamp information for single record updates.

KDSREFDAYS(n)

Specifies, in days, how often a record should be written for a reference date/time change. A key is referenced when it is used to perform a cryptographic operation. If a key is referenced ICSF will check the date and time the key was referenced previous to the current reference. If the number of days between the current date and time and the date and time the key was last referenced is greater than or equal to the number of days specified in the KDSREFDAYS installation option then the key reference date/time in the KDS will be updated to the current date and time. Otherwise the reference date/time will remain the same. Note, in this context days are 24 hour periods not necessarily beginning or ending at midnight.

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).

Note: Updates to records using the Key Generator Utility Program (KGUP) are not subject to the value specified in the KDSREFDAYS option. All updates made via KGUP will update the reference date/time if the CKDS is in a format that supports reference date tracking (KDSR).

KEYARCHMSG(YES or NO)

Controls whether a joblog message is issued when an application successfully references a key data set record that has been archived. The message is only issued for the first successful reference of a record. The results of the service request is not affected by this control. The default is NO.

Value: Indication
YES: ICSF issues a message the first time an archived record is referenced by an application.
NO: ICSF does not issue a message when an archived record is referenced by an application.

KEYAUTH(YES or NO)

This keyword is no longer supported but is tolerated.

MAXLEN(n)

Defines the maximum length of characters in a text string, including any necessary padding, for some callable service requests. For example, this option defines the maximum length of the text the encipher service encrypts for each call. Specify n as a decimal value from 1024 through 2147483647. If you do not specify the MAXLEN option, the default value is MAXLEN(65535).

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.

Note: MAXLEN is no longer displayed on the Installation Option Display panel.

MAXSESSOBJECTS(n)

Defines the maximum number of PKCS #11 session objects and states an unauthorized (problem state, non-system key) application may own at any one time. Specify n as a decimal value from 1024 through 2147483647. If you do not specify the MAXSESSOBJECTS option, the default value is MAXSESSOBJECTS(65535).

PKDSCACHE

This keyword is no longer supported but is tolerated.

PKDSN(data-set-name)

Specifies the PKDS name the system uses to start ICSF. Whenever you restart ICSF, the PKDS named in the PKDSN option becomes the active PKDS. (At first-time startup, you should specify the name of an empty VSAM data set you created to use as the PKDS.)

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.

REASONCODES(ICSF or TSS)

Specifies which set of reason codes are to be returned from callable services. If you do not specify the REASONCODES option, the default of REASONCODES(ICSF) is used. If you specify REASONCODES(TSS), reason codes used by the IBM 4765 PCIe and IBM 4764 PCI-X Cryptographic Coprocessors will be returned. If there is a 1-to-1 mapping, the codes will be converted.

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.

RNGCACHE(YES or NO)

Indicates whether ICSF should maintain a cache of random numbers to be used by services that require them. When YES is specified for this option, a noticeable performance improvement may be realized by workloads requesting a significant amount of random data.

If you do not specify the RNGCACHE option, the default value is RNGCACHE(YES).

Value: Indication
YES: ICSF maintains a random number cache.
NO: ICSF does not maintain a random number cache.

SERVICE(service-number,load-module-name,FAIL(fail-option))

Indicates information about an installation-defined service.

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.

YES: Specifies that ICSF ends abnormally if your service cannot be loaded.
NO: Specifies that ICSF continues to start if your service cannot be loaded.

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.

SSM(YES or NO)

Specifies whether or not an installation can enable special secure mode (SSM) while running ICSF. SSM lowers the security of your system to let you enter clear keys and generate clear PINs. You must enable SSM for KGUP to permit generation or entry of clear keys and to enable the secure key import or clear pin generate callable services.

YES: Indicates that you can enable the SSM.
NO: Indicates that you cannot enable the SSM.

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.

Note: When using the SAF profiles to set the SSM, all ICSF instances sharing the SAF database will be affected.

SYSPLEXCKDS(YES or NO,FAIL(fail-option))

SYSPLEXCKDS(YES,FAIL(fail-option))

ICSF will join the ICSF sysplex group SYSICSF and this system will participate in sysplex-wide consistency for CKDS data.

SYSPLEXCKDS(YES,FAIL(YES)): Indicates ICSF initialization will end abnormally if the ICSF cross-system services environment cannot be established during ICSF initialization due to a failure creating the CKDS latch set or a failure to join the ICSF sysplex group.
SYSPLEXCKDS(YES,FAIL(NO)): Indicates ICSF initialization processing will continue even if the request to join the ICSF sysplex group fails. The system will not be notified of updates to the CKDS by other members of the ICSF sysplex group. A value of either FAIL(YES) or FAIL(NO) will be ignored with SYSPLEXCKDS(NO,...).

SYSPLEXCKDS(NO,FAIL(fail-option))

CKDS update processing proceeds as it does today (i.e. no Cross-System Services task will be initialized, nor will any XCF signalling be performed when an update to a CKDS record occurs).

If you do not specify the SYSPLEXCKDS option, the default value is SYSPLEXCKDS(NO,FAIL(NO)).

SYSPLEXPKDS(YES or NO,FAIL(fail-option))

ICSF will join the ICSF sysplex group SYSICSF and this system will participate in sysplex-wide consistency for PKDS data.

SYSPLEXPKDS(YES,FAIL(fail-option))

ICSF will join the ICSF sysplex group SYSICSFP and this system will participate in sysplex-wide consistency for PKDS data.

SYSPLEXPKDS(YES,FAIL(YES)): Indicates ICSF initialization will fail to join the sysplex if the ICSF cross-system services environment cannot be established during ICSF initialization due to a failure creating the PKDS latch set or a failure to join the ICSF sysplex group.
SYSPLEXPKDS(YES,FAIL(NO)): Indicates ICSF initialization processing will continue even if the request to join the ICSF sysplex group fails. The system will not be notified of updates to the PKDS by other members of the ICSF sysplex group. A value of either FAIL(YES) or FAIL(NO) will be ignored with SYSPLEXPKDS(NO,...).

SYSPLEXPKDS(NO,FAIL(fail-option))

PKDS update processing proceeds without trying to join the ICSF sysplex group.

If you do not specify the SYSPLEXPKDS option, the default value is SYSPLEXPKDS(NO,FAIL(NO)).

SYSPLEXTKDS(YES or NO,FAIL(fail-option))

ICSF will join the ICSF sysplex group SYSICSF and this system will participate in sysplex-wide consistency for TKDS data.

Note: TKDSN needs to be specified for this to work. See TKDSN(data-set-name).

SYSPLEXTKDS(NO,FAIL(fail-option)): Indicates no XCF signalling will be performed when an update to a TKDS record occurs.

SYSPLEXTKDS(YES,FAIL(fail-option))

Indicates the system will be notified of updates made to the TKDS by other members of the sysplex who have also specified SYSPLEXTKDS(YES,FAIL(fail-option)).

SYSPLEXTKDS(YES,FAIL(YES)): Indicates ICSF will terminate abnormally if there is a failure creating the TKDS latch set.
SYSPLEXTKDS(YES,FAIL(NO)): Indicates ICSF initialization processing will continue even if the request to join the ICSF sysplex group fails. This system will not be notified of updates to the TKDS by other members of the ICSF sysplex group.

If you do not specify the SYSPLEXTKDS option, the default value is SYSPLEXTKDS(NO,FAIL(NO)) is the default.

TKDSN(data-set-name)

The name of an existing TKDS or an empty VSAM data set to be used as the TKDS. To enable applications to create and use persistent PKCS #11 tokens and objects that use the PKCS #11 services, this option must be specified.

See Steps to create the installation options data set for the data set naming format requirements.

TRACEENTRY(n)

This keyword is no longer supported but is tolerated.

UDX(UDX-id,service-number,load-module-name,'comment_text',FAIL(fail-option))

ICSF allows the development of User Defined Extensions for the coprocessors. The UDX-id is supplied to the installation when the UDX is developed. The service-number specifies a number that identifies the service to ICSF. The valid service numbers are 1 to 32767, inclusive. This set of service numbers is valid for both installation-defined services and UDX services. The service number of a UDX service must not be the same as the service number of an installation-defined service. The load-module-name is the name of the module that contains this service. During ICSF startup, ICSF loads this module and binds it to the service-number that was specified. A comment may be specified. The positional parameter is required. The comment consists of up to 40 EBCDIC characters, and may include imbedded blank characters. The comment text is enclosed by single quotes. If no comment text is desired, two contiguous single quotes should be 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.

YES: Specifies that ICSF ends abnormally if your service cannot be loaded.
NO: Specifies that ICSF continues to start if your service cannot be loaded.

The User Defined Extension (UDX) is responsible for logging in SMF the results of any authorization checks that were made.

USERPARM(value)

Specifies an 8-byte field for installation use. The Installation Option Display panel displays this value, which is stored in the Cryptographic Communication Vector Table (CCVT) in the CCVT_USERPARM field. An application program or installation exit can examine this field and use it to set system environment information. The default is eight blanks.

WAITLIST(data_set_name)

This optional parameter can be used if you have ICSF with CICS installed. It specifies a customer modifiable data set will be used to determine names of the services to be placed into the ICSF CICS Wait List. A sample data set is provided by ICSF via member CSFWTL01 of SYS1.SAMPLIB. The sample data set contains the same entries as the default ICSF CICS Wait List (i.e., the data set contains the names of all ICSF callable services which, by default, will be driven through the CICS TRUE). The WAITLIST option should be added to the Installation Options data set under these conditions.

Non-CICS customers will not specify a WAITLIST keyword.
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
CICS customers who do not want to make use of CICS TRUE must either not enable the TRUE or must specify a WAITLIST keyword and point to an empty wait list data set (or specify WAITLIST(DUMMY)) in the Installation Options data set.
CICS customers who wish to modify the ICSF default CICS Wait List should modify the sample Wait List data set supplied in member CSFWTL01 of SYS1.SAMPLIB. The WAITLIST keyword in the Installation Options Data Set should be set to point to this modified data set. To ensure maximum performance, any existing CICS applications which invoke any of the ICSF services in the Wait List that were linked with ICSF stubs prior to the HCR7770 should be re-linked with the current ICSF stubs. For additional information on the CICS Attachment Facility, see CICS-ICSF Attachment Facility.