KDE PIM / Developers / API Docs / certmanager

CryptPlug::StructuringInfo Struct Reference
[Signing and Encrypting Actions]

Information record returned by signing and by encrypting functions - this record should be used together with a corresponding free_StructuringInfo() function call. More...

#include <cryptplug.h>

List of all members.

Public Attributes


Detailed Description

Information record returned by signing and by encrypting functions - this record should be used together with a corresponding free_StructuringInfo() function call.

Use this information to compose a MIME object containing signed and/or encrypted content (or to build a text frame around your flat non-MIME message body, resp.)

If value returned in makeMimeObject is TRUE the text strings returned in contentTypeMain and contentDispMain and contentTEncMain (and, if required, content[..]Version and bodyTextVersion and content[..]Sig) should be used to compose a respective MIME object.
If FALSE the texts returned in flatTextPrefix and flatTextSeparator and flatTextPostfix are to be used instead.
Allways either the content[..] and bodyTextVersion parameters or the flatText[..] parameters are holding valid data - never both of them may be used simultaneously as plugins will just ignore the parameters not matching their makeMimeObject setting.

When creating your MIME object please observe these common rules:

If makeMultiMime returns FALSE the contentTypeMain returned must not be altered but used to specify a single part mime object holding the code bloc, e.g. this is used for 'enveloped-data' single part MIME objects. In this case you should ignore both the content[..]Version and content[..]Code parameters.

If makeMultiMime returns TRUE also the following rules apply:

If value returned in makeMimeObject is FALSE the text strings returned in flatTextPrefix and flatTextPostfix should be used to build a frame around the cleartext and the code bloc holding the signature (or - in case of encrypting - the encoded data bloc, resp.).
If includeCleartext is TRUE this frame should also include the cleartext as first bloc, this bloc should be divided from the code bloc by the contents of flatTextSeparator - typically this is used for signing but not when encrypting.
If includeCleartext is FALSE you should ignore both the cleartext and the flatTextSeparator parameter.

How to use StructuringInfo data in your program:

    char* ciphertext;
    StructuringInfo structInf;

    if( ! signMessage( cleartext, &ciphertext, certificate,
                       &structuring ) ) {

        myErrorDialog( "Error: could not sign the message!" );

    } else {
      if( structInf.makeMimeObject ) {

        // Build the main MIME object.
        // This is done by
        // using the header values returned in
        // structInf.contentTypeMain and in
        // structInf.contentDispMain and in
        // structInf.contentTEncMain.
        ..

        if( ! structInf.makeMultiMime ) {

          // Build the main MIME object's body.
          // This is done by
          // using the code bloc returned in
          // ciphertext.
          ..

        } else {

          // Build the encapsulated MIME parts.
          if( structInf.includeCleartext ) {

            // Build a MIME part holding the cleartext.
            // This is done by
            // using the original cleartext's headers and by
            // taking it's original body text.
            ..

          }
          if(    structInf.contentTypeVersion
              && 0 < strlen( structInf.contentTypeVersion ) ) {

            // Build a MIME part holding the version information.
            // This is done by
            // using the header values returned in
            // structInf.contentTypeVersion and
            // structInf.contentDispVersion and
            // structInf.contentTEncVersion and by
            // taking the body contents returned in
            // structInf.bodyTextVersion.
            ..

          }
          if(    structInf.contentTypeCode
              && 0 < strlen( structInf.contentTypeCode ) ) {

            // Build a MIME part holding the code information.
            // This is done by
            // using the header values returned in
            // structInf.contentTypeCode and
            // structInf.contentDispCode and
            // structInf.contentTEncCode and by
            // taking the body contents returned in
            // ciphertext.
            ..

          } else {

            // Plugin error!
            myErrorDialog( "Error: Cryptography plugin returned a main"
                           "Content-Type=Multipart/.. but did not "
                           "specify the code bloc's Content-Type header."
                           "\nYou may report this bug:"
                           "\n" + cryptplug.bugURL() );
          }
        }
      } else  {

        // Build a plain message body
        // based on the values returned in structInf.
        // Note: We do _not_ insert line breaks between the parts since
        //       it is the plugin job to provide us with ready-to-use
        //       texts containing all neccessary line breaks.
        strcpy( myMessageBody, structInf.plainTextPrefix );
        if( structInf.includeCleartext ) {
          strcat( myMessageBody, cleartext );
          strcat( myMessageBody, structInf.plainTextSeparator );
        }
        strcat( myMessageBody, *ciphertext );
        strcat( myMessageBody, structInf.plainTextPostfix );
      }

      // free the memory that was allocated
      // for the ciphertext
      free( ciphertext );

      // free the memory that was allocated
      // for our StructuringInfo's char* members
      free_StructuringInfo( &structuring );
    }

