Decrypt With MAC (QC3DECWM, Qc3DecryptWithMAC) API


  Required Parameter Group:


  Service Program Name: QC3MACDE

  Default Public Authority: *USE

  Threadsafe: Yes

The Decrypt With MAC (OPM, QC3DECWM; ILE, Qc3DecryptWithMAC) API decrypts and verifies data that was encrypted and authenticated with the Encrypt With MAC (OPM, QC3ENCWM; ILE, Qc3EncryptWithMAC) API.


Authorities and Locks

Required device description authority
*USE

Required file authority
*OBJOPR, *READ

Required Parameter Group

Encrypted data
INPUT; CHAR(*)

The data to decrypt and verify.

Length of encrypted data
INPUT; BINARY(4)

The length of the encrypted data parameter.

Associated data
INPUT; CHAR(*)

The additional data that will be used to verify the clear data.

After decrypting the encrypted data, the associated data is placed ahead of the decrypted data and a MAC (message authentication code) is produced for the entire string. This MAC is compared with the MAC that was at the end of the encrypted data.

Length of associated data
INPUT; BINARY(4)

The length of the associated data parameter.

Algorithm description
INPUT; CHAR(*)

The algorithm and associated parameters for decrypting and verifying 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.

ALGD0210
Parameters for a block cipher algorithm with authentication.

See Algorithm Description Formats for a description of these formats.

Key description
INPUT; CHAR(*)

The key and associated parameters for decrypting and verifying the data.
The format of the key description is specified in the key description format name parameter.

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
Key context token. 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 operation.


Cryptographic device name
INPUT; CHAR(10)

This parameter must be set to blanks or the pointer to this parameter set to NULL.

Clear data
OUTPUT; CHAR(*)

The area to store the decrypted and verified data.
To ensure sufficient space, specify an area at least as large as the length of encrypted data. If the length of area provided for clear data is too small, an error will be generated and no data will be returned in the clear data parameter.

Length of area provided for clear data
INPUT; BINARY(4)

The length of the clear data parameter.

Length of clear data returned
OUTPUT; BINARY(4)

The length of clear data returned in the clear data parameter.

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 table fields, see Algorithm Description Formats Field Descriptions. For algorithm standards and resources, see Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.

ALGD0210 Format



Algorithm Description Formats Field Descriptions

Block cipher algorithm
The decryption algorithm. Following are the valid block cipher algorithms.
Block length
The algorithm block length. This field must specify 16.

MAC length
An encrypted MAC will be appended to the end of the encrypted data. The MAC can be 4, 6, 8, 10, 12, 14, or 16 bytes in length. The MAC length should match what was specified on the encrypt with MAC operation.

Mode
The mode of operation. Following are the valid modes.

CCM (Counter with CBC-MAC) is a mode of operation for a 128-bit block cipher algorithm, such as AES. CCM is used to provide data confidentiality and authentication by combining the techniques of Counter (CTR) mode and Cipher Block Chaining (CBC) mode of message authentication code (MAC) generation. CCM is defined in RFC3610 and NIST Special Publication 800-38C.

GCM (Galois/Counter Mode) is a mode of operation for a 128-bit block cipher algorithm, such as AES. GCM is used to provide data confidentiality and authentication by combining a variation of Counter (CTR) mode and GHASH, a GCM approved keyed hash function. GCM is defined in NIST Special Publication 800-38D.

Nonce
The nonce need not be secret, but it should be significantly unique for each message. If not unique, it will compromise security. The nonce should match what was specified on the encrypt with MAC operation.

Nonce length
Valid values for nonce length are 7 - 13.

Reserved
Must be null (binary 0s).


Key Description Formats

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

KEYD0100 Format

KEYD0200 Format


KEYD0400 Format

KEYD0500 Format



Key Description Formats Field Descriptions

Derived key length
The length of key requested. This value must be 16, 24, or 32.

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.
Key string
The key to use in the decrypt with MAC operation.

Key string length
Length of the key string specified in the key string field. The key string length must be 16, 24, or 32.

Key type
The type of key. Following are the valid values.
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.


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.
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. See the standard for more information.

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

Error Messages




API introduced: V6R1

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