Parameters

z/OS Cryptographic Services ICSF Application Programmer's Guide

Parameters

z/OS Cryptographic Services ICSF Application Programmer's Guide
SA22-7522-16

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 supplied in the rule_array parameter. Value must be 1, 2 or 3.

rule_array

Direction: Input

Type: String

One or two keywords that provide control information to the callable service. Table 232 lists the keywords. The keywords must be in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on the right with blanks.

Table 232. Keywords for PKA Key Token Build Control Information
Keyword	Meaning
Key Type (required)
DSS-PRIV	This keyword indicates building a key token containing both public and private DSS key information. The parameter `key_value_structure` identifies the input key values, if supplied.
DSS-PUBL	This keyword indicates building a key token containing public DSS key information. The parameter `key_value_structure` identifies the input key values, if supplied.
RSA-CRT	This keyword indicates building a token containing an RSA private key in the optimized Chinese Remainder Theorem (CRT) form. The parameter `key_value_structure` identifies the input key values, if supplied.
RSA-PRIV	This keyword indicates building a token containing both public and private RSA key information. The parameter `key_value_structure` identifies the input key values, if supplied.
RSA-PUBL	This keyword indicates building a token containing public RSA key information. The parameter `key_value_structure` identifies the input values, if supplied.
RSAMEVAR	This keyword is for creating a key token for an RSA public and private key pair in modulus-exponent form whose modulus is 512 bits or greater.
ECC-PAIR	This keyword indicates building a token containing both public and private ECC key information. The parameter `key_value_structure` identifies the input key values, if supplied.
ECC-PUBL	This keyword indicates building a token containing public ECC key information. The parameter `key_value_structure` identifies the input values, if supplied.
Key Usage Control (optional)
KEY-MGMT	Indicates that an RSA or ECC private key can be used in both the symmetric key import and the digital signature generate callable services.
KM-ONLY	Indicates that an RSA or ECC private key can be used only in symmetric key distribution.
SIG-ONLY	Indicates that an RSA or ECC private key cannot be used in symmetric key distribution. This is the default. Note that for DSS-PRIV the keyword is allowed but extraneous; DSS keys are defined only for digital signature.
Translate Control (optional)
XLATE-OK	Specifies that the private key material can be translated. XLATE-OK is only allowed with key types RSA-PRIV, RSAMEVAR, RSA-CRT, and ECC-PAIR and is valid with all key usage rules.
NO-XLATE	Indicates key translation is not allowed. This is the default. NO-XLATE is only allowed with key types RSA-PRIV, RSAMEVAR, RSA-CRT, and ECC-PAIR and is valid with all key usage rules.

key_value_structure_length

Direction: Input

Type: Integer

This is a segment of contiguous storage containing a variable number of input clear key values. The length depends on the key type parameter in the rule array and on the actual values input. The length is in bytes.

Table 233. Key Value Structure Length Maximum Values for Key Types
Key Type	Key Value Structure Maximum Value
DSS-PRIV	436
DSS-PUBL	416
RSA-CRT	3500
RSAMEVAR	3500
RSA-PRIV	648
RSA-PUBL	520
ECC-PAIR	207
ECC-PUBL	139

key_value_structure

Direction: Input

Type: String

This is a segment of contiguous storage containing a variable number of input clear key values and the lengths of these values in bits or bytes, as specified. The structure elements are ordered, of variable length, and the input key values must be right-justified within their respective structure elements and padded on the left with binary zeros. If the leading bits of the modulus are zero's, don't count them in the length. Table 234 defines the structure and contents as a function of key type.

