SETICSF

Syntax

Add keyword

Parameters

ACTivate

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

REMOTEdevice

The regional cryptographic server or servers (remote device or devices). REMOTEdevice is optional.

Notes:

• At least one REMOTEDEVICE option must have been specified in the ICSF installation options data set prior to ICSF being started in order for the SETICSF ACTivate,REMOTEdevice command to be operational.
• In addition, the current machine type must be an IBM zEnterprise EC12 or later machine.
• If ICSF is started without any REMOTEDEVICE entries specified in the ICSF installation options data set or while running on a machine type other than an IBM zEnterprise EC12 or later machine, the command fails, and ICSF issues message CSFM670I.

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, or 1-16 when REMOTEdevice is specified. 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.

ADD

Adds a regional cryptographic server (single system only).

Notes:

• At least one REMOTEDEVICE option must have been specified in the ICSF installation options data set prior to ICSF being started in order for the SETICSF ADD,REMOTEdevice command to be operational.
• In addition, the current machine type must be an IBM zEnterprise EC12 or later machine.
• If ICSF is started without any REMOTEDEVICE entries specified in the ICSF installation options data set or while running on a machine type other than an IBM zEnterprise EC12 or later machine, the ADD command fails and ICSF issues message CSFM670I.
• SYSPLEX=YES is not supported for the SETICSF ADD,REMOTEdevice command.

REMOTEdevice|RD

The regional cryptographic server or servers (remote device or devices). All of the following operands must be specified:

INDEX=index-number

Specify the index of the device to be added. Specify a number between 1 and 16, inclusive. Each operational REMOTEDEVICE must have a unique number so SETICSF ADDing a index that already exists will fail. For indexes that are repeated, ICSF will only save the last one specified. Additionally, if remote devices or ports are shared between sysplex members, it is strongly recommended that the same index number is used for each member.

IP=ip-addr-or-hostname

Specify the dotted-decimal Internet protocol (IP) version 4 address or the hostname of the remote device. Each ip-addr-or-hostname must locate a single device with fixed serial number. Reverse proxy arrangements where one ip-addr-or-hostname is backed by multiple devices (with different serial numbers) is not supported. The opposite arrangement (one serial number assigned to multiple ip-addr-or-hostnames) is supported, but not recommended.

Notes:

• Hostnames are not case-sensitive and are stored and displayed by ICSF in lowercase.

PORT=port-number

Specify the port number to be used in conjunction with the IP address or hostname when connecting.

Note: No two ICSF instances may share the same port on a regional cryptographic server. Additionally, it is expected that different workloads (for example, ICSF instances using different token data sets) sharing a regional cryptographic server would use different master keys (RCS-MKs) and that the required RCS-MK for the TKDS would be assigned on a per port basis.

SOCK=number-sockets

Specify the maximum number of sockets ICSF is to open for connections with the remote device. This is a value between 1 and 8, inclusive. Multiple sockets are required in order for ICSF to process multiple simultaneous requests. Consult the remote device's documentation to determine this value. There is an ICSF limit of 8 sockets per REMOTEDEVICE entry. If you desire more than 8 socket connections to a single server, then configure multiple ports on the server and define multiple REMOTEDEVICE entries, one per port. Note that the index value must be unique for each entry.

CHECK

Attempts to reopen sockets that were not previously opened.

REMOTEdevice

The regional cryptographic server or servers (remote device or devices).

Notes:

• At least one REMOTEDEVICE option must have been specified in the ICSF installation options data set prior to ICSF being started in order for the SETICSF CHECK,REMOTEdevice command to be operational.
• In addition, the current machine type must be an IBM zEnterprise EC12 or later machine.
• If ICSF is started without any REMOTEDEVICE entries specified in the ICSF installation options data set or while running on a machine type other than an IBM zEnterprise EC12 or later machine, the command fails, and ICSF issues message CSFM670I.

SN=serialnumber

Specify the serial number or numbers of the device or devices to be checked. 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 checked. Specify a number between 1 and 16, inclusive. 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)

DEACTivate

Deactivates specified cryptographic devices. The valid device specification are:

REMOTEdevice

The regional cryptographic server or servers (remote device or devices). REMOTEdevice is optional.

Notes:

• At least one REMOTEDEVICE option must have been specified in the ICSF installation options data set prior to ICSF being started in order for the SETICSF DEACTivate,REMOTEdevice command to be operational.
• In addition, the current machine type must be an IBM zEnterprise EC12 or later machine.
• If ICSF is started without any REMOTEDEVICE entries specified in the ICSF installation options data set or while running on a machine type other than an IBM zEnterprise EC12 or later machine, the command fails, and ICSF issues message CSFM670I.

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, or 1-16 when REMOTEdevice is specified. 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.

DELETE

Removes a regional cryptographic server from a system or systems.

REMOTEdevice

The regional cryptographic server or servers (remote device or devices).

Notes:

• At least one REMOTEDEVICE option must have been specified in the ICSF installation options data set prior to ICSF being started in order for the SETICSF DELETE,REMOTEdevice command to be operational.
• In addition, the current machine type must be an IBM zEnterprise EC12 or later machine.
• If ICSF is started without any REMOTEDEVICE entries specified in the ICSF installation options data set or while running on a machine type other than an IBM zEnterprise EC12 or later machine, the command fails, and ICSF issues message CSFM670I.

SN=serialnumber

Specify the serial number or numbers of the device or devices to be deleted. 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 deleted. Specify a number between 1 and 16, inclusive. 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)

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.

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.

Refreshable option parameters are AUDITKEYLIFECKDS, AUDITKEYLIFEPKDS, AUDITKEYLIFETKDS, AUDITKEYUSGCKDS, AUDITKEYUSGPKDS, AUDITPKCS11USG, BEGIN, CHECKAUTH, DEFAULTWRAP, END, FIPSMODE, KEYARCHMSG, KDSREFDAYS, MASTERKCVLEN, MAXSESSOBJECTS, RNGCACHE, SSM, 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. 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.

Installation options modified by the SETICSF command are in effect only until ICSF is stopped or restarted. When ICSF is restarted, the installation options will be 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. The valid device specification are:

REMOTEdevice

The regional cryptographic server or servers (remote device or devices). REMOTEdevice is optional.

Notes:

• At least one REMOTEDEVICE option must have been specified in the ICSF installation options data set prior to ICSF being started in order for the SETICSF RESTART,REMOTEdevice command to be operational.
• In addition, the current machine type must be an IBM zEnterprise EC12 or later machine.
• If ICSF is started without any REMOTEDEVICE entries specified in the ICSF installation options data set or while running on a machine type other than an IBM zEnterprise EC12 or later machine, the command fails, and ICSF issues message CSFM670I.

SN=serialnumber

Specify the serial number or numbers of the device or devices to be restarted. 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 restarted. The valid range is 0 to 63, or 1-16 when REMOTEdevice is specified. 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.

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 TKDS via the SYSPLEXTKDS(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. For example:
    • The command SETICSF DEACT,REMOTE,INDEX=1,SYSPLEX=YES would deactivate the remote device at index 01 on the originating system as well as the remote device at index 01 on any system sharing the KDS provided that the remote device at index 01 on that system represents the same regional cryptographic server (same serial number).
    • If the REMOTE keyword is not specified, 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 index 01 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 and the command is issued without the REMOTE keyword.

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

SYSPLEX=No is the default.

Usage Notes