Create Algorithm Context (QC3CRTAX, Qc3CreateAlgorithmContext) API

The Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API creates a temporary area for holding the algorithm parameters and the state of the cryptographic operation. The API returns a token which can be used on subsequent cryptographic APIs. The algorithm context token can be used to extend a cryptographic operation over multiple calls. The algorithm context can not be shared between jobs. It should be destroyed using the Destroy Algorithm Context (OPM, QC3DESAX; ILE, Qc3DestroyAlgorithmContext) API. If not explicitly destroyed, the algorithm context will be destroyed at job end.

Authorities and Locks

None.

Required Parameter Group

Algorithm description

INPUT; CHAR(*)

The algorithm and associated parameters.
The format of the algorithm description is specified in the algorithm description format name parameter.

Algorithm description format name

INPUT; CHAR(8)

The format of the algorithm description.
The possible format names follow.

ALGD0200

Block cipher algorithm (DES, Triple DES, AES, and RC2).

ALGD0300

Stream cipher algorithm (RC4-compatible).

ALGD0400

Public key algorithm (RSA).

ALGD0500

Hash algorithm (MD5, SHA-1, SHA-256, SHA-384, SHA-512).

See Algorithm Description Formats for a description of these formats.

Algorithm context token

OUTPUT; CHAR(8)

The area to store the token for the created algorithm context.
Each token will contain an authentication value. If the token is used on a subsequent API but with an incorrect authentication value, the user will be subjected to a 10 second penalty wait. For each authentication error in that job, the penalty wait will increase 10 seconds up to a maximum of 10 minutes.

Error code

I/O; CHAR(*)

The structure in which to return error information.
For the format of the structure, see Error code parameter.

Algorithm Description Formats

ALGD0200 Format

ALGD0300 Format

ALGD0400 Format

ALGD0500 Format

Algorithm Description Formats Field Descriptions

Block cipher algorithm

Following are the valid block cipher algorithms:

20	DES Documented in FIPS 46-3. DES is no longer considered secure enough for today's fast computers. It should be used for compatibility purposes only.
21	Triple DES Documented in FIPS 46-3.
22	AES Documented in FIPS 197.
23	RC2 Documented in RFC 2268.

Block length

The algorithm block length. For DES, Triple DES, and RC2, this field must specify 8. The valid block length values for AES are 16, 24, and 32.

Effective key size

For RC2, the number of key bits to use in the cipher operation. Valid values are from 1 to 1024. If RC2 is not specifed for the block cipher algorithm, this field must be set to 0.

Hash algorithm

Following are the valid hash algorithms:

1	MD5 Documented in RFC 1321.
2	SHA-1 Documented in FIPS 180-2.
3	SHA-256 Documented in FIPS 180-2.
4	SHA-384 Documented in FIPS 180-2.
5	SHA-512 Documented in FIPS 180-2.

Initialization vector or counter

An initialization vector (IV) is used for modes CBC, OFB, CFB, and CUSP. A counter is used for CTR mode. Refer to the mode standards for an explanation of how each mode uses the IV or counter. This field is not used for ECB mode, and must be set to NULL (binary 0s).
For DES, Triple DES, and RC2, the first 8 bytes are used as the IV/counter. For AES, the length of IV/counter is that specified by block length.
The IV need not be secret, but it should be unique for each message. If not unique, it may compromise security. The IV can be any value. To obtain a good random IV value, use the Generate Pseudorandom Numbers (OPM, QC3GENPRN; ILE, Qc3GenPRNs) API.

MAC length

The message authentication code length. This field is used only by the Calculate MAC (OPM, QC3CALMA; ILE, Qc3CalMAC) API. MAC length can not exceed the block length value. When calculating a MAC, the leftmost MAC length bytes from the last block of encrypted data are returned as the MAC.

Mode

The mode of operation. Information on modes can be found in FIPS PUB 81 and ANSI X9.52. Following are the valid modes:

0	ECB.
1	CBC.
2	OFB. Not valid with AES or RC2.
3	CFB 1-bit. Not valid with AES or RC2.
4	CFB 8-bit. Not valid with AES or RC2.
5	CFB 64-bit. Not valid with AES or RC2.
6	CUSP. CUSP is a special type of CBC mode documented in the z/OS® ICSF Application Programmer's Guide (SA22-7522). It is used for handling data not a multiple of the block length. The length of encrypted data in CUSP mode will always equal the length of clear text data.
7	CTR. Only valid with AES.

Pad character

The pad character for pad option 1. Using hex 00 as the pad character is equivalent to ANSI X9.23 padding.

Pad option

Padding, if requested, is performed at the end of the operation. Be sure the area provided for the encrypted data is large enough to include the pad characters. The data will be padded up to the next block length byte multiple. For example, when using DES and and total data to encrypt is 20, the text is padded to 24. The last byte is filled with a 1-byte binary counter containing the number of pad characters used. The preceeding pad characters are filled as specified by this field. Padding is not performed for modes CFB 1-bit, CFB 8-bit, and CUSP. In these cases, the pad option must be set to 0. Following are the valid pad options.

0	No padding is performed.
1	Use the character specified in the pad character field for padding.
2	The pad counter is used as the pad character. This is equivalent to PKCS #5 padding.

PKA block format

The public key algorithm block format. Following are the valid values:

0	PKCS #1 block type 00
1	PKCS #1 block type 01
2	PKCS #1 block type 02 This format is allowed on encryption and decryption operations only.
3	ISO 9796-1 This format is allowed on calculate signature and verify signature operations only. Because of security weaknesses, this format should be used for compatibility purposes only.
4	Zero pad This format is allowed on encryption and decryption operations only. The clear data is placed in the low-order bit positions of a string of the same bit-length as the key modulus. All leading bits are set to zero.
5	ANSI X9.31 This format is allowed on calculate signature and verify signature operations only.
6	OAEP

Public key algorithm

Following are the valid public key algorithms:

50	RSA Documented in Public-Key Cryptography Standard (PKCS) #1.

Reserved

Must be null (binary 0s).

Signing hash algorithm

The hash algorithm for a sign or verify operation. Following are the valid values for the signing hash algorithm:

0	This algorithm context will not be used in a sign or verify operation.
1	MD5 Documented in RFC 1321.
2	SHA-1 Documented in FIPS 180-2.

Stream cipher algorithm

Following are the valid stream cipher algorithms:

30	RC4-compatible

Standards Resources

• FIPS publications are available from NIST Computer Security Resource Center at http://csrc.nist.gov/.
• RFC publications are available from IETF at http://www.ietf.org/.
• PKCS publications are available from RSA Security Inc. Web pages.
• ANSI and ISO publications are available from the ANSI eStandards store at http://webstore.ansi.org/ansidocstore/.
• ISO publications are available from the ISO Store at http://www.iso.org/iso/en/prods-services/ISOstore/store.html.

Error Messages

[ Back to top | Cryptographic Services APIs | APIs by category ]