Calculate MAC (QC3CALMA, Qc3CalculateMAC) API


  Required Parameter Group:

1 Input data Input Char(*)
2 Length of input data Input Binary(4)
3 Input data format name Input Char(8)
4 Algorithm description Input Char(*)
5 Algorithm description format name Input Char(8)
6 Key description Input Char(*)
7 Key description format name Input Char(8)
8 Cryptographic service provider Input Char(1)
9 Cryptographic device name Input Char(10)
10 MAC Output Char(*)
11 Error code I/O Char(*)

  Service Program Name: QC3MAC

  Default Public Authority: *USE

  Threadsafe: Yes

The Calculate MAC (OPM, QC3CALMA; ILE, Qc3CalculateMAC) API produces a message authentication code. Normally, a MAC is appended to the end of a message and later used to check the message's integrity. To produce a MAC, the input data is encrypted using CBC (cipher block chaining) mode. Some or all of the bytes from the last encrypted data block are returned as the MAC value.

Information on cryptographic standards can be found in Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.


Authorities and Locks

Required device description authority
*USE

Required file authority
*OBJOPR, *READ

Required Parameter Group

Input data
INPUT; CHAR(*)

The data to encrypt.
The format of the input data is specified in the input data format name parameter

Length of input data
INPUT; BINARY(4)

For input data format DATA0100, this is the length of the data to encrypt. If it is not a multiple of the block length, the data will be padded with hex 00s.

For input data format DATA0200, this is the number of entries in the array.

Input data format name
INPUT; CHAR(8)

The format of the input data parameter.
The possible format names follow.

DATA0100
The input data parameter contains the data to encrypt.

DATA0200
The input data parameter contains an array of pointers and lengths to the data to encrypt.
See Input Data Formats for a description of this format.

Algorithm description
INPUT; CHAR(*)

The algorithm and associated parameters for encrypting the data.
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.

ALGD0100
The token for an algorithm context. This format must be used when performing the MAC operation over multiple calls. After the last call (when the final operation flag is on), the context will reset to its initial state and can be used in another API.

ALGD0200
Parameters for a block cipher algorithm (DES, Triple DES, and AES).

See Algorithm Description Formats for a description of these formats.

Key description
INPUT; CHAR(*)

The key and associated parameters for encrypting the data.
The format of the key description is specified in the key description format name parameter.
If the MAC operation extends over multiple calls (see ALGD0100 description above), only the key description from the first call will be used. Therefore, on subsequent calls, you may set the pointer to this parameter to NULL.

Key description format name
INPUT; CHAR(8)

The format of the key description.
If the pointer to the key description parameter is NULL, this parameter will be ignored.
The possible format names follow.

KEYD0100
The token for a key context. This format identifies a key context. A key context is used to store a key value so it need not be recreated or retrieved every time it is used. To create a key context, use the Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext) API.

KEYD0200
Key parameters.

KEYD0400
Keystore label. This format identifies a key from keystore. For more information about cryptographic services keystore, see Cryptographic Services Keystore.

KEYD0500
PKCS5 passphrase. This format derives a key using RSA Data Security, Inc. Public-Key Cryptography Standard (PKCS) #5.

See Key Description Formats for a description of these formats.

Cryptographic service provider
INPUT; CHAR(1)

The cryptographic service provider (CSP) that will perform the decryption operation.

0 Any CSP.
The system will choose an appropriate CSP to perform the MAC operation.
1 Software CSP.
The system will perform the MAC operation using software. If the requested algorithm is not available in software, an error is returned.
2 Hardware CSP.
The system will perform the MAC operation using cryptographic hardware. If the requested algorithm is not available in hardware, an error is returned. A specific cryptographic device can be specified using the cryptographic device name parameter. If the cryptographic device is not specified, the system will choose an appropriate one.

Cryptographic device name
INPUT; CHAR(10)

The name of a cryptographic device description.
This parameter is valid when the cryptographic service provider parameter specifies 2 (hardware CSP). Otherwise, this parameter must be blanks or the pointer to this parameter set to NULL.

MAC
OUTPUT; CHAR(*)

The area to store the MAC. The length of MAC is specified in the MAC length field in the algorithm description.

Error code
I/O; CHAR(*)

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



Input Data Formats

For detailed descriptions of the table fields, see Input Data Formats Field Descriptions.

DATA0200 Format

Offset Type Field
Dec Hex
These fields repeat. PTR(SPP) Input data pointer
BINARY(4) Input data length
CHAR(12) Reserved


Input Data Formats Field Descriptions

Input data length
The length of data to encrypt. When final processing is performed and the total of all the input data lengths is not a multiple of the block length, the data will be padded with hex 00s.
Input data pointer
A space pointer to the data to encrypt.
Reserved
Must be null (binary 0s).

Algorithm Description Formats

For detailed descriptions of the table fields, see Algorithm Description Formats Field Descriptions.

ALGD0100 Format

Offset Type Field
Dec Hex
0 0 CHAR(8) Algorithm context token
8 8 CHAR(1) Final operation flag

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


