gsk_read_enveloped_data_content

Processes PKCS #7 EnvelopedData content information.

Format

#include <gskcms.h>

gsk_status gsk_read_enveloped_data_content_extended (
                                            gsk_process_option         option_flag
                                            pkcs_cert_keys *           recipient_keys,
                                            pkcs_content_info *        content_info,
                                            x509_algorithm_type *      encryption_algorithm,
                                            gsk_size *                 key_size,
                                            pkcs_content_info *        content_data)

Parameters

option_flag

Specifies process options to customize process behavior.

Enforce recipient certificate has key encipherment capabilities. That is, the purpose of the certificate key as reflected by the key usage extension must indicate keyEncipherment.
Enforce key parity when using DES or 3DES session keys.

recipient_keys

Specifies one or more certificates and associated private keys.

content_info

Specifies the content information to be processed.

encryption_algorithm

Returns the encryption algorithm used to encrypt the message content.

key_size

Returns the encryption key size in bytes.

content_data

Returns the EnvelopedData content data. The application should call the gsk_free_content_info() routine to release the content information when it is no longer needed.

Results

The function return value will be 0 if no error is detected. Otherwise, it is one of the return codes listed in the gskcms.h include file. These are some possible errors:

[CMSERR_ALG_NOT_AVAILABLE]: The encryption algorithm is not available.
[CMSERR_ALG_NOT_SUPPORTED]: The encryption algorithm is not supported.
[CMSERR_BAD_KEY_SIZE]: The encryption key size is not supported.
[CMSERR_CONTENT_NOT_SUPPORTED]: The message content type is not EnvelopedData or the content of the EnvelopedData message is not supported.
[CMSERR_CRYPTO_HARDWARE_NOT_AVAILABLE]: Cryptographic hardware does not support service or algorithm.
[CMSERR_INCORRECT_KEY_USAGE]: The recipient certificate does not allow key encipherment.
[CMSERR_KEY_MISMATCH]: A recipient private key does not support data decryption.
[CMSERR_NO_CONTENT_DATA]: The content data length is zero.
[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_NO_PRIVATE_KEY]: Private key does not exist or is not accessible.
[CMSERR_RECIPIENT_NOT_FOUND]: No matching recipient certificate provided.

Usage

The gsk_read_enveloped_data_content_extended() routine processes PKCS #7 (Cryptographic Message Syntax) EnvelopedData content information that is created by the gsk_make_enveloped_data_content() routine, the gsk_make_enveloped_data_content_extended(), or the gsk_make_enveloped_private_key_msg() routine. Processing is equivalent to gsk_read_enveloped_data_content(), except that the recipient certificate key usage need not assert key encipherment.

The recipient_keys parameter supplies one or more recipient certificates and associated private keys. The gsk_read_enveloped_data_content_extended() routine searches for a certificate matching one of the message recipients. The private key will be used to decrypt the session key and the session key will then be used to decrypt the enveloped data. In addition, if option_flag specifies that key encipherment is to be enforced, then the certificate key usage must allow key encipherment and session keys need not be odd parity.

No certificate validation is performed by the gsk_read_enveloped_data_content_extended() routine. It is assumed that the application has already validated the recipient certificates.

These encryption algorithms are supported. Strong encryption might not be available depending upon government export regulations.

x509_alg_rc2CbcPad - 40-bit and 128-bit RC2 - {1.2.840.113549.3.2}
x509_alg_rc4 - 40-bit and 128-bit RC4 - {1.2.840.113549.3.4}
x509_alg_desCbcPad - 56-bit DES - {1.3.14.3.2.7}
x509_alg_desEde3CbcPad - 168-bit 3DES - {1.2.840.113549.3.7}
x509_alg_aesCbc128 - 128-bit AES CBC - {2.16.840.1.101.3.4.1.2}
x509_alg_aesCbc256 - 256-bit AES CBC - {2.16.840.1.101.3.4.1.42}

When executing in FIPS mode, encryption algorithms x509_alg_rc2CbcPad, x509_alg_rc4 and x509_alg_desCbcPad are not supported.