- 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.
The value may be 2, 3 or 4.
- rule_array
-
Direction: Input | Type: String |
This keyword provides control information to the callable
service. The keywords must be eight bytes of contiguous storage with
the keyword left-justified in its 8-byte location and padded on the
right with blanks.
Table 135. Symmetric Algorithm Encipher Rule Array KeywordsKeyword | Meaning |
---|
Algorithm (one keyword, required) |
AES | Specifies that the Advanced Encryption
Standard (AES) algorithm will be used. The block size is 16-bytes,
and the key length may be 16-, 24-, or 32-bytes (128-, 192-, 256-bits). |
Processing Rule (optional - zero or one
keyword) |
CBC | Performs encryption in cipher block
chaining (CBC) mode. The text length must be a multiple of the AES
block size (16-bytes). This is the default value. |
ECB | Performs encryption in electronic
code book (ECB) mode. The text length must be a multiple of the AES
block size (16-bytes). |
PKCS-PAD | Performs encryption in cipher block
chaining (CBC) mode, but the data is padded using PKCS padding rules.
The length of the clear text data does not have to be a multiple of
the cipher block length. The cipher text will be longer than the clear
text by at least one byte, and up to 16-bytes. The PKCS padding method
is described in PKCS Padding Method. |
Key Rule (required) |
KEYIDENT | This indicates that the value in
the key_identifier parameter is either an
internal key token or the label of a key token in the CKDS. The key
must be a secure AES key, that is, enciphered under the current master
key. |
ICV Selection (optional - zero or one keyword) |
INITIAL | This specifies that this is the first
request of a sequence of chained requests, and indicates that the
initialization vector should be taken from the initialization_vector parameter.
This is the default value. |
CONTINUE | This specifies that this request
is part of a sequence of chained requests, and is not the first request
in that sequence. The initialization vector will be taken from the
work area identified in the chain_data parameter. This keyword
is only valid for processing rule CBC. |
- key_identifier_length
-
Direction: Input | Type: Integer |
The length of the key_identifier parameter.
The length must be 64 bytes for an AES DATA Internal Key Token (version
X'04') or a CKDS label, or between the actual length of
the token and 725 for an AES CIPHER Internal Key Token (version X'05').
- key_identifier
-
Direction: Input | Type: String |
This specifies an internal secure AES token or the labelname
of a secure AES token in the CKDS. Normal CKDS labelname syntax is
required.
The AES key identifier must be an encrypted key contained
in an internal key token, where the key is enciphered under the AES
master key. The key can be 128-, 192-, or 256-bits in length.
- key_parms_length
-
Direction: Input | Type: Integer |
The length of the key_parms parameter in
bytes. It must be set to 0.
- key_parms
-
Direction: Ignored | Type: String |
This parameter is ignored. It is reserved for future
use.
- block_size
-
Direction: Input | Type: Integer |
The block size for the cryptographic algorithm. AES requires
the block size to be 16.
- initialization_vector_length
-
Direction: Input | Type: Integer |
The length of the initialization_vector parameter
in bytes. This parameter is ignored if the process rule is ECB.
- initialization_vector
-
Direction: Input | Type: String |
This parameter contains the initialization vector (IV)
for CBC mode encryption, including the CBC mode invoked using the
PKCS-PAD keyword. This parameter is ignored if the process rule
is ECB. For AES CBC mode encryption, the initialization vector
length must be 16 bytes, the length of an AES block. The same IV must
be used when decrypting the data.
- chain_data_length
-
Direction: Input/Output | Type: Integer |
The length in bytes of the chain_data parameter.
On input it contains the length of the buffer provided with parameter chain_data.
On output, it is updated with the length of the data returned in
the chain_data parameter.
- chain_data
-
Direction: Input/Output | Type: String |
A buffer that is used as a work area for sequences of
chained symmetric algorithm encipher requests. When the keyword INITIAL
is used, this is an output parameter and receives data that is needed
when enciphering the next part of the input data. When the keyword
CONTINUE is used, this is an input/output parameter; the value received
as output from the previous call in the sequence is provided as input
to this call, and in turn this call will return new chain_data that
will be used as input on the next call. When CONTINUE is used, both
the data (chain_data parameter) and the length (chain_data_length parameter)
must be the same values that were received in these parameters as
output on the preceding call to the service in the chained sequence.
The exact content and layout of chain_data is not
described. For AES CBC encryption, the field must be at least 32-bytes
in length. For AES ECB encryption the field is not used and any length
is acceptable including zero.
- clear_text_length
-
Direction: Input | Type: Integer |
The length of the clear text data in the clear_text parameter.
Unless process rule PKCS-PAD is used, the length must be a multiple
of the algorithm block size. The length must be 1 or greater.
- clear_text
-
Direction: Input | Type: String |
The text to be enciphered.
- cipher_text_length
-
Direction: Input/Output | Type: Integer |
On input, this parameter specifies the size of the storage
pointed to by the cipher_text parameter. On output, this
parameter has the actual length of the text stored in the buffer addressed
by the cipher_text parameter.
If process rule PKCS-PAD
is used, the cipher text length will exceed the clear text length
by at least one byte, and up to 16-bytes. For other process rules,
the cipher text length will be equal to the clear text length.
- cipher_text
-
Direction: Output | Type: String |
The enciphered text the service returns.
- optional_data_length
-
Direction: Input | Type: Integer |
The length of the optional_data parameter.
This parameter is reserved for future use. It must be set to 0.
- optional_data
-
Direction: Ignored | Type: String |
The optional data used in processing the request. This
parameter is ignored.
- cipher_text_id
-
Direction: Input | Type: Integer |
For CSNBSAE1 and CSNESAE1 only, the ALET of the dataspace
in which the cipher_text parameter resides.
- clear_text_id
-
Direction: Input | Type: Integer |
For CSNBSAE1 and CSNESAE1 only, the ALET of the dataspace
in which the clear_text parameter resides.