 |
- 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 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 supplied in the rule_array parameter.
This value must be 1.
- rule_array
-
| Direction: Input | Type: String |
Keywords that provide control information to the callable
service. Each keyword is left-justified in 8-byte fields and padded
on the right with blanks. All keywords must be in contiguous storage.
Table 291. Keywords for derive multiple keys| Keyword | Meaning |
|---|
| Mechanism
(required) | | SSL-KM | Use
the SSL 3.0 Key and MAC derivation protocol as defined in the PKCS
#11 standard as mechanism CKM_SSL3_KEY_AND_MAC_DERIVE. | | TLS-KM | Use
the TLS 1.0/1.1 Key and MAC derivation protocol as defined in the
PKCS #11 standard as mechanism CKM_TLS_KEY_AND_MAC_DERIVE. | | IKE1PHA1 | Use the IKEv1 phase 1 protocol to derive multiple
keys using a previously derived IKE seed key as the base key and a
previously derived secret key as an additional key. 3 keys are derived
(one derivation, one authentication, and one encryption key).
Using
IKE terminology, this mechanism performs {SKEYID_d | SKEYID_a | SKEYID_e} = prf(SKEYID, g^xy | CKY-I | CKY-R) with key expansion for SKEYID_e,
if required. (SKEYID_d,a are always the size
of the prf output.)
Where:
- CKY-I | CKY-R -
is the concatenated initiator/responder cookie string
- SKEYID - is the base key
- g^xy - is the additional key
- SKEYID_d,a,e - are the to-be-derived derivation,
authentication and encryption keys
| | IKE2PHA1 | Use the IKEv2 phase 1 (SA) protocol to derive
multiple keys using a previously derived IKE seed key as the base
key. 7 keys are derived (one derivation, two authentication, two encryption,
and two peer authentication keys).
Using IKE terminology, this
mechanism performs {SK_d | SK_ai | SK_ar | SK_ei | SK_er | SK_pi | SK_pr } = prf+(SKEYSEED, Ni | Nr | SPIi | SPIr ).
Where:
- Ni | Nr | SPIi | SPIr - is the concatenated
initiator/responder nonce and Security Parameter Index string
- SKEYSEED - is the base key
- SK_d,ai,ar,ei,er,pi,pr - are the to-be-derived
derivation, initiator authentication, responder authentication, initiator
encryption, responder encryption, initiator peer authentication, and
responder peer authentication keys
| | IKE1PHA2 | Use the IKEv1 phase 2 (CHILD SA) protocol to
derive multiple keys and salt values using a previously derived IKE
derivation key as the base key and a previously derived secret key
as an additional key (optional). The derivation produces one of the
following key sets:
- One authentication key
- One GMAC key plus salt value
- One authentication key plus one encryption key
- One GCM key plus a salt value
Up to two such sets are produced, one for the sender and one
for the receiver.
Using IKE terminology, this mechanism performs KEYMAT = prf(SKEYID_d, [g^xy |] protocol | SPI | Ni_b | Nr_b), done in
two passes - once for the sender and once for the receiver.
Where:
- protocol | SPI | Ni_b | Nr_b - is the concatenated
Protocol, Security Parameter Index, and initiator/responder nonce
string
- SKEYID_d - is the base key
- g^xy - is the optional additional key
- KEYMAT - is the generated key material
which is partitioned into the key set
| | IKE2PHA2 | Use the IKEv2 phase 2 protocol to derive multiple
keys and salt values using a previously derived IKE derivation key
as the base key and a previously derived secret key as an additional
key (optional). The derivation produces one of the following key sets:
- One authentication key
- One GMAC key plus salt value
- One authentication key plus one encryption key
- One GCM key plus a salt value
Two such sets are produced, one for the initiator and one
for the responder.
Using IKE terminology, this mechanism performs KEYMAT = prf+(SK_d, [g^ir |] Ni | Nr ).
Where:
- Ni | Nr - is the
concatenated initiator/responder nonce string
- SK_d - is the base key
- g^ir - is the optional additional key
- KEYMAT - is the generated key material
which is partitioned into the key set
|
- attribute_list_length
-
| Direction: Input | Type: Integer |
The length of the attributes supplied in the attribute_list parameter
in bytes. The maximum value for this field is 32752.
- attribute_list
-
| Direction: Input | Type: String |
List of attributes for the derived secret key
object. See Attribute List for the format
of an attribute_list .
- base_key_handle
-
| Direction: Input | Type: String |
The 44-byte handle of the base key object. See Handles for the format of a key_handle.
- parms_list_length
-
| Direction: Input | Type: Integer |
The length of the parameters supplied in the parms_list parameter
in bytes.
- parms_list
-
| Direction: Input/Output | Type: String |
The protocol specific parameters. This field has a varying
format depending on the mechanism specified:
Table 292. parms_list parameter format for SSL-KM and TLS-KM mechanisms| Offset | Length in bytes | Direction | Description |
|---|
| 0 | 1 | Input | Boolean indicating if “export"
processing is required. Any value other than x'00' means
yes | | 1 | 3 | Not applicable | reserved | | 4 | 4 | Input | length in bytes of the client's random
data (x) ), where 1 <= length <= 32 | | 8 | 4 | Input | length in bytes of the server's random
data (y) ), where 1 <= length <= 32 | | 12 | 4 | Input | size of MAC to be generated in bits, where
8 <= size <= 384, in multiples of 8 | | 16 | 4 | Input | size of key to be generated in bits, Must
match a supported size for the key type specified in the attribute
list. Zero if no encryption keys are to be generated. | | 20 | 4 | Input | size of IV to be generated in bits (v),
where 0<= size <= 128, in multiples of 8. Must
be zero if no encryption keys are to be generated. | | 24 | 44 | Output | handle of client MAC secret object created | | 68 | 44 | Output | handle of server MAC secret object created | | 112 | 44 | Output | handle of client key object created | | 156 | 44 | Output | handle of server key object created | | 200 | x | Input | client's random data | | 200+x | y | Input | server's random data | | 200+x+y | v/8 | Output | client's IV | | 200+x+y+v/8 | v/8 | Output | server's IV |
Table 293. parms_list parameter format for IKE1PHA1 mechanism| Offset | Length in bytes | Direction | Description |
|---|
| 0 | 1 | Input | IKE version code. Must be x'01' | | 1 | 1 | Input | PRF function code x'01' = HMAC_MD5, x'02'
= HMAC_SHA1, x'04' = HMAC_SHA256, x'05' = SHA384,
and x'06' = SHA512 | | 2 | 4 | Input | reserved | | 6 | 2 | Input | length of to-be-derived encryption key,
SKEYID_e | | 8 | 44 | Input | Key handle of additional key | | 52 | 16 | Input | Concatenated cookie string | | 68 | 44 | Output | SKEYID_d key handle | | 112 | 44 | Output | SKEYID_a key handle | | 156 | 44 | Output | SKEYID_e key handle |
Table 294. parms_list parameter format for IKE2PHA1 mechanism| Offset | Length in bytes | Direction | Description |
|---|
| 0 | 1 | Input | IKE version code. Must be x'02' | | 1 | 1 | Input | PRF function code x'01' = HMAC_MD5, x'02'
= HMAC_SHA1, x'04' = HMAC_SHA256, x'05' = SHA384,
and x'06' = SHA512 | | 2 | 2 | Input | length of to-be-derived derivation key,
SK_d | | 4 | 2 | Input | length of a single to-be-derived authentication
key, SK_a | | 6 | 2 | Input | length of a single to-be-derived encryption
key, SK_e | | 8 | 2 | Input | length of a single to-be-derived peer authentication
key, SK_p | | 10 | 2 | Input | Concatenated nonce, SPI string length (n),
where 24 <= n <= 520 | | 12 | 44 | Output | SKEYID_d key handle | | 56 | 44 | Output | Initiator SKEYID_a key handle | | 100 | 44 | Output | Responder SKEYID_a key handle | | 144 | 44 | Output | Initiator SKEYID_e key handle | | 188 | 44 | Output | Responder SKEYID_e key handle | | 232 | 44 | Output | Initiator SKEYID_p key handle | | 276 | 44 | Output | Responder SKEYID_p key handle | | 320 | n | Input | Concatenated nonce, SPI string |
Table 295. parms_list parameter format for IKE1PHA2 and IKE2PHA2 mechanisms| Offset | Length in bytes | Direction | Description |
|---|
| 0 | 1 | Input | IKE version code. Must be x'01'
for IKE1PHA2, x'02' for IKE2PHA2 | | 1 | 1 | Input | PRF function code x'01' = HMAC_MD5, x'02'
= HMAC_SHA1, x'04' = HMAC_SHA256, x'05' = SHA384,
and x'06' = SHA512 | | 2 | 2 | Input | length of to-be-derived salts (s), where
0 <= s <= 4. Zero if salts are not to be derived | | 4 | 2 | Input | length of to-be-derived authentication keys.
Zero if authentication keys are not to be derived | | 6 | 2 | Input | length of to-be-derived encryption, GMAC,
or GCM keys. Zero if no such keys are to be derived | | 8 | 2 | Input | First pass parameter string length (n)
- For IKE1PHA2 - Receiver concatenated Protocol, Security
Parameter Index, and initiator/responder nonce string length, where
25 <= n <= 525
- For IKE2PHA2 – Concatenated initiator/responder nonce string
length, where 16 <= n <= 512.
| | 10 | 2 | Input | Second pass parameter string length (m)
- For IKE1PHA2 - Sender concatenated Protocol, Security Parameter
Index, and initiator/responder nonce string length, where 25 <=
m <= 525. Zero if second pass is to be skipped
- For IKE2PHA2 – Not used. Must be zero
| | 12 | 44 | Input | Key handle of additional key. Fill with
binary zeros if n/a | | 56 | 44 | Output | Initiator (sender) authentication key handle | | 100 | 44 | Output | Responder (receiver) authentication key
handle | | 144 | 44 | Output | Initiator (sender) encryption, GMAC, or
GCM key handle | | 188 | 44 | Output | Responder (receiver) encryption, GMAC, or
GCM key handle | | 232 | n | Input | First pass parameter string | | 232+n | m | Input | Second pass parameter string | | 232+n+m | s | Output | Initiator (sender) salt | | 232+n+m+s | s | Output | Responder (receiver) salt |
|
z/OS Cryptographic Services ICSF Application Programmer's Guide
Copyright IBM Corporation 1990, 2014