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.
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:
- Parameters named
contentType
[..] and contentDisp
[..] and contentTEnc
[..] will return the values for the respective MIME headers 'Content-Type' and 'Content-Disposition' and 'Content-Transfer-Encoding'. The following applies to these parameters:
- The relevant MIME part may only be created if the respective
contentType
[..] parameter is holding a non-zero-length string. If the contentType
[..] parameter value is invalid or holding an empty string the respective contentDisp
[..] and contentTEnc
[..] parameters should be ignored.
- If the respective
contentDisp
[..] or contentTEnc
[..] parameter is NULL or holding a zero-length string it is up to you whether you want to add the relevant MIME header yourself, but since it in in the responsibility of the plugin implementors to provide you with all neccessary 'Content-[..]' header information you should not need to define them if they are not returned by the signing or encrypting function - otherwise this may be considered as a bug in the plugin and you could report the missing MIME header information to the address returned by the bugURL()
function.
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
includeCleartext
is TRUE you should include the cleartext as first part of our multipart MIME object, typically this is TRUE when signing mails but FALSE when encrypting.
- The
contentTypeMain
returned typically starts with "multipart/" while providing a "protocol" and a "micalg" parameter: just add an appropriate "; boundary=[your \c boundary \c string]"
to get the complete Content-Type value to be used for the MIME object embedding both the signed part and the signature part (or - in case of encrypting - the version part and the code part, resp.).
- If
contentTypeVersion
is holding a non-zero-length string an additional MIME part must added immediately before the code part, this version part's MIME headers must have the unaltered values of contentTypeVersion
and (if they are holding non-zero-length strings) contentDispVersion
and contentTEncVersion
, the unaltered contents of bodyTextVersion
must be it's body.
- The value returned in
contentTypeCode
is specifying the complete Content-Type to be used for this multipart MIME object's signature part (or - in case of encrypting - for the code part following after the version part, resp.), you should not add/change/remove anything here but just use it's unaltered value for specifying the Content-Type header of the respective MIME part.
- The same applies to the
contentDispCode
value: just use it's unaltered value to specify the Content-Disposition header entry of the respective MIME part.
- The same applies to the
contentTEncCode
value: just use it's unaltered value to specify the Content-Transfer-Encoding header of the respective MIME part.
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:
- To compose a signed message please act as described below.
- For constructing an encrypted message just replace the
signMessage()
call by the respective encryptMessage()
call and then proceed exactly the same way.
- In any case make sure to free your
ciphertext
and to call free_StructuringInfo()
when you are done with processing the data returned by the signing (or encrypting, resp.) function.
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
Definition at line 667 of file cryptplug.h.
Member Data Documentation
|
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) Definition at line 668 of file cryptplug.h. |
|
specifies whether we should create a MIME object or a flat text message body Definition at line 678 of file cryptplug.h. |
|
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) Definition at line 681 of file cryptplug.h. |
|
value of the main 'Content-Type' header
(ignore this parameter if makeMimeObject is FALSE) Definition at line 689 of file cryptplug.h. |
|
value of the main 'Content-Disposition' header
(ignore this parameter if makeMimeObject is FALSE) Definition at line 693 of file cryptplug.h. |
|
value of the main 'Content-TransferEncoding' header
(ignore this parameter if makeMimeObject is FALSE) Definition at line 697 of file cryptplug.h. |
|
'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) Definition at line 701 of file cryptplug.h. |
|
'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) Definition at line 708 of file cryptplug.h. |
|
'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) Definition at line 716 of file cryptplug.h. |
|
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) Definition at line 724 of file cryptplug.h. |
|
'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) Definition at line 731 of file cryptplug.h. |
|
'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) Definition at line 737 of file cryptplug.h. |
|
'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) Definition at line 742 of file cryptplug.h. |
|
text to preceed the main text (or the code bloc containing the encrypted main text, resp.)
(ignore this parameter if makeMimeObject is TRUE) Definition at line 748 of file cryptplug.h. |
|
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) Definition at line 753 of file cryptplug.h. |
|
text to follow the signature code bloc (or the encrypted data bloc, resp.)
(ignore this parameter if makeMimeObject is TRUE) Definition at line 759 of file cryptplug.h. |
The documentation for this struct was generated from the following file:
This file is part of the documentation for certmanager/lib Library Version 3.3.0.