SETICSF

Syntax

Parameters

ACTivate

Activates the specified cryptographic device or devices. The valid device specifications are:

SN=serialnumber

Specify the serial number or numbers of the device or devices to be activated. The serialnumber value can be a single serial number or a list of serial numbers separated by commas. When more than one value is provided, the set of values must be enclosed in parentheses. For example:

SN=99AE6012
SN=(99AE6012,99AE6013,99AE6014)

INDEX=indexlist

Specify the index or indexes of the device or devices to be activated. The valid range is 0 to 63. The indexlist value can be a single device index, a range of indexes separated by a colon, or a combination of the two separated by commas. When more than one value is provided, the set of values must be enclosed in parentheses. For example:

INDEX=01
INDEX=(02:08)
INDEX=(02,04:07,09)

Note: To understand how the use of the INDEX value with the SYSPLEX parameter can result in devices with different serial numbers being modified on other systems sharing the KDS, see the explanation of the SYSPLEX parameter.

DEACTivate

Deactivates specified cryptographic devices. The valid device specification are:

SN=serialnumber

Specify the serial number or numbers of the device or devices to be deactivated. The serialnumber value can be a single serial number or a list of serial numbers separated by commas. When more than one value is provided, the set of values must be enclosed in parentheses. For example:

SN=99AE6012
SN=(99AE6012,99AE6013,99AE6014)

INDEX=indexlist

Specify the index or indexes of the device or devices to be deactivated. The valid range is 0 to 63. The indexlist value can be a single device index, a range of indexes separated by a colon, or a combination of the two separated by commas. When more than one value is provided, the set of values must be enclosed in parentheses. For example:

INDEX=01
INDEX=(02:08)
INDEX=(02,04:07,09)

Note: To understand how the use of the INDEX value with the SYSPLEX parameter can result in devices with different serial numbers being modified on other systems sharing the KDS, see the explanation of the SYSPLEX parameter.

DISable

Disables updates for the specified key data set. The valid KDS specifications are:

• CKDS
• PKDS
• TKDS

ENable

Enables updates for the specified key data set. The valid KDS specifications are:

• CKDS
• PKDS
• TKDS

OPTions

Changes the value of an ICSF option. The supported options are:

AUDITKEYLIFECKDS,AUDKLC

Changes one or more options related to lifecycle auditing of CKDS labels and tokens.

LABEL,LAB = YES|NO

YES

Enables key lifecycle auditing of CKDS labels.

NO

Disables key lifecycle auditing of CKDS labels.

TOKEN,TOK = YES|NO

YES

Enables key lifecycle auditing of CKDS tokens.

NO

Disables key lifecycle auditing of CKDS tokens.

Example:

AUDITKEYLIFECKDS,LABEL=YES,TOKEN=NO

AUDITKEYLIFEPKDS,AUDKLP

Changes one or more options related to lifecycle auditing of PKDS labels and tokens.

LABEL,LAB = YES|NO

YES

Enables key lifecycle auditing of PKDS labels.

NO

Disables key lifecycle auditing of PKDS labels.

TOKEN,TOK = YES|NO

YES

Enables key lifecycle auditing of PKDS tokens.

NO

Disables key lifecycle auditing of PKDS tokens.

Example:

AUDKLP,TOK=NO,LABEL=YES

AUDITKEYLIFETKDS,AUDKLT

Changes one or more options related to lifecycle auditing of TKDS token objects and session objects.

TOKENOBJ,TOKO = YES|NO

YES

Enables key lifecycle auditing of TKDS token objects.

NO

Disables key lifecycle auditing of TKDS token objects.

SESSIONOBJ,SESSO = YES|NO

YES

Enables key lifecycle auditing of TKDS token objects.

NO

Disables key lifecycle auditing of TKDS token objects.

Example:

AUDKLT,TOKO=YES
AUDKLT,TOKO=YES,SESSO=YES

AUDITKEYUSGCKDS,AUDKUC

Changes one or more options related to key usage auditing of CKDS labels and tokens.

LABEL,LAB = YES|NO

YES

Enables key usage auditing of CKDS labels.

NO

Disables key usage auditing of CKDS labels.

TOKEN,TOK = YES|NO

YES