Algorithm Description Formats Field Descriptions

Algorithm context token
A token for an algorithm context. The algorithm context is created by using the Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.

Block cipher algorithm
The encryption algorithm. Following are the valid block cipher algorithms.
20 DES
21 Triple DES
22 AES

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

Effective key size
Effective key size is not used on a MAC operation and must be set to null (binary 0's).

Final operation flag
The final processing indicator.
0 Continue.
The system will not perform final processing and the algorithm context will maintain the state of the operation. The algorithm context can be used on future calls to this API to continue the MAC operation. The pointer to the MAC parameter may be set to NULL because the MAC value will not be returned until the final operation flag is set on.
1 Final.
The system will perform final processing (e.g. padding). The MAC value will be returned and the algorithm context will reset to its initial state. The algorithm context can then be used to begin a new cryptographic operation (encrypt, decrypt, etc.). When performing a final operation, the pointer to the input data parameter may be set to NULL and the length of the input data parameter set to 0.

Initialization vector
The initialization vector (IV). For an explanation of its use, refer to the mode standards for CBC in FIPS PUB 81 and ANSI X9.52. For DES and Triple DES, the first 8 bytes are used as the IV. For AES, the length of IV used 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. It can not exceed the block length value. 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 for a MAC operation.
1 CBC

Pad character
This field is not used on a MAC operation and must be set to null (binary 0s).

Pad option
Following are the valid pad options for a MAC operation.
0 If the length of input data is not a multiple of 8, the input data will be padded with null (binary 0s).

Reserved
Must be null (binary 0s).

Key Description Formats

For detailed descriptions of the table fields, see Key Description Formats Field Descriptions.

KEYD0100 Format

Offset Type Field
Dec Hex
0 0 CHAR(8) Key context token

KEYD0200 Format

Offset Type Field
Dec Hex
0 0 BINARY(4) Key type
4 4 BINARY(4) Key string length
8 8 CHAR(1) Key format
9 9 CHAR(3) Reserved
12 C CHAR(*) Key string

KEYD0400 Format

Offset Type Field
Dec Hex
0 0 CHAR(20) Qualified keystore file name
20 14 CHAR(32) Record label
52 34 CHAR(4) Reserved

KEYD0500 Format

Offset Type Field
Dec Hex
0 0 BINARY(4) Key type
4 4 BINARY(4) Derived key length
8 8 BINARY(4) Iteration count
12 C BINARY(4) Salt length
16 10 CHAR(16) Salt
32 20 BINARY(4) Passphrase CCSID
36 24 BINARY(4) Passphrase length
40 28 CHAR(*) Passphrase


Key Description Formats Field Descriptions

Derived key length
The length of key requested. The minimum allowed length is 1.

File name
The name of a keystore file. Keystore files are created by using the Create Keystore (OPM, QC3CRTKS; ILE, Qc3CreateKeyStore) API.

Iteration count
Used to greatly increase the cost of an exhaustive search while modestly increasing the cost of key derivation. The minimum allowed value is 1. The standard recommends a minimum of 1000. The maximum allowed length is 100,000.

Key context token
A token for a key context. The key context is created by using the Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext) API.

Key format
The format of the key string field. Following are the valid values.
0 Binary string.
The key is specified as a binary value. To obtain a good random key value, use the Generate Symmetric Key (OPM, QC3GENSK; ILE, Qc3GenSymmetricKey) API or the Generate Pseudorandom Numbers (OPM, QC3GENRN; ILE, Qc3GenPRNs) API.

Key string
The key to use in the MAC operation.

Key string length
Length of the key string specified in the key string field.

Key type
The type of key. Following are the valid values.
20 DES
The key format must be 0. The key string must be 8 bytes in length. Only 7 bits of each byte are used as the actual key. The rightmost bit of each byte is used to set parity. Some cryptographic service providers require that a DES key have odd parity in every byte. Others ignore parity.
21 Triple DES
The key format must be 0. The key string can be 8, 16, or 24 bytes in length. When 24 bytes are specified, the first 8 bytes are used for key 1, the second 8 bytes for key 2, and the third 8 bytes for key 3. When 16 bytes are specified the first 8 bytes are used for keys 1 and 3, and the second 8 bytes for key 2. When just 8 bytes are specified, the first 8 bytes are used for all 3 keys. A MAC operation using Triple DES encrypts the entire input data (plus any padding) using DES and key 1. The last block is then decrypted using key 2 and encrypted again with key 3. Only 7 bits of each byte are used as the actual key. The rightmost bit of each byte is used to set parity. Some cryptographic service providers require that a Triple DES key have odd parity in every byte. Others ignore parity.
22 AES
The key format must be 0. The key string can be 16, 24, or 32 bytes in length.

Passphrase
A text string.

Passphrase CCSID
INPUT; BINARY(4)

The CCSID of the passphrase. The passphrase will be converted from the specified CCSID to Unicode before calling the PKCS5 algorithm.