Note:
Make sure to call free_StructuringInfo() when you are done with processing the StructuringInfo data!
See also:
free_StructuringInfo

signMessage, encryptMessage, encryptAndSignMessage


Member Data Documentation

bool CryptPlug::StructuringInfo::includeCleartext
 

specifies whether we should include the cleartext as first part of our multipart MIME object (or - for non-MIME messages - as flat text to be set before the ciphertext, resp.), typically this is TRUE when signing mails but FALSE when encrypting
(this parameter is relevant no matter whether makeMimeObject is TRUE or FALSE)

bool CryptPlug::StructuringInfo::makeMimeObject
 

specifies whether we should create a MIME object or a flat text message body

bool CryptPlug::StructuringInfo::makeMultiMime
 

specifies whether we should create a 'Multipart' MIME object or a single part object, if FALSE only contentTypeMain, contentDispMain and contentTEncMain may be used and all other parameters have to be ignored
(ignore this parameter if makeMimeObject is FALSE)

char* CryptPlug::StructuringInfo::contentTypeMain
 

value of the main 'Content-Type' header
(ignore this parameter if makeMimeObject is FALSE)

char* CryptPlug::StructuringInfo::contentDispMain
 

value of the main 'Content-Disposition' header
(ignore this parameter if makeMimeObject is FALSE)

char* CryptPlug::StructuringInfo::contentTEncMain
 

value of the main 'Content-TransferEncoding' header
(ignore this parameter if makeMimeObject is FALSE)

char* CryptPlug::StructuringInfo::contentTypeVersion
 

'Content-Type' of the additional version part that might preceed the code part - if NULL or zero length no version part must be created
(ignore this parameter if either makeMimeObject or makeMultiMime is FALSE)

char* CryptPlug::StructuringInfo::contentDispVersion
 

'Content-Disposition' of the additional preceeding the code part (only valid if contentTypeVersion holds a non-zero-length string)
(ignore this parameter if either makeMimeObject or makeMultiMime is FALSE or if contentTypeVersion does not return a non-zero-length string)

char* CryptPlug::StructuringInfo::contentTEncVersion
 

'Content-Transfer-Encoding' of the additional version part (only valid if contentTypeVersion holds a non-zero-length string)
(ignore this parameter if either makeMimeObject or makeMultiMime is FALSE or if contentTypeVersion does not return a non-zero-length string)

char* CryptPlug::StructuringInfo::bodyTextVersion
 

body text of the additional version part (only valid if contentTypeVersion holds a non-zero-length string)
(ignore this parameter if either makeMimeObject or makeMultiMime is FALSE or if contentTypeVersion does not return a non-zero-length string)

char* CryptPlug::StructuringInfo::contentTypeCode
 

'Content-Type' of the code part holding the signature code (or the encrypted data, resp.)
(ignore this parameter if either makeMimeObject or makeMultiMime is FALSE)

char* CryptPlug::StructuringInfo::contentDispCode
 

'Content-Disposition' of the code part
(ignore this parameter if either makeMimeObject or makeMultiMime is FALSE or if contentTypeCode does not return a non-zero-length string)

char* CryptPlug::StructuringInfo::contentTEncCode
 

'Content-Type' of the code part
(ignore this parameter if either makeMimeObject or makeMultiMime is FALSE or if contentTypeCode does not return a non-zero-length string)

char* CryptPlug::StructuringInfo::flatTextPrefix
 

text to preceed the main text (or the code bloc containing the encrypted main text, resp.)
(ignore this parameter if makeMimeObject is TRUE)

char* CryptPlug::StructuringInfo::flatTextSeparator
 

text to be put between the main text and the signature code bloc (not used when encrypting)
(ignore this parameter if makeMimeObject is TRUE or if includeCleartext is FALSE)

char* CryptPlug::StructuringInfo::flatTextPostfix
 

text to follow the signature code bloc (or the encrypted data bloc, resp.)
(ignore this parameter if makeMimeObject is TRUE)


The documentation for this struct was generated from the following file: