Displaying installation options

Installation options enable you to specify certain modes and conditions to ICSF. For example, if your installation specifies YES for the SSM option, you can enable special secure mode. You specify installation options in the installation options data set. The ICSF startup procedure, specifies the installation options data set to be used for that start of ICSF. The options become active, when you start ICSF. You can use the panels to view each installation option and its current value.

To display installation options:

Select option 3, OPSTAT, on the ICSF Primary Menu panel.

The Installation Options panel appears. Refer to Figure 1.

Figure 1. Installation Options panel

 CSFSOP00 ----------- ICSF - Installation Options --------------
 COMMAND ===> 1

 Enter the number of the desired option above.

   1  OPTIONS  -  Display Installation Options
   2  EXITS    -  Display Installation exits and exit options
   3  SERVICES -  Display Installation Defined Services

Select option 1, Options, on the Installation Options panel.
The Installation Option Display panel appears, which is shown in CSFSOP10 — Installation Options panel.

This panel displays the keyword for each installation option, a brief description, and the current value of the option.

You may want to change the current value of an installation option. To change and activate an installation option, you must change the option value in the installation options data set and restart ICSF. For integrity reasons, a change of the DOMAIN option also requires a re-IPL of MVS. For a complete description of these installation options and the installation options data set, see z/OS Cryptographic Services ICSF System Programmer's Guide.

The installation options data set that the system uses at ICSF startup contains keywords and their values which specify certain installation options. On this panel, you can view these options and their values:

Active CKDS: (data-set-name)

This specifies the name of the CKDS that ICSF is currently using. During startup, ICSF uses the CKDSN option, but this may be changed by re-enciphering or refreshing the CKDS.

Active PKDS: (data-set-name)

This specifies the name of the PKDS that ICSF is currently using. During startup, ICSF uses the PKDSN option, but this may be changed by re-enciphering or refreshing the PKDS.

Active TKDS: (data-set-name)

This specifies the name of the TKDS that ICSF is currently using. During startup, ICSF uses the TKDSN option, but this may be changed by re-enciphering or refreshing the TKDS.

CHECKAUTH(YES or NO)

Indicates whether ICSF performs access control checking of Supervisor State and 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. If you specify CHECKAUTH(NO), the authorization checks against resources in the CSFSERV, the CSFKEYS, and the XCSFKEY classes are not performed resulting in a significant performance enhancement for supervisor state and system key callers. However, the authorization checks are not logged in the RACF SMF records. If you do not specify the CHECKAUTH option, the default is CHECKAUTH(NO).

COMPAT(YES, NO, or COEXIST)

Indicates whether ICSF is running in compatibility mode, noncompatibility mode, or coexistence mode with the Programmed Cryptographic Facility (PCF). If you do not specify the COMPAT option, the default value is COMPAT(NO).

Value: Indication
YES: ICSF is running in compatibility mode, which means you can run CUSP and PCF applications on ICSF because ICSF supports the CUSP and PCF macros in this mode. You do not have to reassemble CUSP and PCF applications to do this. However, you cannot start CUSP or PCF at the same time as ICSF on the same MVS system.
NO: ICSF is running in noncompatibility mode, which means that 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. You can start PCF at the same time as ICSF on the same z/OS operating system. You can start ICSF and then start PCF or you can start PCF and then start CSF. You should use noncompatibility mode unless you are migrating from PCF to ICSF.
COEXIST: ICSF is running in coexistence mode. In this 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. In this mode, you can start PCF at the same time as ICSF on the same MVS system.

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. During ICSF startup, if this parameter is not specified, or if it is specified with a PARMLIB member that is absent or contains an incorrect option, ICSF CTRACE will attempt to use the default CTICSF00 PARMLIB member. If the CTICSF00 PARMLIB member is absent or contains an incorrect option, 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.

The operator console TRACE CT command may be used to dynamically change ICSF CTRACE options from a new PARMLIB member or directly from options specified on the command. If the TRACE CT command is used to specify a PARMLIB member that is either absent or contains incorrect options, ICSF CTRACE will ignore it and continue to use the current active options. If an incorrect option is specified directly with the TRACE CT command, ICSF CTRACE will ignore it as well and continue to use the current active options.

The CSFSOP10 — Installation Options panel will display the current active PARMLIB member for CTRACE. If the TRACE CT command is used to update the CTRACE options, a value of “TRACE CT” will be displayed on the panel to indicate that the operator console TRACE CT command was used to modify the CTRACE options. Use the operator console DISPLAY TRACE,COMP=CSF command to display the current active CTRACE options.

Note: If the default CTICSF00 PARMLIB member has been deleted from the system and ICSF attempts to use it, ICSF CTRACE will perform tracing using an internal default set of trace options (KdsIO, CardIO, and SysCall filters using a 2M buffer). In this situation, if the operator console DISPLAY TRACE,COMP=CSF command is used to display the current active CTRACE options, a value of Minimum will be displayed.

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 used. Note that the enhanced wrapping method requires an IBM zEnterprise 196 with a CEX3C.

DOMAIN(n)

Allows you to access one of the set of master key registers in the CCA and EP11 coprocessors. Each CCA domain contains AES, DES, ECC, and RSA master keys depending on the coprocessor licensed internal code level. Each EP11 domain contains the EP11 master key.

You can use domains to have separate master keys for different purposes.