0 The CCSID of the job is used to determine the CCSID of the data to be converted. If the job CCSID is 65535, the CCSID from the default CCSID (DFTCCSID) job attribute is used.
1-65533 A valid CCSID in this range is used. For a list of valid CCSIDs, see the i5/OS globalization topic collection.

Passphrase length
The length of passphrase. The length must be in the range of 1 to 256.

Qualified keystore file name
The keystore file where the key is stored. Keystore files are created by using the Create Keystore (OPM, QC3CRTKS; ILE, Qc3CreateKeyStore) API. The first 10 characters contain the file name. The second 10 characters contain the name of the library where the keystore file is located. You can use the following special values for the library name.
*CURLIB The job's current library is used to locate the keystore file. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL The job's library list is searched for the first occurence of the specified file name.

Record label
The label of a key record in a keystore file. The label will be converted from the job CCSID, or if 65535, the job default CCSID (DFTCCSID) job attribute to CCSID 1200 (Unicode UTF-16). Key records are created by using the Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord API or the Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord) API.

Reserved
Must be null (binary 0s).

Salt
Used to help thwart attacks by producing a large set of keys for each passphrase. The standard recommends the salt be generated at random and be at least 8 bytes long. You can use the Generate Pseudorandom Numbers (OPM, QC3GENPRN; ILE, Qc3GenPRNs) API to obtain a random value. Additionally, data that distinguishes between various operations can be added to the salt for additional security. Refer to the standard for more information.

Salt length
The length of salt. The length must be in the range of 1 to 16.

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.
CPF3CF2 E Error(s) occurred during running of &1 API.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.
CPF9D94 E A pending value exists for a master key.
CPF9D9C E Function is disallowed with specified key context.
CPF9D9F E Not authorized to keystore file.
CPF9DA0 E Error occured opening keystore file.
CPF9DA1 E Key record not found.
CPF9DA5 E Keystore file not found.
CPF9DA6 E The keystore file is not available.
CPF9DA7 E File is corrupt or not a valid keystore file.
CPF9DAA D A key requires translation.
CPF9DAB E A key can not be decrypted.
CPF9DB1 E The CCSID is not valid.
CPF9DB3 E Qualified keystore file name not valid.
CPF9DB6 E Record label not valid.
CPF9DB8 E Error occured retrieving key record from keystore.
CPF9DBA E Derived key length not valid.
CPF9DBB E Iteration count not valid.
CPF9DBC E Salt length not valid.
CPF9DBD E Passphrase length not valid.
CPF9DC2 E Key-encrypting algorithm context not compatible with key-encrypting key context.
CPF9DC3 E Unable to decrypt data or key.
CPF9DC6 E Algorithm not valid for encrypting or decrypting a key.
CPF9DC7 E The output data parameter specifies a NULL pointer.
CPF9DC8 E The input data parameter specifies a NULL pointer.
CPF9DC9 E The total length of data in the input data array is not valid.
CPF9DCD E Pad character not valid.
CPF9DCE E A data length is not valid.
CPF9DCF E A data pointer is not valid.
CPF9DD0 E Clear data format name not valid.
CPF9DD2 E Algorithm description format name not valid.
CPF9DD3 E Key description format name not valid.
CPF9DD5 E Length of input data not valid.
CPF9DD6 E Length of area provided for output data is too small.
CPF9DD7 E The key-encrypting key context for the specified key is not valid or was previously destroyed.
CPF9DD8 E The key-encrypting algorithm context for the specified key is not valid or was previously destroyed.
CPF9DD9 E Effective key size not valid.
CPF9DDA E Unexpected return code &1.
CPF9DDB E The key string or Diffie-Hellman parameter string is not valid.
CPF9DDD E The key string length is not valid.
CPF9DDE E Cipher algorithm not valid.
CPF9DDF E Block length not valid.
CPF9DE2 E MAC (message authentication code) length not valid.
CPF9DE3 E Mode not valid.
CPF9DE4 E Pad option not valid.
CPF9DE7 E Key type not valid.
CPF9DE9 E Key format not valid.
CPF9DEC E Cryptographic service provider not valid.
CPF9DED E Final operation flag not valid.
CPF9DEE E Reserved field not null.
CPF9DF0 E Operation, algorithm, or mode not available on the requested CSP (cryptographic service provider).
CPF9DF1 E The algorithm context token does not reference a valid algorithm context.
CPF9DF2 E The algorithm context is not found or was previously destroyed.
CPF9DF3 E Algorithm in algorithm context not valid for requested operation.
CPF9DF4 E The key context token does not reference a valid key context.
CPF9DF5 E The key context is not found or was previously destroyed.
CPF9DF7 E Algorithm context not compatible with key context.
CPF9DF8 E Cryptographic device name not valid.
CPF9DF9 E Cryptographic device not found.
CPF9DFB E Cryptographic service provider (CSP) conflicts with the key context CSP.
CPF9DFD E Not authorized to device.
CPF9DFE E Cryptographic device not available.

API introduced: V5R3

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