Enables key usage auditing of CKDS tokens.

NO

Disables key usage auditing of CKDS tokens.

INTERVAL,INT = usginterval[H|M|S]

The interval over which key usage records are aggregated before being written out to SMF. The time unit may be specified as H – hours, M – minutes, or S – seconds. If the time unit is not specified, the default is S - seconds. The minimum value of usginterval is 1 second. The maximum value is 24 hours.

Example:

AUDKUC,LABEL=YES,TOK=YES
AUDKUC,INT=8H

AUDITKEYUSGPKDS,AUDKUP

Changes one or more options related to key usage auditing of PKDS labels and tokens.

LABEL,LAB = YES|NO

YES

Enables key usage auditing of PKDS labels.

NO

Disables key usage auditing of PKDS labels.

TOKEN,TOK = YES|NO

YES

Enables key usage auditing of PKDS tokens.

NO

Disables key usage auditing of PKDS tokens.

INTERVAL,INT = usginterval[H|M|S]

The interval over which key usage records are aggregated before being written out to SMF. The time unit may be specified as H – hours, M – minutes, or S – seconds. If the time unit is not specified, the default is S - seconds. The minimum value of usginterval is 1 second. The maximum value is 24 hours.

Example:

AUDITKEYUSGPKDS,LAB=YES,TOKEN=NO
AUDKUP,LAB=YES,TOKEN=NO,INT=3600

AUDITPKCS11USG,AUDP11U

Changes one or more options related to usage auditing of PKCS #11 services.

TOKENOBJ,TOKO = YES|NO

YES

Enables key usage auditing of PKCS #11 token objects.

NO

Disables key usage auditing of PKCS #11 token objects.

SESSIONOBJ,SESSO = YES|NO

YES

Enables key usage auditing of PKCS #11 session objects.

NO

Disables key usage auditing of PKCS #11 session objects.

NOKEY = YES|NO

YES

Enables usage auditing of PKCS #11 services which do not involve an object.

NO

Disables usage auditing of PKCS #11 services which do not involve an object.

INTERVAL,INT = usginterval[H|M|S]

The interval over which key usage records are aggregated before being written out to SMF. The time unit may be specified as H – hours, M – minutes, or S – seconds. If the time unit is not specified, the default is S - seconds. The minimum value of usginterval is 1 second. The maximum value is 24 hours.

Example:

AUDP11U,TOKO=YES,SESSIONOBJ=NO
AUDP11U,TOKO=YES,SESSIONOBJ=NO,NOKEY=YES,INTERVAL=1440M

MKCVLEN = value

Specifies the number of hexadecimal digits to display on the ICSF Coprocessor Hardware Status panel (CSFCMP40) for the verification and hash patterns for the master keys. The patterns are also referred to as key check values. The value may be 2, 3, 4, 5, 6, or ALL. When an integer value is specified, that number of digits will displayed. When ALL is specified, all digits will be displayed.

This option can be used to be in compliance with the ISO11568 standard for display of the key check values for master keys.

Notes:

• This option corresponds to the MASTERKCVLEN option in the ICSF installation options data set. Be aware that when ICSF is restarted, the value will revert to the value specified by the MASTERKCVLEN option in the ICSF installation options data set.
• This option has no effect on the output of the DISPLAY ICSF,MKS command.

PAUSE

ICSF terminates after all in-flight transactions finish, and any new transactions are paused until ICSF is restarted. ICSF must then be restarted via ARM policy, customer automation, or manually. Upon restart, ICSF is loaded from the specified service data set, and paused transactions resume.

Note: Before issuing the SETICSF PAUSE command, see Dynamic service update.

REFRESH

Refreshes supported option parameters whose values have been updated in the current installation options data set listed in the ICSF startup procedure on the CSFPARM DD statement or from the CSFPRMxx member in the parmlib concatenation.

Refreshable option parameters are AUDITKEYLIFECKDS, AUDITKEYLIFEPKDS, AUDITKEYLIFETKDS, AUDITKEYUSGCKDS, AUDITKEYUSGPKDS, AUDITPKCS11USG, BEGIN, CHECKAUTH, CICSAUDIT, COMPLIANCEWARN, DEFAULTWRAP, END, FIPSMODE, KEYARCHMSG, KDSREFDAYS, MASTERKCVLEN, MAXSESSOBJECTS, RNGCACHE, SSM, TRACKCLASSUSAGE, USERPARM, and WAITLIST.

