Encrypt With MAC (QC3ENCWM, Qc3EncryptWithMAC) API


  Required Parameter Group:

1 Clear data Input Char(*)
2 Length of clear data Input Binary(4)
3 Associated data Input Char(*)
4 Length of associated data Input Binary(4)
5 Algorithm description Input Char(*)
6 Algorithm description format name Input Char(8)
7 Key description Input Char(*)
8 Key description format name Input Char(8)
9 Cryptographic service provider Input Char(1)
10 Cryptographic device name Input Char(10)
11 Encrypted data Output Char(*)
12 Length of area provided for encrypted data Input Binary(4)
13 Length of encrypted data returned Output Binary(4)
14 Error code I/O Char(*)

  Service Program Name: QC3MACEN

  Default Public Authority: *USE

  Threadsafe: Yes

The Encrypt With MAC (OPM, QC3ENCWM; ILE, Qc3EncryptWithMAC) API both authenticates and encrypts data in a single operation. To recover the clear data from the encrypted data, use the Decrypt With MAC (OPM, QC3DECWM; ILE, Qc3DecryptWithMAC) API.


Authorities and Locks

Required device description authority
*USE

Required file authority
*OBJOPR, *READ

Required Parameter Group

Clear data
INPUT; CHAR(*)

The data to encrypt. Before encryption, this data will be authenticated along with the associated data.

If the Length of clear data parameter is 0, this parameter may be set to NULL.

Length of clear data
INPUT; BINARY(4)

The length of the clear data parameter.
The length of data to encrypt must be less than 28(15-Nonce length).

Associated data
INPUT; CHAR(*)

The additional data that will be authenticated along with the clear data.

The associated data is not encrypted, but is authenticated along with the clear data. The associated data is placed ahead of the clear data and a MAC (message authentication code) is produced for the entire string. The MAC is then appended to the end of the clear data prior to encryption.

If the Length of associated data parameter is 0, this parameter may be set to NULL.

Length of associated data
INPUT; BINARY(4)

The length of the associated data parameter.
The length must be less than 264.

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.

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 to use for authenticating and encrypting 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 on 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 encryption operation.

1 Software CSP.
The system will perform the encryption operation using software. If the requested algorithm is not available in software, an error is returned.

Cryptographic device name
INPUT; CHAR(10)

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

Encrypted data
OUTPUT; CHAR(*)

The area to store the encrypted and authenticated data.

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

The length of the encrypted data parameter.
Note that the length of encrypted data will be the length of clear data plus the length of the MAC value (specified in the algorithm description). If the length of area provided for encrypted data is too small, an error will be generated and no data will be returned in the encrypted data parameter.

Length of encrypted data returned
OUTPUT; BINARY(4)

The length of encrypted data returned in the encrypted 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

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(3) Reserved
12 C BINARY(4) MAC length
16 10 BINARY(4) Nonce length
20 14 CHAR(32) Nonce


Algorithm Description Formats Field Descriptions

Block cipher algorithm
The encryption algorithm. Following are the valid block cipher algorithms.
22 AES
Documented in FIPS 197.

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 must be 4, 6, 8, 10, 12, 14, or 16 bytes in length. A MAC of at least 8 bytes is recommended.

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

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.

Nonce
The nonce need not be secret, but it should be unique for each message. If not unique, it will compromise security. The nonce can be any value. To obtain a good random nonce value, use the Generate Pseudorandom Numbers (OPM, QC3GENPRN; ILE, Qc3GenPRNs) API.

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

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. 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 PKCS5 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 encrypt 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.
22 AES

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 i5/OS globalization.

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 PKCS5 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 PKCS5 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.
CPF9D9A E Key is protected by a cryptographic coprocessor.
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.
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.
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.
CPF9DD4 E Length of clear 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.
CPF9DDA E Unexpected return code &1.
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.
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.
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.
CPF9DFB E Cryptographic service provider (CSP) conflicts with the key context CSP.

API introduced: V6R1

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