Table 234. Key Value Structure Elements for PKA Key Token Build
Offset	Length (bytes)	Description
Key Value Structure (Optimized RSA, Chinese Remainder Theorem form, RSA-CRT)
000	002	Modulus length in bits (512 to 4096). This is required.
002	002	Modulus field length in bytes, "nnn." This value can be zero if the key token is used as a `skeleton_key_token` in the PKA key generate callable service. This value must not exceed 512.
004	002	Public exponent field length in bytes, "eee." This value can be zero if the key token is used as a `skeleton_key_token` in the PKA key generate callable service.
006	002	Reserved, binary zero.
008	002	Length of the prime number, p, in bytes, "ppp." This value can be zero if the key token is used as a `skeleton_key_token` in the PKA key generate callable service. Maximum size of p + q is 512 bytes.
010	002	Length of the prime number, q, in bytes, "qqq." This value can be zero if the key token is used as a `skeleton_key_token` in the PKA key generate callable service. Maximum size of p + q is 512 bytes.
012	002	Length of d_p, in bytes, "rrr." This value can be zero if the key token is used as a `skeleton_key_token` in the PKA key generate callable service. Maximum size of d_p + d_q is 512 bytes.
014	002	Length of d_q, in bytes, "sss." This value can be zero if the key token is used as a `skeleton_key_token` in the PKA key generate callable service. Maximum size of d_p + d_q is 512 bytes.
016	002	Length of U, in bytes, "uuu." This value can be zero if the key token is used as a `skeleton_key_token` in the PKA key generate callable service. Maximum size of U is 512 bytes.
018	nnn	Modulus, n.
018 + nnn	eee	Public exponent, e. This is an integer such that 1<e<n. e must be odd. When you are building a `skeleton_key_token` to control the generation of an RSA key pair, the public key exponent can be one of these values: 3, 65537 (2¹⁶ + 1), or 0 to indicate that a full random exponent should be generated. The exponent field can be a null-length field if the exponent value is 0.
018 + nnn + eee	ppp	Prime number, p.
018 + nnn + eee + ppp	qqq	Prime number, q.
018 + nnn + eee + ppp + qqq	rrr	d_p = d mod(p-1).
018 + nnn + eee + ppp + qqq + rrr	sss	d_q = d mod(q-1).
018 + nnn + eee + ppp + qqq + rrr + sss	uuu	U = q^–1mod(p).
Key Value Structure (RSA Private, RSA Private variable or RSA Public)
000	002	Modulus length in bits. This is required. When building a skeleton token, the modulus length in bits must be greater than or equal to 512 bits.
002	002	Modulus field length in bytes, "XXX". This value can be zero if you are using the key token as a skeleton in the PKA key generate verb. This value must not exceed 512 when either the RSA-PUBL or RSAMEVAR keyword is used, and must not exceed 128 when the RSA-PRIV keyword is used. This service can build a key token for a public RSA key with a 4096-bit modulus length, or it can build a key token for a 1024-bit modulus length private key.
004	002	Public exponent field length in bytes, "YYY". This value must not exceed 512 when either the RSA-PUBL or RSAMEVAR keyword is used, and must not exceed 128 when the RSA-PRIV keyword is used. This value can be zero if you are using the key token as a skeleton token in the PKA key generate verb. In this case, a random exponent is generated. To obtain a fixed, predetermined public key exponent, you can supply this field and the public exponent as input to the PKA key generate verb.
006	002	Private exponent field length in bytes, "ZZZ". This field can be zero, indicating that private key information is not provided. This value must not exceed 128 bytes. This value can be zero if you are using the key token as a skeleton token in the PKA key generate verb.
008	XXX	Modulus, n. This is an integer such that 1 < n <2**²⁰⁴⁸.The n is the product of p and q for primes p and q.
008 + XXX	YYY	RSA public exponent, e. This is an integer such that 1<e<n. e must be odd. When you are building a `skeleton_key_token` to control the generation of an RSA key pair, the public key exponent can be one of these values: 3, 65537 (2¹⁶ + 1), or 0 to indicate that a full random exponent should be generated. The exponent field can be a null-length field if the exponent value is 0.
008 + XXX + YYY	ZZZ	RSA secret exponent d. This is an integer such that 1<d<n. The value of d is
Key Value Structure (DSS Private or DSS Public)
000	002	Modulus length in bits. This is required.
002	002	Prime modulus field length in bytes, "XXX". You can supply this as a network quantity to the ICSF PKA key generate callable service, which uses the quantity to generate DSS keys. The maximum allowed value is 128.
004	002	Prime divisor field length in bytes, "YYY". You can supply this as a network quantity to the ICSF PKA key generate callable service, which uses the quantity to generate DSS keys. The allowed values are 0 or 20 bytes.
006	002	Public generator field length in bytes, "ZZZ". You can supply this in a skeleton token as a network quantity to the ICSF PKA key generate callable service, which uses the quantity to generate DSS keys. The maximum allowed value is 128 bytes and is exactly the same length as the prime modulus.
008	002	Public key field length in bytes, "AAA". This field can be zero, indicating that the ICSF PKA key generate callable service generates a value at random from supplied or generated network quantities. The maximum allowed value is 128 bytes and is exactly the same length as the prime modulus.
010	002	Secret key field length in bytes, "BBB". This field can be zero, indicating that the ICSF PKA key generate callable service generates a value at random from supplied or generated network quantities. The allowed values are 0 or 20 bytes.
012	XXX	DSS prime modulus p. This is an integer such that ^L-1<p<2^L. The p must be prime. You can supply this value in a skeleton token as a network quantity; it is used in the algorithm that generates DSS keys.
012 + XXX	YYY	DSS prime divisor q. This is an integer that is a prime divisor of p-1 and ¹⁵⁹<q<2¹⁶⁰. You can supply this value in a skeleton token as a network quantity; it is used in the algorithm that generates DSS keys.
012 + XXX+ YYY	ZZZ	DSS public generator g. This is an integer such that 1<g<p. You can supply this value in a skeleton token as a network quantity; it is used in the algorithm that generates DSS keys.
012 + XXX+ YYY+ ZZZ	AAA	DSS public key y. This is an integer such that
012 + XXX+ YYY+ ZZZ+ AAA	BBB	DSS secret private key x. This is an integer such that 0<x<q. The x is random. You need not supply this value if you specify DSS-PUBL in the rule array.
Key Value Structure (ECC_PAIR)
000	001	Curve type x'00' Prime Curve x'01' Brainpool Curve
001	001	Reserved x'00'
002	002	Length of p in bits 0x'00C0' Prime P-192 0x'00E0' Prime P-224 0x'0100' Prime P-256 0x'0180' Prime P-384 0x'0209' Prime P-521 0x'00A0' Brain Pool P-160 0x'00C0' Brain Pool P-192 0x'00E0' Brain Pool P-224 0x'0100' Brain Pool P-256 0x'0140' Brain Pool P-320 0x'0180' Brain Pool P-384 0x'0200' Brain Pool P512.
004	002	ddd, This field is the length of the private key d value in bytes, This value can be zero if the key token is used as a skeleton key token in the PKA Key Generate callable service. The maximum value could be up to 66 bytes.
006	002	xxx, This field is the length of the public key Q value in bytes. This value can be zero if the key token is used as a skeleton key token in the PKA Key Generate callable service. The maximum value could be up to 133 bytes which includes one byte to indicate if the value is compressed.
008	ddd	Private key d
008 + ddd	xxx	Public Key value Q
Key value Structure (ECC_PUBL)
000	001	Curve type: 0x'00' Prime Curve 0x'01' Brain Pool Curve
000	001	Reserved x'00'
002	002	Length of p in bits 0x'00C0' Prime P-192 0x'00E0' Prime P-224 0x'0100' Prime P-256 0x'0180' Prime P-384 0x'0209' Prime P-521 0x'00A0' Brain Pool P-160 0x'00C0' Brain Pool P-192 0x'00E0' Brain Pool P-224 0x'0100' Brain Pool P-256 0x'0140' Brain Pool P-320 0x'0180' Brain Pool P-384 0x'0200' Brain Pool P512.
004	002	xxx, This field is the length of the public key Q value in bytes. This value can be zero if the key token is used as a skeleton key token in the PKA Key Generate callable service. The maximum value could be up to 133 bytes which includes a one byte value indicating compressed or uncompressed key value.
006	xxx	Public key value Q