You can use domains in basic mode or with PR/SM logical partition (LPAR) mode. In basic mode, you access only one domain at a time. You can specify a different master key in each domain. For example, you might have one master key for production operations and a different master key for test operations. In LPAR mode, you can have a different domain for each partition. The number you specify is the number of the domain to be used for this start of ICSF.

The DOMAIN parameter is an optional parameter in the installation options data set. It is required if more than one domain is specified as the usage domain on the PR/SM panels or if running in native mode. If you assign multiple domains to an LPAR, you can have separate master keys for different purposes.

You use the Crypto page of the Customize Activation Profile to assign a usage domain index to a logical partition and enable cryptographic functions. The DOMAIN number you specify in the installation options data set while running in a partition must be the same number as the usage domain index specified for the partition on the Crypto page.

To change and activate the other installation options, you must restart ICSF. In compatibility or coexistence mode, to change and activate the DOMAIN option, you must also re-IPL MVS. A re-IPL ensures that a program does not use a key that has been encrypted under a different master key to access a cryptographic service.

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 default is FIPSMODE(NO,FAIL(NO)).

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, refer to z/OS Cryptographic Services ICSF Writing PKCS #11 Applications.

HDRDATE(YES or NO)

Indicates whether the header data is to be updated on every I/O operation. The default is YES.

KDSREFDAYS

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 or read, such that the retrieved token may have been used in 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.

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.

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

REASONCODES(ICSF or TSS)

Specifies which set of reason codes the application interface returns.

Value: Indication
ICSF: ICSF reason codes are returned.
TSS: TSS reason codes are returned.

ICSF is the default.

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.

SSM(YES or NO)

Indicates whether or not special secure mode is enabled. This mode lowers the security of your system. It allows you to input clear keys by using KGUP, produce clear PINs, use the Secure Key Import callable services and the initial use of Pass Phrase. If you do not specify the SSM option, the default value is SSM(NO).

Value: Indication
YES: Special secure mode is enabled. For z/OS ICSF, SSM(YES) must be specified in order to use KGUP, Secure Key Import callable services, Clear PIN Generate and the initial use of Pass Phrase. SSM(YES) for Pass Phrase is only required for CCF systems.
NO: You cannot enable the special secure mode.
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 profile will be affected.

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

Displays the current value of the SYSPLEXCKDS option. The values of the option can be YES or NO, with the default being NO. If SYSPLEXCKDS(NO,FAIL(fail-option)) is specified, no XCF signalling will be performed when an update to a CKDS record occurs. If SYSPLEXCKDS(YES,FAIL(fail-option)) is specified, the support described in CKDS management in a sysplex will occur.

The fail-option can be specified as either YES or NO. If FAIL(YES) is specified then ICSF initialization will end abnormally if the request during ICSF initialization to join the ICSF sysplex group fails. If FAIL(NO) is specified, then 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 CKDS by other members of the ICSF sysplex group. The default is SYSPLEXCKDS(NO,FAIL(NO)).

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

Displays the current value of the SYSPLEXPKDS option. The values of the option can be YES or NO, with the default being NO. If SYSPLEXPKDS(NO,FAIL(fail-option)) is specified, no XCF signalling will be performed when an update to a PKDS record occurs. If SYSPLEXPKDS(YES,FAIL(fail-option)) is specified, the support described in PKDS management in a sysplex will occur.

The fail-option can be specified as either YES or NO. If FAIL(YES) is specified then ICSF initialization will end abnormally if the request during ICSF initialization to join the ICSF sysplex group fails. If FAIL(NO) is specified, then 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 PKDS by other members of the ICSF sysplex group. The default is SYSPLEXPKDS(NO,FAIL(NO)).

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

Displays the current value of the SYSPLEXTKDS option. The values of the option can be YES or NO, with the default being NO. If SYSPLEXTKDS(NO,FAIL(fail-option)) is specified, no XCF signalling will be performed when an update to a TKDS record occurs. If SYSPLEXTKDS(YES,FAIL(fail-option)) is specified, the support described in TKDS management in a sysplex will occur.

The fail-option can be specified as either YES or NO. If FAIL(YES) is specified then ICSF initialization will end abnormally if the request during ICSF initialization to join the ICSF sysplex group fails. If FAIL(NO) is specified, then 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. The default is SYSPLEXTKDS(NO,FAIL(NO)).

USERPARM(value)

Displays the value of an 8-byte field that is defined for installation use. ICSF stores this value in the CCVT_USERPARM field of the Cryptographic Communication Vector Table (CCVT). An application program or installation exit can examine this field and use it to set system environment information.

WAITLIST(value)

Displays the current value of the WAITLIST option. If WAITLIST is coded, the value will be "dataset" and a second line will contain the name of the specified Wait List data set. If WAITLIST is not coded, the value will be "default". If the data set specified by the WAITLIST option cannot be allocated or opened, the value will also be "default".

For more information about the ICSF startup procedure and installation options, see z/OS Cryptographic Services ICSF System Programmer's Guide. At any time while you are running ICSF, you can check the current value of these installation options.

The installation exits and installation-defined callable services are also specified in the installation options data set, but they are not displayed on this panel. For a description of how to display the installation exit information, see Displaying installation exits. For a description of how to display installation-defined callable service information, see Displaying installation-defined callable services.