 |
- return_code
-
| Direction: Output | Type: Integer |
The return code specifies the general result of the callable
service. Appendix A. ICSF and TSS Return and Reason Codes lists the return codes.
- reason_code
-
| Direction: Output | Type: Integer |
The reason code specifies the result of the callable service
that is returned to the application program. Each return code has
different reason codes assigned to it that indicate specific processing
problems. Appendix A. ICSF and TSS Return and Reason Codes lists the reason codes.
- exit_data_length
-
| Direction: Ignored | Type: Integer |
This field is ignored. It is recommended to specify 0 for
this parameter.
- exit_data
-
| Direction: Ignored | Type: String |
This field is ignored.
- rule_array_count
-
| Direction: Input | Type: Integer |
The number of keywords you are supplying in rule_array.
Value must be 1 or 2
- rule_array
-
| Direction: Input | Type: String |
Keywords that provide control information to callable services.
The keywords are left-justified in an 8-byte field and padded on the
right with blanks. The keywords must be in contiguous storage. Specify
one or two of the values in Table 264.
Table 264. Keywords for ICSF Query Service| Keyword | Meaning |
|---|
| Coprocessor (optional) - parameter is ignored
for ICSFSTAT. | | COPROCxx | Specifies the specific coprocessor
to execute the request. xx may be 00 through 63 inclusive. This may
be the processor number of any coprocessor. The processor number
of any accelerator is not supported. | | ANY | Process request on any ACTIVE cryptographic
coprocessor. This is the default. | | nnnnnnnn | Specifies the 8-byte serial number of the coprocessor
to execute the request. | | Information to return (required) | | ICSFSTAT | Get ICSF related status information. | | ICSFST2 | Get coprocessor-related basic
status information. | | NUM-DECT | Get the number of bytes of storage required
for the output of a STATDECT request. | | STATAES | Get status information on AES enablement
and the AES master key registers. | | STATCCA | Get CCA-related status information. | | STATCCAE | Get CCA-related extended status information. | | STATCARD | Get coprocessor-related basic status
information. | | STATDECT | Get the PIN decimalization tables loaded. The
format of the data is shown under the returned_data parameter.
The length of the data is 20 bytes per decimalization table. The NUM-DECT
option will return the storage required for this option. The maximum
length of the data is 2000 bytes. | | STATDIAG | Get coprocessor-related basic status information. | | STATAPKA | Get status information on ECC enablement and
the ECC master key registers. | | STATEID | Get coprocessor-related basic status information. | | STATEXPT | Get coprocessor-related basic status information. | | WRAPMTHD | Get coprocessor-related default configuration
setting for the wrapping method. |
- returned_data_length
-
| Direction: Input/Output | Type: Integer |
The length of the returned_data parameter.
Currently, the value must be at least eight times the number of elements
returned for the rule_array keyword specified. Allow additional
space for future enhancements. On output, this field will contain
the actual length of the data returned.
- returned_data
-
| Direction: Output | Type: String/Integer |
This field will contain the output from the service.
The format of the output depends on the rule_array keyword.
The format of the data is defined in the tables below, which describe
the output for each keyword.
When the format is 8-byte
elements that contain numbers, those numbers are represented by numeric
characters which are left-justified and padded on the right with space
characters. For example, a returned_data element which contains
the number two will contain the character string '2 '.
For option NUM-DECT, the output is a 4-byte integer.
For
ICSFSTAT, the coprocessor keyword is ignored. The output returned_data for
the ICSFSTAT keyword is defined in Table 265.
Table 265. Output for option ICSFSTAT| Element Number | Name | Description | | 1 | FMID | 8-byte ICSF FMID | | 2 | ICSF Status Field 1 | Status of ICSF
- Number
- Meaning
- 0
- ICSF started
- 1
- ICSF initialized (CCVINIT is on)
- 2
- SYM-MK (DES master key) valid (CCVTMK is on)
- 3
- PKA callable services enabled (see Usage Notes)
| | 3 | ICSF Status Field 2 | Status of ICSF
- Number
- Meaning
- 0
- 64-bit callers not supported
- 1
- 64-bit callers supported
- 2
- 64-bit callers supported, and a TKDS has been specified
for the storage of persistent PKCS #11 objects.
| | 4 | CPACF | CPACF availability
- Number
- Meaning
- 0
- CPACF not available
- 1
- SHA-1 available only
- 2
- DES/TDES enabled
- 3
- SHA-224 and SHA-256 are available
- 4
- SHA-224 and SHA-256, DES and TDES are available
- 7
- Encrypted CPACF functions available.
- 8
- OFB, CFB, and GCM CPACF functions are available.
| | 5 | AES | AES availability for clear keys
- Number
- Meaning
- 0
- AES not available
- 1
- AES software only
- 2
- AES-128
- 3
- AES-192 and AES-256
| | 6 | DSA | DSA algorithm availability
- Number
- Meaning
- 0
- DSA not available
- 1
- DSA 1024 key size
- 2
- DSA 2048 key size
| | 7 | RSA Signature | RSA Signature key length
- Number
- Meaning
- 0
- RSA not available
- 1
- RSA 1024 key size
- 2
- RSA 2048 key size
- 3
- RSA 4096 key size
| | 8 | RSA Key Management | RSA Key Management key length
- Number
- Meaning
- 0
- RSA not available
- 1
- RSA 1024 key size
- 2
- RSA 2048 key size
- 3
- RSA 4096 key size
| | 9 | RSA Key Generate | RSA Key Generate
- Number
- Meaning
- 0
- Service not available
- 1
- Service available - 2048 bit modulus
- 2
- Service available - 4096 bit modulus
| | 10 | Accelerators | Availability of clear RSA key accelerators (PCICAs)
- Number
- Meaning
- 0
- Not available
- 1
- At least one available for application use.
| | 11 | Accelerator Key Size |
Clear key size supported by Accelerators.
There must be at least one Accelerator available for use for this
field to contain valid information.
- Number
- Meaning
- 0
- RSA-ME key size of 2048, CRT key size of 2048.
- 1
- RSA-ME key size of 4096, CRT key size of 4096.
| | 12 | Future Use | Currently blanks | For ICSFST2 the coprocessor rule array keyword is ignored.
The output returned_data for the ICSFST2 keyword is defined
in Table 266.
Table 266. Output for option ICSFST2| Element Number | Name | Description | | 1 | Version | Version of the ICSFST2 returned_data. Initial
value is 1. It covers elements 1 through 12. | | 2 | FMID | 8–byte ICSF FMID. | | 3 | ICSF Status Field 1 | Status of ICSF
- Number
- Meaning
- 0
- PKA callable services disabled
- 1
- PKA callable services enabled (see Usage Notes)
| | 4 | ICSF Status Field 2 | Status of ICSF
- Number
- Meaning
- 0
- PKCS #11 is not available
- 1
- PKCS #11 is available
| | 5 | ICSF Status Field 3 | Status of ICSF
- Number
- Meaning
- 0
- ICSF started
- 1
- ICSF initialized
- 2
- AES master key valid
| | 6 | ICSF Status Field 4 | Status of ICSF
- Number
- Meaning
- 0
- Secure key AES not available
- 1
- Secure key AES is available
| | 7 | ICSF Status Field 5 | An 8-character
numeric character string summarizing the current Key Store Policy.
The
first character in this string indicates if Key Token Authorization
Checking controls have been enabled for the CKDS in either warning
or fail mode, and, if so, if the Default Key Label Checking control
has also been enabled. The numbers that can appear in the first character
of this string are:
- Number
- Meaning
- 0
- Key Token Authorization Checking is not enabled for the CKDS.
- 1
- Key Token Authorization Checking for CKDS is enabled in FAIL
mode. Key Store Policy is active for CKDS. Default
Key Label Checking is not enabled.
- 2
- Key Token Authorization Checking for CKDS is enabled in WARN
mode. Key Store Policy is active for CKDS. Default
Key Label Checking is not enabled.
- 3
- Key Token Authorization Checking for CKDS is enabled in FAIL
mode. Key Store Policy is active for CKDS. Default
Key Label Checking is also enabled.
- 4
- Key Token Authorization Checking for CKDS is enabled in WARN
mode. Key Store Policy is active for CKDS. Default
Key Label Checking is also enabled.
| | |
The second character
in this string indicates if Duplicate Key Token Checking controls
have been enabled for the CKDS. The numbers that can appear in the
second character of this string are:
- Number
- Meaning
- 0
- Duplicate Key Token Checking is not enabled for the CKDS.
- 1
- Duplicate Key Token Checking is enabled for the CKDS. Key Store Policy is active for CKDS.
| | |
The third character
in this string indicates if Key Token Authorization Checking controls
have been enabled for the PKDS in either warning or fail mode, and,
if so, if the Default Key Label Checking control has also been enabled.
The numbers that can appear in the third character of this string
are:
- Number
- Meaning
- 0
- Key Token Authorization Checking is not enabled for the PKDS.
- 1
- Key Token Authorization Checking for PKDS is enabled in FAIL
mode. Key Store Policy is active for PKDS. Default
Key Label Checking is not enabled.
- 2
- Key Token Authorization Checking for PKDS is enabled in WARN
mode. Key Store Policy is active for PKDS. Default
Key Label Checking is not enabled.
- 3
- Key Token Authorization Checking for PKDS is enabled in FAIL
mode. Key Store Policy is active for PKDS. Default
Key Label Checking is also enabled.
- 4
- Key Token Authorization Checking for PKDS is enabled in WARN
mode. Key Store Policy is active for PKDS. Default
Key Label Checking is also enabled.
| | |
The fourth character
in this string indicates if Duplicate Key Token Checking controls
have been enabled for the PKDS. The numbers that can appear in the
fourth character of this string are:
- Number
- Meaning
- 0
- Duplicate Key Token Checking is not enabled for the PKDS.
- 1
- Duplicate Key Token Checking is enabled for the PKDS. Key Store Policy is active for PKDS.
| | |
The fifth character
in this string indicates if Granular Key Label Access controls have
been enabled in WARN or FAIL mode. The numbers that can appear in
the fifth character of this string are:
- Number
- Meaning
- 0
- Granular Key Label Access controls are not enabled.
- 1
- Granular Key Label Access control is enabled in FAIL mode
- 2
- Granular Key Label Access control is enabled in WARN mode
| | |
The sixth character
in this string indicates if Symmetric Key Label Export controls have
been enabled for AES and/or DES keys. The numbers that can appear
in the sixth character of this string are:
- Number
- Meaning
- 0
- Symmetric Key Label Export controls are not enabled.
- 1
- Symmetric Key Label Export control is enabled for DES keys only.
- 2
- Symmetric Key Label Export control is enabled for AES keys only.
- 3
- Symmetric Key Label Export controls are enabled for both DES
and AES keys.
| | |
The seventh character
in this string indicates if PKA Key Management Extensions have been
enabled in either WARN or FAIL mode, and, if so, whether a SAF key
ring or a PKCS #11 token is identified as the trusted certificate
repository. (The trusted certificate repository is identified using
the APPLDATA field of the CSF.PKAEXTNS.ENABLE profile. If no value
is specified in the APPLDATA field, a PKCS #11 token is assumed.)
The numbers that can appear in the seventh character of this string
are:
- Number
- Meaning
- 0
- Symmetric Key Label Export controls are not enabled.
- 1
- PKA Key Management Extensions control is enabled in FAIL mode.
The trusted certificate repository is a SAF key ring.
- 2
- PKA Key Management Extension control is enabled in FAIL mode.
The trusted certificate repository is a PKCS #11 token.
- 3
- PKA Key Management Extensions control is enabled in WARN mode.
The trusted certificate repository is a SAF key ring.
- 4
- PKA Key Management Extension control is enabled in WARN mode.
The trusted certificate repository is a PKCS #11 token.
| | 8 | ICSF Status Field 6 | Status of ICSF
- Number
- Meaning
- 0
- ICSF started
- 1
- ICSF initialized
- 2
- ECC master key valid, internal keys supported
- 3
- ECC master key valid, external keys also supported
| | 9 | ICSF Status Field 7 | Status of ICSF
- Number
- Meaning
- 0
- ICSF started
- 1
- ICSF initialized
- 2
- RSA master key valid
| | 10 | ICSF Status Field 8 | Status of ICSF
- Number
- Meaning
- 0
- ICSF started
- 1
- ICSF initialized
- 2
- DES master key valid
| | 11 | ICSF Status Field 9 | Status of ICSF
- Number
- Meaning
- 0
- PKA callable services disabled.
- 1
- PKA callable services enabled.
See Usage Notes for additional information. | | 12 | Future use | Currently blanks |
Table 267. Output for option NUM-DECT| Element Number | Description | | 1 | The number of bytes required for
the output of a STATDECT request. This is the number of decimalization
tables loaded times 20 bytes. This is a four-byte binary number. |
Table 268. Output for option STATAES| Element Number | Name | Description | | 1 | AES NMK Status | State of the AES new master key register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a partially complete key
- 3
- Register contains a complete key
| | 2 | AES CMK Status | State of the AES current master key register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a key
| | 3 | AES OMK Status | State of the AES old master key register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a key
| | 4 | AES key length enablement | The maximum AES key length that is enabled by
the function control vector. The value is 0 (if no AES key length
is enabled in the FCV), 128, 192, or 256. |
Table 269. Output for option STATCCA| Element Number | Name | Description | | 1 | NMK Status | State of the DES New Master Key Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a partially complete key
- 3
- Register contains a complete key
| | 2 | CMK Status | State of the DES Current Master Key
Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a key
| | 3 | OMK Status | State of the DES Old Master Key Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a key
| | 4 | CCA Application Version | A character string that identifies the version
of the CCA application program that is running in the coprocessor. | | 5 | CCA Application Build Date | A character string containing the build date
for the CCA application program that is running in the coprocessor. | | 6 | User Role | A character string containing the Role identifier
which defines the host application user's current authority. |
Table 270. Output for option STATCCAE| Element Number | Name | Description | | 1 | Symmetric NMK Status | State of the DES Symmetric New Master
Key Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a partially complete key
- 3
- Register contains a complete key
| | 2 | Symmetric CMK Status | State of the DES Symmetric Current
Master Key Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a key
| | 3 | Symmetric OMK Status | State of the DES Symmetric Old Master
Key Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a key
| | 4 | CCA Application Version | A character string that identifies the version
of the CCA application program that is running in the coprocessor. | | 5 | CCA Application Build Date | A character string containing the build date
for the CCA application program that is running in the coprocessor. | | 6 | User Role | A character string containing the Role identifier
which defines the host application user's current authority. | | 7 | Asymmetric NMK Status | State of the RSA Asymmetric New Master Key Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a partially complete key
- 3
- Register contains a complete key
| | 8 | Asymmetric CMK Status | State of the RSA Asymmetric Current Master Key
Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a key
| | 9 | Asymmetric OMK Status | State of the RSA Asymmetric Old Master Key Register:
- Number
- Meaning
- 1
- Register is clear
- 2
- Register contains a key
|
Table 271. Output for option STATCARD| Element Number | Name | Description | | 1 | Number of installed adapters | The number of active cryptographic coprocessors
installed in the machine. This only includes coprocessors that have
CCA software loaded (including those with CCA UDX software). | | 2 | DES hardware level | A numeric character string containing an integer
value identifying the version of DES hardware that is on the coprocessor. | | 3 | RSA hardware level | A numeric character string containing an integer
value identifying the version of RSA hardware that is on the coprocessor. | | 4 | POST Version | A character string identifying the version of
the coprocessor's Power-On Self Test (POST) firmware. The first four
characters define the POST0 version and the last four characters define
the POST1 version. | | 5 | Coprocessor Operating System Name | A character string identifying the operating
system firmware on the coprocessor. Padding characters are blanks. | | 6 | Coprocessor Operating System Version | A character string identifying the version of
the operating system firmware on the coprocessor. | | 7 | Coprocessor Part Number | A character string containing the eight-character
part number identifying the version of the coprocessor. | | 8 | Coprocessor EC Level | A character string containing the eight-character
EC (engineering change) level for this version of the coprocessor. | | 9 | Miniboot Version | A character string identifying the version of
the coprocessor's miniboot firmware. This firmware controls the loading
of programs into the coprocessor.
The first four characters define
the MiniBoot0 version and the last four characters define the MiniBoot1
version. | | 10 | CPU Speed | A numeric character string containing the operating
speed of the microprocessor chip, in megahertz. | | 11 | Adapter ID (Also see element number 15) | A unique identifier manufactured into the
coprocessor. The coprocessor's Adapter ID is an eight-byte binary
value. | | 12 | Flash Memory Size | A numeric character string containing the size
of the flash EPROM memory on the coprocessor, in 64-kilobyte increments. | | 13 | DRAM Memory Size | A numeric character string containing the size
of the dynamic RAM (DRAM) on the coprocessor, in kilobytes. | | 14 | Battery-Backed Memory Size | A numeric character string containing the size
of the battery-backed RAM on the coprocessor, in kilobytes. | | 15 | Serial Number | A character string containing the unique serial
number of the coprocessor. The serial number is factory installed
and is also reported by the CLU utility in a coprocessor signed status
message. | For STATDECT, the output is a table of up
to 100 PIN decimalization tables as shown in the following table.
The maximum size is 2000 bytes.
Table 272. Output for option STATDECT| Offset | Field | Description | | 0 | Number | Numeric character indicating the table number | | 3 | State | Character indicating the state of the table
- L
- loaded
- A
- active
| | 4 | Table | 16-byte decimalization table |
Table 273. Output for option STATDIAG| Element Number | Name | Description | | 1 | Battery State | A numeric character string containing a value
which indicates whether the battery on the coprocessor needs to be
replaced:
- Number
- Meaning
- 1
- Battery is good
- 2
- Battery should be replaced
| | 2 | Intrusion Latch State | A numeric character string containing a value
which indicates whether the intrusion latch on the coprocessor is
set or cleared:
- Number
- Meaning
- 1
- Latch is cleared
- 2
- Latch is set
| | 3 | Error Log Status | A numeric character string containing a value
which indicates whether there is data in the coprocessor CCA error
log.
- Number
- Meaning
- 1
- Error log is empty
- 2
- Error log contains data but is not yet full
- 3
- Error log is full
| | 4 | Mesh Intrusion | A numeric character string containing a value
to indicate whether the coprocessor has detected tampering with the
protective mesh that surrounds the secure module — indicating
a probable attempt to physically penetrate the module.
- Number
- Meaning
- 1
- No intrusion detected
- 2
- Intrusion attempt detected.
| | 5 | Low Voltage Detected | A numeric character string containing a value
to indicate whether a power supply voltage was under the minimum acceptable
level. This may indicate an attempt to attack the security module.
- Number
- Meaning
- 1
- Only acceptable voltages have been detected
- 2
- A voltage has been detected under the low-voltage tamper threshold
| | 6 | High Voltage Detected | A numeric character string containing a value
to indicate whether a power supply voltage was higher than the maximum
acceptable level. This may indicate an attempt to attack the security
module.
- Number
- Meaning
- 1
- Only acceptable voltages have been detected
- 2
- A voltage has been detected that is higher than the high-voltage
tamper threshold
| | 7 | Temperature Range Exceeded | A numeric character string containing a value
to indicate whether the temperature in the secure module was outside
of the acceptable limits. This may indicate an attempt to obtain information
from the module:
- Number
- Meaning
- 1
- Temperature is acceptable
- 2
- Detected temperature is outside an acceptable limit
| | 8 | Radiation Detected | A numeric character string containing a value
to indicate whether radiation was detected inside the secure module.
This may indicate an attempt to obtain information from the module:
- Number
- Meaning
- 1
- No radiation has been detected
- 2
- Radiation has been detected
| | 9, 11, 13, 15, 17 | Last Five Commands Run | These five rule-array elements contain the last
five commands that were executed by the coprocessor CCA application.
They are in chronological order, with the most recent command in element
9. Each element contains the security API command code in the first
four characters and the subcommand code in the last four characters. | | 10, 12, 14,16, 18 | Last Five Return Codes | These five rule-array elements contain the SAPI
return codes and reason codes corresponding to the five commands in
rule-array elements 9, 11, 13, 15, and 17. l Each element contains
the return code in the first four characters and the reason code in
the last four characters. |
Table 275. Output for option STATEXPT| Element Number | Name | Description | | 1 | Base CCA Services Availability | A numeric character string containing a value
to indicate whether base CCA services are available.
- Number
- Meaning
- 0
- Base CCA services are not available
- 1
- Base CCA services are available
| | 2 | CDMF Availability | A numeric character string containing a value
to indicate whether CDMF is available.
- Number
- Meaning
- 0
- CDMF encryption is not available
- 1
- CDMF encryption is available
| | 3 | 56-bit DES Availability | A numeric character string containing a value
to indicate whether 56-bit DES encryption is available.
- Number
- Meaning
- 0
- 56-bit DES encryption is not available
- 1
- 56-bit DES encryption is available
| | 4 | Triple-DES Availability | A numeric character string containing a value
to indicate whether triple-DES encryption is available.
- Number
- Meaning
- 0
- Triple-DES encryption is not available
- 1
- Triple-DES encryption is available
| | 5 | SET Services Availability | A numeric character string containing a value
to indicate whether SET (Secure Electronic Transaction) services are
available.
- Number
- Meaning
- 0
- SET Services are not available
- 1
- SET Services are available
| | 6 | Maximum Modulus for Symmetric Key Encryption | A numeric character string containing the maximum
modulus size that is enabled for the encryption of symmetric keys.
This defines the longest public-key modulus that can be used for key
management of symmetric-algorithm keys.
- Number
- Meaning
- 0
- DSA not available
- 1024
- DSA 1024 key size
- 2048
- DSA 2048 key size
- 4096
- RSA 4096 key size
|
Table 276. Output for option STATAPKA| Element Number | Name | Description | | 1 | ECC NMK status | The state of the ECC new master key register:
- Number
- Meaning
- 1
- Register is clear.
- 2
- Register contains a partially complete key.
- 3
- Register contains a complete key.
| | 2 | ECC CMK status | The state of the ECC current master key register:
- Number
- Meaning
- 1
- Register is clear.
- 2
- Register contains a key.
| | 3 | ECC OMK status | The state of the ECC old master key register:
- Number
- Meaning
- 1
- Register is clear.
- 2
- Register contains a key.
| | 4 | ECC key length enablement | The maximum ECC curve size that is enabled by
the function control vector. The value will be 0 (if no ECC keys
are enabled in the FCV) and 521 for the maximum size. |
Table 277. Output for option WRAPMTHD| Element Number | Name | Description | | 1 | Internal tokens | Default wrapping method for internal tokens.
- Number
- Meaning
- 0
- Keys will be wrapped with the original method
- 1
- Keys will be wrapped with the enhanced X9.24 method
| | 2 | External tokens | Default wrapping method for external tokens.
- Number
- Meaning
- 0
- Keys will be wrapped with the original method
- 1
- Keys will be wrapped with the enhanced X9.24 method
|
- reserved_data_length
-
| Direction: Input | Type: Integer |
The length of the reserved_data parameter.
Currently, the value must be 0.
- reserved_data
-
| Direction: Input | Type: String |
This field is currently not used.
|
z/OS Cryptographic Services ICSF Application Programmer's Guide
Copyright IBM Corporation 1990, 2014