Notes:

All length fields are in binary.
All binary fields (exponent, lengths, modulus, and so on) are stored with the high-order byte field first. This integer number is right-justified within the key structure element field.
You must supply all values in the structure to create a token containing an RSA or DSS private key for input to the PKA key import service.

private_key_name_length

Direction: Input

Type: Integer

The length can be 0 or 64.

private_key_name

Direction: Input

Type: EBCDIC character

This field contains the name of a private key. The name must conform to ICSF label syntax rules. That is, allowed characters are alphanumeric, national (@,#,$) or period (.). The first character must be alphabetic or national. The name is folded to upper case and converted to ASCII characters. ASCII is the permanent form of the name because the name should be independent of the platform. The name is then cryptographically coupled with clear private key data prior to its encryption of the private key. Because of this coupling, the name can never change when the key token is already imported. The parameter is not valid with key types DSS-PUBL or RSA-PUBL.

user_definable_associated_data_length

Direction: Input

Type: Integer

The length of the user_definable_associated_data parameter.

Valid for Rule Array Key Type of ECC-PAIR with a maximum value of 100 and must be set to 0 for all other Rule Array Key Types.

user_definable_associated_data

Direction: Input

Type: String

The user_definable_associated_data parameter is a pointer to a string variable containing the associated data that will be placed following the IBM associated data in the token. The associated data is data whose integrity but not confidentiality is protected by a key wrap mechanism. It can be used to bind usage control information.

Valid for Rule Array Key Type of ECC-PAIR and is ignored for all others.

reserved_2_length

Direction: Input

Type: Integer

Length in bytes of a reserved parameter. You must set this variable to 0.

reserved_2

Direction: Input

Type: String

The reserved_2 parameter identifies a string that is reserved. The service ignores it.

reserved_3_length

Direction: Input

Type: Integer.

Length in bytes of a reserved parameter. You must set this variable to 0.

reserved_3

Direction: Input

Type: String

The reserved_3 parameter identifies a string that is reserved. The service ignores it.

reserved_4_length

Direction: Input

Type: Integer.

Length in bytes of a reserved parameter. You must set this variable to 0.

reserved_4

Direction: Input

Type: String

The reserved_4 parameter identifies a string that is reserved. The service ignores it.

reserved_5_length

Direction: Input

Type: Integer.

Length in bytes of a reserved parameter. You must set this variable to 0.

reserved_5

Direction: Input

Type: String

The reserved_5 parameter identifies a string that is reserved. The service ignores it.

key_token_length

Direction: Input/Output

Type: Integer

Length of the returned key token. The service checks the field to ensure it is at least equal to the size of the token to return. On return from this service, this field is updated with the exact length of the key_token created. On input, a size of 3500 bytes is sufficient to contain the largest key_token created.

key_token

Direction: Output

Type: String

The returned key token containing an unenciphered private or public key. The private key is in an external form that can be exchanged with different Common Cryptographic Architecture (CCA) PKA systems. You can use the public key token directly in appropriate ICSF signature verification or key management services.

Notices | Terms of use | Support | Contact z/OS | zFavorites