RISEC = interval

Specifies, in seconds, how often a record should be written for a reference date/time change. The values must be between 0 (write a record for every reference) and 2592000 (30 days) seconds. For example:

RISEC=300

Note: OPTions,RISEC corresponds to the KDSREFDAYS option in the ICSF options data set, which can only be specified in full days. When the RISEC option has been used to change the refdate interval, the value for KDSREFDAYS on the Installation Options Display panel is set to SETICSF to indicate that the current value has been modified from the value that is set in the installation options dataset.

RPSEC = period

Specifies how often in seconds ICSF hardens refdate updates to the appropriate key data set. The value must be between 10 and 3600. The default is 3600 seconds. For example:

RPSEC=30

Note: There is no corresponding keyword in the ICSF options data set for the RPSEC option. The value can only be changed using the SETICSF command.

STATS

Updates cryptographic usage tracking options. Keywords can be combined to track multiple statistics.

Each issuance of the command replaces the prior settings. For example, if ENG is tracked and SRV is to be added, then STATS=(ENG,SRV) must be issued.

ENG

Enables usage tracking of cryptographic engines. Supports Crypto Express adapters, CPACF, and software.

SRV

Enables usage tracking of cryptographic services. Supports ICSF callable services and UDXes only.

ALG

Enables usage tracking of cryptographic algorithms. Supports cryptographic algorithms that are referenced in cryptographic operations. Limited support for key generation, key derivation, and key import.

NONE

Disables usage tracking of cryptographic statistics.

TRACKCLASSUSAGE

Updates the options for tracking of classes of cryptographic operations. Keywords can be combined to track multiple classes.

Each issuance of the command replaces the prior settings.

DATAENC

Symmetric keys data encryption operations.

DATADEC

Symmetric keys data decryption operations.

NONE

Disables tracking of classes of cryptographic operations.

Installation options that are modified by the SETICSF command are in effect only until ICSF is stopped or restarted. When ICSF is restarted, the installation options are re-initialized from the ICSF installation options data set. If you want to make the changes permanent, the installation options data set must be manually updated as needed.

RESTART

Restarts specified cryptographic devices. For the specified devices, the work queues are cleared and ICSF runs through normal configuration processing in an attempt to return a device that is in an error state to an active state. This is most appropriate for a device that has had an error such as CARD BUSY.

SYSPLEX(YES or NO)

The SYSPLEX keyword increases the scope of the SETICSF command to all participating members of the sysplex. The SETICSF command is executed locally on the initiating system and then again on each participating member of the sysplex. The output indicates which systems were able to process the request as well as those systems that were not able to process the request due to a lack of support or an error.

Specify SYSPLEX=Yes to execute the command on all systems. When SYSPLEX=YES is specified, the command may affect cryptographic devices on all systems within the sysplex as follows:

• When SN is specified, all cryptographic devices that have the specified serial number or numbers are affected. No other filtering criteria is applied.
• When INDEX is specified instead of SN, additional filtering criteria is applied. Cryptographic devices that do not meet this criteria are skipped:
  • The command will only affect those systems within the sysplex that share the same KDS via the SYSPLEXnKDS(YES,...) ICSF installation option. This includes the originating system.
  • For each such system, both the index or indexes and serial number or numbers must match that of the system where the command was issued. The use of SYSPLEX with INDEX results in the command action being performed on all devices at that index on the originating system as well as the cryptographic device at that index on any system that is sharing the KDS.

    For example, the command SETICSF DEACT,INDEX=1,SYSPLEX=YES would deactivate the cryptographic device at index 01 on the originating system as well as the cryptographic device at index 01 on any system sharing the KDS. In this case, it is better to use SN rather than INDEX as the SETICSF DEACT command can affect devices that have different serial numbers when INDEX is used with SYSPLEX=YES.

Specify SYSPLEX=No to execute the command only on the local (initiating) system. When SYSPLEX=NO is specified or defaulted, the command affects only affects devices on the system where the command was issued.

SYSPLEX=No is the default.

Usage Notes