SETICSF

The SETICSF command is used to perform the following specific administration functions:
  • Activate, deactivate, or restart a cryptographic device.
  • Add, check, or delete a regional cryptographic device.
  • Attempt to reopen sockets that were not previously opened.
  • Change a subset of ICSF's installation options.
  • Enable or disable updates to a key data set (KDS).
  • Change cryptographic usage tracking options.
  • Change key lifecycle auditing options.
  • Change key usage auditing options.
  • Pause transactions until ICSF is restarted.
  • Refresh some options in the installation options data set.
Note: For additional information on these administrative functions and their impact on ICSF and cryptographic devices, see z/OS Cryptographic Services ICSF Administrator's Guide.

Syntax

Read syntax diagramSkip visual syntax diagramSETICSF ACTivateDEACTivateRESTART,REMOTEdevice|RD,SN=serialnumber,INDEX=indexlistCHECKDELETE,REMOTEdevice|RD,SN=serialnumber,INDEX=indexlistENableDISable,CKDS,PKDS,TKDSOPTions,AUDITKEYLIFECKDSAUDKLC,TOKen={Yes|No},LABel={Yes|No}AUDITKEYLIFEPKDSAUDKLP,TOKen={Yes|No},LABel={Yes|No}AUDITKEYLIFETKDSAUDKLT,TOKenObj={Yes|No},SESSionObj={Yes|No}AUDITKEYUSGCKDSAUDKUC,TOKen={Yes|No},LABel={Yes|No},INTerval=usgintervalAUDITKEYUSGPKDSAUDKUP,TOKen={Yes|No},LABel={Yes|No},INTerval=usgintervalAUDITPKCS11USGAUDP11U,TOKenObj={Yes|No},SESSionObj={Yes|No},NOKEY={Yes|No},INTerval=usginterval,MKCVLEN=valueRISEC=intervalRPSEC=periodREFRESHSTATS=(,ENGSRVALGNONE)PAUSE ,SYSPLEXNoYes
Add keyword
Read syntax diagramSkip visual syntax diagram ADD ,REMOTEdevice|RD,INDEX=indexlist,IP=ip-addr-or-hostname,PORT=port-number,SOCK=number-sockets

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.
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, 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.
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, regional cryptographic servers, 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.

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

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.

For information on how to limit the use of MVS console commands to a specific set of users, see the System Operations topic in z/OS MVS System Commands.