Creates a PKCS #7 EnvelopedData message from application 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.

version

Specifies the PKCS #7 EnvelopedData version number. Specify 0 to create an EnvelopedData message as described in PKCS #7 Version 1.5. Specify 1 to create an EnvelopedData message as described in PKCS #7 Version 1.6.

session_key

Specifies the session encryption key as follows:

• The encryptionType field specifies the encryption algorithm.
• The encryptionKey.length field specifies the encryption key length in bytes.
• The encryptionKey.data field specifies the address of the encryption key. A new key will be generated and returned in this parameter if the key address is NULL. If a new key is generated, the application should call the gsk_free_buffer() routine to release the key when it is no longer needed. Note that the encryptionType and encryptionKey.length fields must be set by the application even when a new session key is to be generated.

recipient_certificates

Specifies the certificates for the message recipients. There must be at least one recipient.

data

Specifies the application data for the EnvelopedData message.

stream

Returns the ASN.1 DER-encoded stream. The application should call the gsk_free_buffer() routine to release the stream when it is no longer needed.

Results

The function return value will be 0 if no error is detected. Otherwise, it will be 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 content type is not supported.

[CMSERR_INCORRECT_KEY_USAGE]

A recipient certificate does not allow key encipherment.

[CMSERR_KEY_MISMATCH]

A recipient public key does not support data encryption.

[CMSERR_NO_CONTENT_DATA]

The content data length is zero.

[CMSERR_NO_MEMORY]

Insufficient storage is available.

[CMSERR_RECIPIENT_NOT_FOUND]

No recipient certificates provided.

[CMSERR_VERSION_NOT_SUPPORTED]

The version is not valid.

Usage

The gsk_make_enveloped_data_msg_extended() routine creates a PKCS #7 (Cryptographic Message Syntax) EnvelopedData message and returns the ASN.1 DER-encoded ContentInfo sequence. Processing is equivalent to gsk_make_enveloped_data_msg(), except that the recipient certificate key usage need not assert key encipherment. The enveloped data content type will be Data. The gsk_read_enveloped_data_msg() routine or the gsk_read_enveloped_data_msg_extended() routine can be used to extract the application data from the stream. No validity checking is performed on the recipient certificates. It is assumed that the application has already validated the recipient certificates.

Calling the gsk_make_enveloped_data_msg_extended() routine is equivalent to calling the gsk_make_data_content() routine, the gsk_make_enveloped_data_content_extended() routine, and the gsk_make_content_msg() routine.

The session key is used to encrypt the message content. A new session key is generated and returned to the application if no key is provided. For each recipient, the session key is encrypted with the recipient's public key and stored in the EnvelopedData message. This means the public key algorithm must support data encryption. Currently, only RSA public keys support data encryption. In addition, if option_flag specifies that key encipherment is to be enforced, then the certificate key usage must allow key encipherment.

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

• x509_alg_rc2CbcPad - 40-bit and 128-bit RC2 - Key lengths 5 and 16 - {1.2.840.113549.3.2}
• x509_alg_rc4 - 40-bit and 128-bit RC4 - Key lengths 5 and 16 - {1.2.840.113549.3.4}
• x509_alg_desCbcPad - 56-bit DES - Key length 8 - {1.3.14.3.2.7}
• x509_alg_desEde3CbcPad - 168-bit 3DES - Key length 24 - {1.2.840.113549.3.7}
• x509_alg_aesCbc128 - 128-bit AES CBC - Key length 16 - {2.16.840.1.101.3.4.1.2}
• x509_alg_aesCbc256 - 256-bit AES CBC - Key length 32 - {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.