Previous: CMS Basics, Up: CMS

4.2 CMS Parser

KSBA includes a versatile CMS parser for encryption (enveloped data) and digital signing. The parser is capable of handling arbitrary amounts of data without requiring much memory. Well, certain objects are build in memory because it can be assumed that those objects are limited in size; e.g. it does not make sense to use a video clip as the DN despite the fact that the standard does not forbid it.

— Function: gpg_error_t ksba_cms_parse (ksba_cms_t cms, ksba_stop_reason_t *r_stopreason)

This is the core function of the parser and commonly used in a loop. The parsing process is divided into several phases to allow the user to get information at the right time and prepare for further processing. The caller has to act on certain stop reasons which are returned by r_stopreason and set up things accordingly; KSBA may introduce new stop reasons to let the caller know other details; there is no need for the caller to act on every stop reason; it should only do so for reasons that the caller understands and which are mandatory. The function will return with an error if the caller did not setup things correctly for certain stop reasons.

The use of this function is best explained by an example, leaving out all error checking. 

       do
         {
           ksba_cms_parse (cms, &stopreason);
           if (stopreason == KSBA_SR_BEGIN_DATA)
             {
               get_recipients ();
               decrypt_session_key ();
               setup_bulk_decryption ();
             }
           else if (stopreason == KSBA_SR_END_DATA)
             {
               remove_padding ();
             }
         }
       while (stopreason != KSBA_SR_READY);

This function assumes that the parsed data is so called `enveloped data'.

As CMS provides a common framework for a variety of data formats, it is probably very useful to check the type of that data very early. This can be accomplished by hooking into the stop reason KSBA_SR_GOT_CONTENT and retrieving the content using the following function.

— Function: ksba_content_t ksba_cms_get_content_type (ksba_cms_t cms, int what)

By using a value of 0 for what this function returns the content type of the outer container; using 1 does return the content type of the enclosed object.

— Data type: ksba_content_t

The ksba_content_t type is an enumeration used to describe the content of a CMS message. Here is a list of possible values:

KSBA_CT_NONE
No content type known (value 0)
KSBA_CT_DATA
The content is plain data, not further interpreted.
KSBA_CT_SIGNED_DATA
The content is an signed CMS object. This also includes the case of a detached signature where no actual data is included in the message.
KSBA_CT_ENVELOPED_DATA
The content is encrypted using a session key.
KSBA_CT_DIGESTED_DATA
Not yet supported
KSBA_CT_ENCRYPTED_DATA
Not yet supported
KSBA_CT_AUTH_DATA
Not yet supported

— Function: const char * ksba_cms_get_content_oid (ksba_cms_t cms, int what)

Return the object ID of cms. This is a constant string valid as long as the context is valid and no new parse is started. This function is similar to ksba_cms_get_content_type but returns the OID actually used in the data. Depending on the value of what different values are returned: Using a value of 0 yields the OID of the outer container, a value of 1 yields the OID of the inner container if available and the value 2 returns the OID of the algorithm used to encrypt the inner container.