Creates a PKCS #7 EnvelopedData message from application
data.
Format
#include <gskcms.h>
gsk_status gsk_make_enveloped_data_msg (
int version,
pkcs_session_key * session_key,
pkcs_certificates * recipient_certificates,
gsk_buffer * data,
gsk_buffer * stream)
Parameters
- 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() routine
creates a PKCS #7 (Cryptographic Message Syntax) EnvelopedData message
and returns the ASN.1 DER-encoded ContentInfo sequence. The enveloped
data content type will be Data. The gsk_read_enveloped_data_msg() 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() routine is equivalent to
calling the gsk_make_data_content() routine, the gsk_make_enveloped_data_content() 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, 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.