Create Algorithm Context (QC3CRTAX, Qc3CreateAlgorithmContext) API
Required Parameter Group:
| 1 | Algorithm description | Input | Char(*) |
| 2 | Algorithm description format name | Input | Char(8) |
| 3 | Algorithm context token | Output | Char(8) |
| 4 | Error code | I/O | Char(*) |
Service Program Name: QC3CTX
Default Public Authority: *USE
Threadsafe: Yes
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-224, SHA-256, SHA-384, SHA-512).
- ALGD0600
- Elliptic curve public key algorithm (ECDSA).
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
For detailed descriptions of the fields in the tables, see Algorithm Description Formats Field Descriptions.ALGD0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Block cipher algorithm |
| 4 | 4 | BINARY(4) | Block length |
| 8 | 8 | CHAR(1) | Mode |
| 9 | 9 | CHAR(1) | Pad option |
| 10 | A | CHAR(1) | Pad character |
| 11 | B | CHAR(1) | Reserved |
| 12 | C | BINARY(4) | MAC length |
| 16 | 10 | BINARY(4) | Effective key size |
| 20 | 14 | CHAR(32) | Initialization vector or counter |
ALGD0300 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Stream cipher algorithm |
ALGD0400 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Public key algorithm |
| 4 | 4 | CHAR(1) | PKA block format |
| 5 | 5 | CHAR(3) | Reserved |
| 8 | 8 | BINARY(4) | Signing hash algorithm |
ALGD0500 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Hash algorithm |
ALGD0600 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Elliptic curve public key algorithm |
| 4 | 4 | CHAR(4) | Reserved |
| 8 | 8 | BINARY(4) | Signing hash algorithm |
| 12 | C | BINARY(4) | Domain parameters length |
| 16 | 10 | PTR(SPP) | Domain parameters |
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-3.3 SHA-256
Documented in FIPS 180-3.4 SHA-384
Documented in FIPS 180-3.5 SHA-512
Documented in FIPS 180-3.7 SHA-224
Documented in FIPS 180-3.
- 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. Also, this format is not valid with SHA-2 based signatures.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. However, this format is not valid with SHA-2 based signatures.6 OAEP
- Public key algorithm
- Following are the valid public key algorithms:
50 RSA
Documented in Public-Key Cryptography Standard (PKCS) #1.
- Elliptic curve public key algorithm
- Following are the valid elliptic curve public key algorithms:
54 ECDSA
Documented in Digital Signature Standard (DSS), FIPS PUB 186-3.
- 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.3 SHA-256
Documented in FIPS 180-2.4 SHA-384
Documented in FIPS 180-2.5 SHA-512
Documented in FIPS 180-2.7 SHA-224
Documented in FIPS 180-2.
- Stream cipher algorithm
- Following are the valid stream cipher algorithms:
30 RC4-compatible - Domain Parameters Length
- The length of elliptic curve ASN.1, BER encoded domain parameters. If no domain parameters are being supplied independantly of the keys, this field should be zero and domain parameters pointer should be NULL.
- Domain Parameters
- The elliptic curve ASN.1 BER encoded domain parameters to be used in the event that the ECC key does not already contain domain parameters. If domain parameters are already associated with the key when performing an ECC operation such as ECDSA (See Calculate Signature (OPM, QC3CALSG; ILE, Qc3CalculateSignature) API and Verify Signature (OPM, QC3VFYSG; ILE, Qc3VerifySignature) API) these supplied domain parameters (which will be associated with the Algorithm Context token), will be ignored.
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/prods-services/ISOstore/store.html.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9D83 E | Elliptic curve public key algorithm not valid. |
| CPF9D84 E | Domain parameters not valid. |
| CPF9D85 E | Domain parameters length not valid. |
| CPF9DD2 E | Algorithm description format name not valid. |
| CPF9DD9 E | Effective key size not valid. |
| CPF9DDA E | Unexpected return code &1. |
| CPF9DDE E | Cipher algorithm not valid. |
| CPF9DDF E | Block length not valid. |
| CPF9DE0 E | Hash algorithm not valid. |
| CPF9DE1 E | Initialization vector not valid. |
| CPF9DE2 E | MAC (message authentication code) length not valid. |
| CPF9DE3 E | Mode not valid. |
| CPF9DE4 E | Pad option not valid. |
| CPF9DE5 E | PKA (public key algorithm) block format not valid. |
| CPF9DE6 E | Public key algorithm not valid. |
| CPF9DEE E | Reserved field not null. |
API introduced: V5R3
[ Back to top | Cryptographic Services APIs | APIs by category ]