Create PKCS #7 EnvelopedData content information

Parameters

version

Specifies the PKCS #7 EnvelopedData version number. Specify 0 to create EnvelopedData content as described in PKCS #7 Version 1.5. Specify 1 to create EnvelopedData content 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.

content_data

Specifies the EnvelopedData content. This must be one of the content information types defined in PKCS #7.

content_info

Returns the EnvelopedData content information. 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 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_BAD_RNG_OUTPUT]

In FIPS mode, random bytes generation produced duplicate output.

[CMSERR_CONTENT_NOT_SUPPORTED]

The content type is not supported

[CMSERR_ICSF_FIPS_DISABLED]

ICSF PKCS #11 services are disabled.

[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_content() routine creates PKCS #7 (Cryptographic Message Syntax) EnvelopedData content information. The data content type must be one of the types defined by PKCS #7. The gsk_read_enveloped_data_content() routine can be used to extract the content data from the EnvelopedData content information. No validity checking is performed on the recipient certificates. It is assumed that the application has already validated the recipient certificates.

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, 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.