- 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: Input/Output | Type: Integer |
The length of the data that is passed to the installation
exit. The length can be from X'00000000' to X'7FFFFFFF' (2
gigabytes). The data is identified in the exit_data parameter.
- exit_data
-
Direction: Input/Output | Type: String |
The data that is passed to the installation exit.
- rule_array_count
-
Direction: Input | Type: Integer |
The number of keywords you are supplying in the rule_array parameter.
The rule_array_count parameter must be 0, 1, 2, 3,
or 4. If the rule_array_count is 0, the default keywords
are used.
- rule_array
-
Direction: Input | Type: String |
Zero, one or two keywords that supply control information
to the callable service. The keywords must be 8 bytes of contiguous
storage with the keyword left-justified in its 8-byte
location and padded on the right with blanks. The keywords are
shown in Table 71.
The first keyword is the algorithm.
If no algorithm is specified, the system default algorithm is used.
If no algorithm is specified on a CDMF only system and either a double-
or triple-length DATA key is specified, the token is marked DES. The
algorithm keyword applies only when the desired output token is of
key form OP and key type IMPORTER, EXPORTER, or DATA. For key form
IM or any other key type, specifying DES or CDMF causes an error.
The
second keyword is optional and specifies that the output key token
be marked as an NOCV-KEK.
The third keyword is optional, and
specifies whether the original key wrapping method or the enhanced
key wrapping method (which is compliant with the ANSI X9.24 standard)
should be used.
The fourth keyword enables an application to
specify that the imported_key_identifier output token can
not be rewrapped using the original wrapping method after it has been
wrapped using the enhanced method.
Table 71. Keywords for Multiple Secure Key Import Rule Array Control InformationKeyword | Meaning |
---|
Algorithm (optional) |
CDMF | The output key identifier is to be
a CDMF token. For a DATA key of length 16 or 24, you may not specify
CDMF.
CDMF is only supported on CCF systems. |
AES | The output key identifier is to be
a AES token. |
DES | The output key identifier is to be
a DES token. This is the default. |
NOCV Choice (optional) |
NOCV-KEK | The output token is to be marked
as an NOCV-KEK. This keyword only applies if key form is OP and key
type is IMPORTER, EXPORTER or IMP-PKA. For key form IM or any other
key type, specifying NOCV-KEK causes an error. |
Key Wrapping
Method (optional) |
USECONFG | Specifies that the system default configuration
should be used to determine the wrapping method. This is the default
keyword.
The system default key wrapping method can be specified
using the DEFAULTWRAP parameter in the installation options data set.
See the z/OS Cryptographic Services ICSF System Programmer’s Guide. |
WRAP-ENH | Use enhanced key wrapping method, which is compliant
with the ANSI X9.24 standard. |
WRAP-ECB | Use original key wrapping method, which uses
ECB wrapping for DES key tokens and CBC wrapping for AES key tokens. |
Translation
Control (optional) |
ENH-ONLY | Restrict rewrapping of the imported_key_identifier token.
Once the token has been wrapped with the enhanced method, it cannot
be rewrapped using the original method. |
- clear_key_length
-
Direction: Input | Type: Integer |
The clear_key_length specifies
the length of the clear key value to import in bytes. For AES
keys, this length must be 16-, 24-, or 32-bytes. For DES keys, this
length must be 8-, 16- or 24-bytes.
- clear_key
-
Direction: Input | Type: String |
The clear_key specifies
the AES or DES clear key value to import.
- key_type
-
Direction: Input | Type: 8 Character String |
The type of key you want to encipher under the master
key or an importer key. Specify an 8-byte field that must contain
a keyword from this list or the keyword TOKEN. For types with fewer
than 8 characters, the type should be padded on the right with blanks.
If the key type is TOKEN, ICSF determines the key type from the
control vector (CV) field in the internal key token provided in the imported_key_identifier parameter. When
key_type is TOKEN, ICSF does not check for the length of the key but
uses the clear_key_length parameter to determine the
length of the key.
Key type values for the
Multiple Secure Key Import callable service are: CIPHER, CVARDEC,
CVARENC, CVARPINE, CVARXCVL, CVARXCVR, DATA, DATAM, DATAMV, DATAXLAT,
DECIPHER, ENCIPHER, EXPORTER, IKEYXLAT, IMPORTER, IMP-PKA, IPINENC,
MAC, MACVER, OKEYXLAT, OPINENC, PINGEN and PINVER. For information
on the meaning of the key types, see Table 3.
- key_form
-
Direction: Input | Type: 4 Character String |
The key form you want to generate. Enter a 4-byte keyword
specifying whether the key should be enciphered under the master key
(OP) or the importer key-encrypting key (IM). The keyword must be
left-justified and padded with blanks. Valid DES keyword
values are OP for encryption under the master key or IM for encryption
under the importer key-encrypting key. If you specify IM, you must
specify an importer key-encrypting key in the key_encrypting_key_identifier parameter.
For a key_type of IMP-PKA, this service supports only
the OP key_form.
The only valid AES keyword value
is OP.
- key_encrypting_key_identifier
-
Direction: Input/Output | Type: String |
A 64-byte string internal key token or key label of a DES importer
key-encrypting key. This parameter is ignored for AES secure keys.
- imported_key_identifier_length
-
Direction: Input/Output | Type: Integer |
The byte length of the imported_key_identifier parameter. This
must be at least 64.
- imported_key_identifier
-
Direction: Input/Output | Type: String |
A
64-byte string that is to receive the output key token. If OP is specified
in the key_form parameter, the service returns an internal
key token. If IM is specified in the key_form parameter,
the service returns an external key token. On input, this parameter
is ignored except when the key_type is TOKEN. If
you specify a key_type of TOKEN, then this field contains
a valid token of the key type you want to encipher. See key_type for
a list of valid key types. Appendix B. Key Token Formats describes the
key tokens.
Note that for a DATA key of length 16 or 24, no
reference will be made to the data encryption algorithm bits or to
the system's default algorithm; the token will be marked DES.
ICSF
supports two methods of wrapping the key value in a symmetric key
token: the original ECB wrapping and an enhanced CBC wrapping method
which is ANSI X9.24 compliant. The output imported_key_identifier will
use the default method unless a rule array keyword overriding the
default is specified.