gsk_make_enveloped_private_key

Creates a PKCS #7 EnvelopedData message from application data. The application data passed in is the PKCS #11 secure key label name.

Format

   #include <gskcms.h>

   gsk_status gsk_make_enveloped_private_key_msg (
                                          gsk_uint32							    option_flag,
                                          int										        version,
                                          x509_algorithm_type		encryption_algorithm,
                                          pkcs_certificates *		recipient_certificates,
                                          gsk_buffer *						   secure_key_label,
                                          gsk_buffer *						   stream)

Parameters

option_flag

Specifies process options to customize process behavior. Specify execution options using bit setting.

GSK_PROCESS_OPTION_ENFORCE_KEYUSAGE - 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 is supported.
Any other bit values are ignored.

version

Specify PKCS #7 EnvelopedData version number. Only version 0, PKCS #7 Version 1.5, is supported.

encryption_algorithm

Specifies the algorithm to be used:

x509_alg_aesCbc128 for AES with Key length 16.
x509_alg_aesCbc256 for AES with Key length 32.
x509_alg_desEde3CbcPad for 3DES with Key length 24.

recipient_certificates

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

secure_key_label

Specifies a PKCS #11 secure private key label object. No other type of object is supported.

stream

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

Results

The function return value will be 0 (GSK_OK) 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 recipient key size is not supported.
[CMSERR_CRYPTO_HARDWARE_NOT_AVAILABLE]: Cryptographic hardware does not support service or algorithm.
[CMSERR_ICSF_FIPS_BAD_ALG_OR_KEY_SIZE]: A recipient algorithm or key size is not FIPS approved for an ICSF operation.
[CMSERR_ICSF_FIPS_DISABLED]: ICSF PKCS #11 services are disabled.
[CMSERR_ICSF_NOT_FIPS]: ICSF is not operating in FIPS mode.
[CMSERR_INCORRECT_KEY_ATTRIBUTE]: Key attributes do not support envelope operation.
[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_MEMORY]: Insufficient storage is available.
[CMSERR_NO_PKCS11_OBJECT_NOT_FOUND]: A PKCS #11 key label is either missing or not valid.
[CMSERR_NO_PRIVATE_KEY]: No private key.
[CMSERR_PKCS11_LABEL_INVALID]: PKCS #11 label is not valid.
[CMSERR_RECIPIENT_NOT_FOUND]: No recipient certificates provided.

Usage

The gsk_make_enveloped_private_key_msg() routine creates a PKCS #7 (Cryptographic Message Syntax) EnvelopedData message using a TKDS secure private key label and returns the ASN.1 DER-encoded ContentInfo sequence. The gsk_read_enveloped_data_content() routine or the gsk_read_enveloped_data_content_extended() 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 validated the recipient certificates.

A session key is used to encrypt the message content. A new session key is generated but is not returned to the application. For each recipient, the session key is encrypted with the public key of the recipient and stored in the EnvelopedData message. Each recipient's public key must be type RSA.

In addition, if option_flag specifies that key usage is to be enforced, then each recipient certificate key usage must allow key encipherment.

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

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}