summaryrefslogtreecommitdiffstats
path: root/certmanager/lib/cryptplug.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commit460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 (patch)
tree67208f7c145782a7e90b123b982ca78d88cc2c87 /certmanager/lib/cryptplug.h
downloadtdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.tar.gz
tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'certmanager/lib/cryptplug.h')
-rw-r--r--certmanager/lib/cryptplug.h954
1 files changed, 954 insertions, 0 deletions
diff --git a/certmanager/lib/cryptplug.h b/certmanager/lib/cryptplug.h
new file mode 100644
index 000000000..081702a7a
--- /dev/null
+++ b/certmanager/lib/cryptplug.h
@@ -0,0 +1,954 @@
+/* -*- Mode: C++ -*-
+
+ this is a C++-ification of:
+ CRYPTPLUG - an independent cryptography plug-in API
+
+ Copyright (C) 2001,2004 Klarälvdalens Datakonsult AB
+
+ CRYPTPLUG is free software; you can redistribute it and/or modify
+ it under the terms of GNU General Public License as published by
+ the Free Software Foundation; version 2 of the License.
+
+ CRYPTPLUG is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+*/
+
+#ifndef CRYPTPLUG_H
+#define CRYPTPLUG_H
+
+#include <stdlib.h>
+
+#include <gpgmepp/context.h>
+#include <gpgme.h> // need it for gpgme_protocol_t :(
+#include <kdepimmacros.h>
+
+namespace GpgME {
+ class ImportResult;
+}
+
+/*! \file cryptplug.h
+ \brief Common API header for CRYPTPLUG.
+
+ CRYPTPLUG is an independent cryptography plug-in API
+ developed for Sphinx-enabeling KMail and Mutt.
+
+ CRYPTPLUG was designed for the Aegypten project, but it may
+ be used by 3rd party developers as well to design pluggable
+ crypto backends for the above mentioned MUAs.
+
+ \note All string parameters appearing in this API are to be
+ interpreted as UTF-8 encoded.
+
+ \see pgpplugin.c
+ \see gpgplugin.c
+*/
+
+/*! \defgroup groupGeneral Loading and Unloading the Plugin, General Functionality
+
+ The functions in this section are used for loading and
+ unloading plugins. Note that the actual locating of the plugin
+ and the loading and unloading of the dynamic library is not
+ covered here; this is MUA-specific code for which support code
+ might already exist in the programming environments.
+*/
+
+/*! \defgroup groupDisplay Graphical Display Functionality
+
+ The functions in this section return stationery that the
+ MUAs can use in order to display security functionality
+ graphically. This can be toolbar icons, shortcuts, tooltips,
+ etc. Not all MUAs will use all this functionality.
+*/
+
+/*! \defgroup groupConfig Configuration Support
+
+ The functions in this section provide the necessary
+ functionality to configure the security functionality as well
+ as to query configuration settings. Since all configuration
+ settings will not be saved with the plugin, but rather with
+ the MUA, there are also functions to set configuration
+ settings programmatically; these will be used on startup of
+ the plugin when the MUA transfers the configuration values it
+ has read into the plugin. Usually, the functions to query and
+ set the configuration values are not needed for anything but
+ saving to and restoring from configuration files.
+*/
+
+
+/*! \defgroup groupConfigSign Signature Configuration
+ \ingroup groupConfig
+
+ The functions in this section provide the functionality
+ to configure signature handling and set and query the
+ signature configuration.
+*/
+
+/*! \defgroup groupConfigCrypt Encryption Configuration
+ \ingroup groupConfig
+
+ The functions in this section provide the functionality
+ to configure encryption handling and set and query the
+ encryption configuration.
+
+ \note Whenever the term <b> encryption</b> is used here,
+ it is supposed to mean both encryption and decryption,
+ unless otherwise specified.
+*/
+
+/*! \defgroup groupConfigDir Directory Service Configuration
+ \ingroup groupConfig
+
+ This section contains messages for configuring the
+ directory service.
+*/
+
+
+/*! \defgroup groupCertHand Certificate Handling
+
+ The following methods are used to maintain and query certificates.
+*/
+
+
+/*! \defgroup groupSignCryptAct Signing and Encrypting Actions
+
+ This section describes methods and structures
+ used for signing and/or encrypting your mails.
+*/
+
+
+/*! \defgroup groupSignAct Signature Actions
+ \ingroup groupSignCryptAct
+
+ This section describes methods that are used for working
+ with signatures.
+*/
+
+/*! \defgroup groupCryptAct Encryption and Decryption
+ \ingroup groupSignCryptAct
+
+ The following methods are used to encrypt and decrypt
+ email messages.
+*/
+
+/*! \defgroup groupCertAct Certificate Handling Actions
+
+ The functions in this section provide local certificate management.
+*/
+
+/*! \defgroup groupCRLAct CRL Handling Actions
+
+ This section describes functions for managing CRLs.
+*/
+
+/*! \defgroup groupAdUsoInterno Important functions to be used by plugin implementors ONLY.
+
+ This section describes functions that have to be used by
+ plugin implementors but should not be used by plugin users
+ directly.
+
+ If you are not planning to write your own cryptography
+ plugin <b>you should ignore this</b> section!
+*/
+
+/*! \defgroup certList Certificate Info listing functions
+ */
+
+typedef enum {
+ Feature_undef = 0,
+
+ Feature_SignMessages = 1,
+ Feature_VerifySignatures = 2,
+ Feature_EncryptMessages = 3,
+ Feature_DecryptMessages = 4,
+ Feature_SendCertificates = 5,
+ Feature_WarnSignCertificateExpiry = 6,
+ Feature_WarnSignEmailNotInCertificate = 7,
+ Feature_PinEntrySettings = 8,
+ Feature_StoreMessagesWithSigs = 9,
+ Feature_EncryptionCRLs = 10,
+ Feature_WarnEncryptCertificateExpiry = 11,
+ Feature_WarnEncryptEmailNotInCertificate = 12,
+ Feature_StoreMessagesEncrypted = 13,
+ Feature_CheckCertificatePath = 14,
+ Feature_CertificateDirectoryService = 15,
+ Feature_CRLDirectoryService = 16,
+ Feature_CertificateInfo = 17
+} Feature;
+
+/* dummy values */
+typedef enum {
+ PinRequest_undef = 0,
+
+ PinRequest_Always = 1,
+ PinRequest_WhenAddingCerts = 2,
+ PinRequest_AlwaysWhenSigning = 3,
+ PinRequest_OncePerSession = 4,
+ PinRequest_AfterMinutes = 5
+} PinRequests;
+
+
+typedef enum {
+ SignatureCompoundMode_undef = 0,
+
+ SignatureCompoundMode_Opaque = 1,
+ SignatureCompoundMode_Detached = 2
+} SignatureCompoundMode;
+
+
+typedef enum {
+ SendCert_undef = 0,
+
+ SendCert_DontSend = 1,
+ SendCert_SendOwn = 2,
+ SendCert_SendChainWithoutRoot = 3,
+ SendCert_SendChainWithRoot = 4
+} SendCertificates;
+
+
+typedef enum {
+ SignAlg_undef = 0,
+
+ SignAlg_SHA1 = 1
+} SignatureAlgorithm;
+
+
+
+typedef enum {
+ EncryptAlg_undef = 0,
+
+ EncryptAlg_RSA = 1,
+ EncryptAlg_SHA1 = 2,
+ EncryptAlg_TripleDES = 3
+} EncryptionAlgorithm;
+
+typedef enum {
+ SignEmail_undef = 0,
+
+ SignEmail_SignAll = 1,
+ SignEmail_Ask = 2,
+ SignEmail_DontSign = 3
+} SignEmail;
+
+typedef enum {
+ EncryptEmail_undef = 0,
+
+ EncryptEmail_EncryptAll = 1,
+ EncryptEmail_Ask = 2,
+ EncryptEmail_DontEncrypt = 3
+} EncryptEmail;
+
+typedef enum {
+ CertSrc_undef = 0,
+
+ CertSrc_Server = 1,
+ CertSrc_Local = 2,
+ CertSrc_ServerLocal = CertSrc_Server | CertSrc_Local
+} CertificateSource;
+
+
+/*! \ingroup groupSignAct
+ \brief Flags used to compose the SigStatusFlags value.
+
+ This status flags are used to compose the SigStatusFlags value
+ returned in \c SignatureMetaDataExtendedInfo after trying to
+ verify a signed message part's signature status.
+
+ The normal flags may <b>not</b> be used together with the
+ special SigStat_NUMERICAL_CODE flag. When finding the special
+ SigStat_NUMERICAL_CODE flag in a SigStatusFlags value you
+ can obtain the respective error code number by substracting
+ the SigStatusFlags value by SigStat_NUMERICAL_CODE: this is
+ used to transport special status information NOT matching
+ any of the normal predefined status codes.
+
+ \note to PlugIn developers: Implementations of the CryptPlug API
+ should try to express their signature states by bit-wise OR'ing
+ the normal SigStatusFlags values. Using the SigStat_NUMERICAL_CODE
+ flag should only be used as for exceptional situations where no
+ other flag(s) could be used. By using the normal status flags your
+ PlugIn's users will be told an understandable description of the
+ status - when using (SigStat_NUMERICAL_CODE + internalCode) they
+ will only be shown the respective code number and have to look
+ into your PlugIn's manual to learn about it's meaning...
+*/
+enum {
+ SigStat_VALID = 0x0001, /* The signature is fully valid */
+ SigStat_GREEN = 0x0002, /* The signature is good. */
+ SigStat_RED = 0x0004, /* The signature is bad. */
+ SigStat_KEY_REVOKED = 0x0010, /* One key has been revoked. */
+ SigStat_KEY_EXPIRED = 0x0020, /* One key has expired. */
+ SigStat_SIG_EXPIRED = 0x0040, /* The signature has expired. */
+ SigStat_KEY_MISSING = 0x0080, /* Can't verify: key missing. */
+ SigStat_CRL_MISSING = 0x0100, /* CRL not available. */
+ SigStat_CRL_TOO_OLD = 0x0200, /* Available CRL is too old. */
+ SigStat_BAD_POLICY = 0x0400, /* A policy was not met. */
+ SigStat_SYS_ERROR = 0x0800, /* A system error occurred. */
+
+ SigStat_NUMERICAL_CODE = 0x8000 /* An other error occurred. */
+};
+typedef unsigned long SigStatusFlags;
+
+class CryptPlugWrapper;
+
+class KDE_EXPORT CryptPlug {
+ friend class CryptPlugWrapper;
+protected:
+ CryptPlug();
+ virtual ~CryptPlug();
+
+ // these must be set by subclasses:
+ gpgme_protocol_t GPGMEPLUG_PROTOCOL;
+ GpgME::Context::Protocol mProtocol;
+
+ /* definitions for signing */
+ // 1. opaque signatures (only used for S/MIME)
+ int GPGMEPLUG_OPA_SIGN_INCLUDE_CLEARTEXT;
+ int GPGMEPLUG_OPA_SIGN_MAKE_MIME_OBJECT;
+ int GPGMEPLUG_OPA_SIGN_MAKE_MULTI_MIME;
+ const char * GPGMEPLUG_OPA_SIGN_CTYPE_MAIN;
+ const char * GPGMEPLUG_OPA_SIGN_CDISP_MAIN;
+ const char * GPGMEPLUG_OPA_SIGN_CTENC_MAIN;
+ const char * GPGMEPLUG_OPA_SIGN_CTYPE_VERSION;
+ const char * GPGMEPLUG_OPA_SIGN_CDISP_VERSION;
+ const char * GPGMEPLUG_OPA_SIGN_CTENC_VERSION;
+ const char * GPGMEPLUG_OPA_SIGN_BTEXT_VERSION;
+ const char * GPGMEPLUG_OPA_SIGN_CTYPE_CODE;
+ const char * GPGMEPLUG_OPA_SIGN_CDISP_CODE;
+ const char * GPGMEPLUG_OPA_SIGN_CTENC_CODE;
+ const char * GPGMEPLUG_OPA_SIGN_FLAT_PREFIX;
+ const char * GPGMEPLUG_OPA_SIGN_FLAT_SEPARATOR;
+ const char * GPGMEPLUG_OPA_SIGN_FLAT_POSTFIX;
+ // 2. detached signatures (used for S/MIME and for OpenPGP)
+ int GPGMEPLUG_DET_SIGN_INCLUDE_CLEARTEXT;
+ int GPGMEPLUG_DET_SIGN_MAKE_MIME_OBJECT;
+ int GPGMEPLUG_DET_SIGN_MAKE_MULTI_MIME;
+ const char * GPGMEPLUG_DET_SIGN_CTYPE_MAIN;
+ const char * GPGMEPLUG_DET_SIGN_CDISP_MAIN;
+ const char * GPGMEPLUG_DET_SIGN_CTENC_MAIN;
+ const char * GPGMEPLUG_DET_SIGN_CTYPE_VERSION;
+ const char * GPGMEPLUG_DET_SIGN_CDISP_VERSION;
+ const char * GPGMEPLUG_DET_SIGN_CTENC_VERSION;
+ const char * GPGMEPLUG_DET_SIGN_BTEXT_VERSION;
+ const char * GPGMEPLUG_DET_SIGN_CTYPE_CODE;
+ const char * GPGMEPLUG_DET_SIGN_CDISP_CODE;
+ const char * GPGMEPLUG_DET_SIGN_CTENC_CODE;
+ const char * GPGMEPLUG_DET_SIGN_FLAT_PREFIX;
+ const char * GPGMEPLUG_DET_SIGN_FLAT_SEPARATOR;
+ const char * GPGMEPLUG_DET_SIGN_FLAT_POSTFIX;
+ // 3. common definitions for opaque and detached signing
+ int __GPGMEPLUG_SIGNATURE_CODE_IS_BINARY;
+
+ /* definitions for encoding */
+ int GPGMEPLUG_ENC_INCLUDE_CLEARTEXT;
+ int GPGMEPLUG_ENC_MAKE_MIME_OBJECT;
+ int GPGMEPLUG_ENC_MAKE_MULTI_MIME;
+ const char * GPGMEPLUG_ENC_CTYPE_MAIN;
+ const char * GPGMEPLUG_ENC_CDISP_MAIN;
+ const char * GPGMEPLUG_ENC_CTENC_MAIN;
+ const char * GPGMEPLUG_ENC_CTYPE_VERSION;
+ const char * GPGMEPLUG_ENC_CDISP_VERSION;
+ const char * GPGMEPLUG_ENC_CTENC_VERSION;
+ const char * GPGMEPLUG_ENC_BTEXT_VERSION;
+ const char * GPGMEPLUG_ENC_CTYPE_CODE;
+ const char * GPGMEPLUG_ENC_CDISP_CODE;
+ const char * GPGMEPLUG_ENC_CTENC_CODE;
+ const char * GPGMEPLUG_ENC_FLAT_PREFIX;
+ const char * GPGMEPLUG_ENC_FLAT_SEPARATOR;
+ const char * GPGMEPLUG_ENC_FLAT_POSTFIX;
+ int __GPGMEPLUG_ENCRYPTED_CODE_IS_BINARY;
+ // end-of(these must be set by subclasses)
+
+public:
+
+#define CRYPTPLUG_CERT_DOES_NEVER_EXPIRE 365000
+#define CRYPTPLUG_ERR_WRONG_KEY_USAGE 0x7070
+
+/*! \ingroup groupGeneral
+ \brief This function sets up all internal structures.
+
+ Plugins that need no initialization should provide an empty
+ implementation. The method returns \c true if the initialization was
+ successful and \c false otherwise. Before this function is called,
+ no other plugin functions should be called; the behavior is
+ undefined in this case.
+
+ \note This function <b>must</b> be implemented by each plug-in using
+ this API specification.
+*/
+bool initialize( void );
+
+/*! \ingroup groupGeneral
+ \brief This function frees all internal structures.
+
+ Plugins that do not keep any internal structures should provide an
+ empty implementation. After this function has been called,
+ no other plugin functions should be called; the behavior is
+ undefined in this case.
+
+ \note This function <b>must</b> be implemented by each plug-in using
+ this API specification.
+*/
+//void deinitialize( void );
+
+/*! \ingroup groupGeneral
+ \brief This function returns \c true if the
+ specified feature is available in the plugin, and
+ \c false otherwise.
+
+ Not all plugins will support all features; a complete Sphinx
+ implementation will support all features contained in the enum,
+ however.
+
+ \note This function <b>must</b> be implemented by each plug-in using
+ this API specification.
+*/
+bool hasFeature( ::Feature );
+
+/*! \ingroup groupSignCryptAct
+ \brief Information record returned by signing and by encrypting
+ functions - this record should be used together with a
+ corresponding \c 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.)
+
+ <b>If</b> value returned in \c makeMimeObject is <b>TRUE</b> the
+ text strings returned in \c contentTypeMain and \c contentDispMain
+ and \c contentTEncMain (and, if required, \c content[..]Version and
+ \c bodyTextVersion and \c content[..]Sig) should be used to compose
+ a respective MIME object.<br>
+ If <b>FALSE</b> the texts returned in \c flatTextPrefix and
+ \c flatTextSeparator and \c flatTextPostfix are to be used instead.<br>
+ Allways <b>either</b> the \c content[..] and \c bodyTextVersion
+ parameters <b>or</b> the \c flatText[..] parameters are holding
+ valid data - never both of them may be used simultaneously
+ as plugins will just ignore the parameters not matching their
+ \c makeMimeObject setting.
+
+ When creating your MIME object please observe these common rules:
+ \li Parameters named \c contentType[..] and \c contentDisp[..] and
+ \c 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:
+ \li The relevant MIME part may <b>only</b> be created if the respective
+ \c contentType[..] parameter is holding a non-zero-length string. If the
+ \c contentType[..] parameter value is invalid or holding an empty string
+ the respective \c contentDisp[..] and \c contentTEnc[..] parameters
+ should be ignored.
+ \li If the respective \c contentDisp[..] or \c 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 <b>not need</b>
+ 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 \c bugURL() function.
+
+ If \c makeMultiMime returns FALSE the \c 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 \c content[..]Version
+ and \c content[..]Code parameters.
+
+ If \c makeMultiMime returns TRUE also the following rules apply:
+ \li If \c 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.
+ \li The \c contentTypeMain returned typically starts with
+ "multipart/" while providing a "protocol" and a "micalg" parameter: just
+ add an appropriate \c "; 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.).
+ \li If \c 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
+ \c contentTypeVersion and (if they are holding non-zero-length strings)
+ \c contentDispVersion and \c contentTEncVersion, the unaltered contents
+ of \c bodyTextVersion must be it's body.
+ \li The value returned in \c 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.
+ \li The same applies to the \c contentDispCode value: just use it's
+ unaltered value to specify the Content-Disposition header entry of
+ the respective MIME part.
+ \li The same applies to the \c contentTEncCode value: just use it's
+ unaltered value to specify the Content-Transfer-Encoding header of
+ the respective MIME part.
+
+ <b>If</b> value returned in \c makeMimeObject is <b>FALSE</b> the
+ text strings returned in \c flatTextPrefix and \c 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.).<br>
+ If \c 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 \c flatTextSeparator - typically this is used for
+ signing but not when encrypting.<br>
+ If \c includeCleartext is FALSE you should ignore both the cleartext
+ and the \c flatTextSeparator parameter.
+
+ <b>How to use StructuringInfo data in your program:</b>
+ \li To compose a signed message please act as described below.
+ \li For constructing an encrypted message just replace the
+ \c signMessage() call by the respective \c encryptMessage() call
+ and then proceed exactly the same way.
+ \li In any case make <b>sure</b> to free your \c ciphertext <b>and</b>
+ to call \c free_StructuringInfo() when you are done with processing
+ the data returned by the signing (or encrypting, resp.) function.
+
+\verbatim
+
+ 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 );
+ }
+
+\endverbatim
+
+ \note Make sure to call \c free_StructuringInfo() when you are done
+ with processing the StructuringInfo data!
+
+ \see free_StructuringInfo
+ \see signMessage, encryptMessage, encryptAndSignMessage
+*/
+struct StructuringInfo {
+ bool 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<br>
+ (this parameter is relevant no matter
+ whether \c makeMimeObject is TRUE or
+ FALSE) */
+ bool makeMimeObject; /*!< specifies whether we should create a MIME
+ object or a flat text message body */
+ /* the following are used for MIME messages only */
+ bool makeMultiMime; /*!< specifies whether we should create a
+ 'Multipart' MIME object or a single part
+ object, if FALSE only \c contentTypeMain,
+ \c contentDispMain and \c contentTEncMain
+ may be used and all other parameters have
+ to be ignored<br>
+ (ignore this parameter if \c makeMimeObject
+ is FALSE) */
+ char* contentTypeMain; /*!< value of the main 'Content-Type'
+ header<br>
+ (ignore this parameter if \c makeMimeObject
+ is FALSE) */
+ char* contentDispMain; /*!< value of the main 'Content-Disposition'
+ header<br>
+ (ignore this parameter if \c makeMimeObject
+ is FALSE) */
+ char* contentTEncMain; /*!< value of the main
+ 'Content-TransferEncoding' header<br>
+ (ignore this parameter if \c makeMimeObject
+ is FALSE) */
+ char* 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<br>
+ (ignore this parameter if either
+ \c makeMimeObject or \c makeMultiMime
+ is FALSE) */
+ char* contentDispVersion; /*!< 'Content-Disposition' of the additional
+ preceeding the code part (only valid if
+ \c contentTypeVersion holds a
+ non-zero-length string)<br>
+ (ignore this parameter if either
+ \c makeMimeObject or \c makeMultiMime
+ is FALSE or if \c contentTypeVersion does
+ not return a non-zero-length string) */
+ char* contentTEncVersion; /*!< 'Content-Transfer-Encoding' of the
+ additional version part (only valid if
+ \c contentTypeVersion holds a
+ non-zero-length string)<br>
+ (ignore this parameter if either
+ \c makeMimeObject or \c makeMultiMime
+ is FALSE or if \c contentTypeVersion does
+ not return a non-zero-length string) */
+ char* bodyTextVersion; /*!< body text of the additional version part
+ (only valid if \c contentTypeVersion
+ holds a non-zero-length string)<br>
+ (ignore this parameter if either
+ \c makeMimeObject or \c makeMultiMime
+ is FALSE or if \c contentTypeVersion does
+ not return a non-zero-length string) */
+ char* contentTypeCode; /*!< 'Content-Type' of the code part holding
+ the signature code (or the encrypted
+ data, resp.)<br>
+ (ignore this parameter if either
+ \c makeMimeObject or \c makeMultiMime
+ is FALSE) */
+ char* contentDispCode; /*!< 'Content-Disposition' of the code part<br>
+ (ignore this parameter if either
+ \c makeMimeObject or \c makeMultiMime
+ is FALSE or if \c contentTypeCode does
+ not return a non-zero-length string) */
+ char* contentTEncCode; /*!< 'Content-Type' of the code part<br>
+ (ignore this parameter if either
+ \c makeMimeObject or \c makeMultiMime
+ is FALSE or if \c contentTypeCode does
+ not return a non-zero-length string) */
+ /* the following are used for flat non-MIME messages only */
+ char* flatTextPrefix; /*!< text to preceed the main text (or the
+ code bloc containing the encrypted main
+ text, resp.)<br>
+ (ignore this parameter if
+ \c makeMimeObject is TRUE) */
+ char* flatTextSeparator; /*!< text to be put between the main text and
+ the signature code bloc (not used when
+ encrypting)<br>
+ (ignore this parameter if
+ \c makeMimeObject is TRUE or if
+ \c includeCleartext is FALSE) */
+ char* flatTextPostfix; /*!< text to follow the signature code bloc
+ (or the encrypted data bloc, resp.)<br>
+ (ignore this parameter if
+ \c makeMimeObject is TRUE) */
+};
+
+
+/*! \ingroup groupAdUsoInterno
+ \brief If you are not planning to write your own cryptography
+ plugin <b>you should ignore this</b> function!
+
+ Usage of this function is depreciated for plugin users but highly
+ recommended for plugin implementors since this is an internal
+ function for initializing all char* members of a \c StructuringInfo
+ struct.<br>
+ This function <b>must</b> be called in <b>any</b> plugin's
+ implementations of the following functions:
+
+ \c signMessage() <br>
+ \c encryptMessage() <br>
+ \c encryptAndSignMessage()
+
+ Calling this function makes sure the corresponding
+ \c free_StructuringInfo() calls which will be embedded by
+ your plugin's users into their code will be able to
+ determine which of the char* members belonging to the
+ respective's StructuringInfo had been allocated memory
+ for during previous signing or encrypting actions.
+
+ \see free_StructuringInfo, StructuringInfo
+ \see signMessage, encryptMessage, encryptAndSignMessage
+*/
+ inline void init_StructuringInfo( struct StructuringInfo* s )
+ {
+ if( ! s ) return;
+
+ s->includeCleartext = false;
+
+ s->makeMimeObject = false;
+ s->makeMultiMime = false;
+
+ s->contentTypeMain = 0;
+ s->contentDispMain = 0;
+ s->contentTEncMain = 0;
+
+ s->contentTypeVersion = 0;
+ s->contentDispVersion = 0;
+ s->contentTEncVersion = 0;
+ s->bodyTextVersion = 0;
+
+ s->contentTypeCode = 0;
+ s->contentDispCode = 0;
+ s->contentTEncCode = 0;
+
+ s->flatTextPrefix = 0;
+ s->flatTextSeparator = 0;
+ s->flatTextPostfix = 0;
+ }
+
+/*! \ingroup groupSignCryptAct
+ \brief Important method for freeing all memory that was allocated
+ for the char* members of a \c StructuringInfo struct - use
+ this function after <b>each</b> signing or encrypting function
+ call.
+
+ \note Even when intending to call \c encryptMessage() immediately
+ after having called \c signMessage() you first <b>must</b> call
+ the \c free_StructuringInfo() function to make sure all memory is
+ set free that was allocated for your StructuringInfo's char* members
+ by the \c signMessage() function!
+
+ \see StructuringInfo
+*/
+ inline void free_StructuringInfo( struct StructuringInfo* s )
+ {
+ if( ! s ) return;
+ if( s->contentTypeMain ) free( s->contentTypeMain );
+ if( s->contentDispMain ) free( s->contentDispMain );
+ if( s->contentTEncMain ) free( s->contentTEncMain );
+ if( s->contentTypeVersion ) free( s->contentTypeVersion );
+ if( s->contentDispVersion ) free( s->contentDispVersion );
+ if( s->contentTEncVersion ) free( s->contentTEncVersion );
+ if( s->bodyTextVersion ) free( s->bodyTextVersion );
+ if( s->contentTypeCode ) free( s->contentTypeCode );
+ if( s->contentDispCode ) free( s->contentDispCode );
+ if( s->contentTEncCode ) free( s->contentTEncCode );
+ if( s->flatTextPrefix ) free( s->flatTextPrefix );
+ if( s->flatTextSeparator ) free( s->flatTextSeparator );
+ if( s->flatTextPostfix ) free( s->flatTextPostfix );
+ }
+
+
+/*! \ingroup groupSignAct
+ */
+struct SignatureMetaDataExtendedInfo
+{
+ struct tm* creation_time;
+ SigStatusFlags sigStatusFlags;
+ char* status_text;
+ char* keyid;
+ char* fingerprint;
+ char* algo;
+ char* userid;
+ char* name;
+ char* comment;
+ char** emailList;
+ int emailCount;
+ unsigned long algo_num;
+ unsigned long validity;
+ unsigned long userid_num;
+ unsigned long keylen;
+ unsigned long key_created;
+ unsigned long key_expires;
+};
+
+/*! \ingroup groupSignAct
+*/
+struct SignatureMetaData {
+ char* status;
+ struct SignatureMetaDataExtendedInfo* extended_info;
+ int extended_info_count;
+ int status_code;
+};
+
+/*! \ingroup groupSignAct
+ \brief Checks whether the signature of a message is
+ valid.
+
+ \c cleartext must never be 0 but be a valid pointer.
+
+ If \c *cleartext > 0 then **cleartext specifies the message text
+ that was signed and \c signaturetext is the signature itself.
+
+ If \c *cleartext == 0 is an empty string then \c signaturetext is
+ supposed to contain an opaque signed message part. After checking the
+ data and verifying the signature the cleartext of the message will be
+ returned in \c cleartext. The user must free the respective memory
+ ocupied by *cleartext.
+
+ Depending on the configuration, MUAs might not need to use this.
+ If \c sigmeta is non-null, the
+ \c SignatureMetaData object pointed to will
+ contain meta information about the signature after the
+ function call.
+*/
+bool checkMessageSignature( char** cleartext,
+ const char* signaturetext,
+ bool signatureIsBinary,
+ int signatureLen,
+ struct SignatureMetaData* sigmeta,
+ char** attrOrder,
+ const char* unknownAttrsHandling );
+
+
+/*! \ingroup groupCryptAct
+ \brief Tries to decrypt an email message
+ \c ciphertext and returns the decrypted
+ message in \c cleartext.
+
+ The \c certificate is used for decryption. If
+ the message could be decrypted, the function returns
+ \c true, otherwise
+ \c false.
+*/
+bool decryptMessage( const char* ciphertext,
+ bool cipherIsBinary,
+ int cipherLen,
+ const char** cleartext,
+ const char* certificate,
+ int* errId,
+ char** errTxt );
+
+/*! \ingroup groupCryptAct
+ \brief Combines the functionality of
+ \c checkMessageSignature() and
+ \c decryptMessage().
+
+ If \c certificate is \c NULL,
+ the default certificate will be used.
+ If \c sigmeta is non-null, the \c SignatureMetaData
+ object pointed to will contain meta information about
+ the signature after the function call.
+*/
+bool decryptAndCheckMessage( const char* ciphertext,
+ bool cipherIsBinary,
+ int cipherLen,
+ const char** cleartext,
+ const char* certificate,
+ bool* signatureFound,
+ struct SignatureMetaData* sigmeta,
+ int* errId,
+ char** errTxt,
+ char** attrOrder,
+ const char* unknownAttrsHandling );
+
+struct DnPair {
+ char *key;
+ char *value;
+};
+
+struct CertificateInfo {
+ char** userid;
+ char* userid_0_org;
+ char* serial;
+ char* fingerprint;
+
+ char* issuer_org;
+ char* issuer_reord;
+ char* chainid;
+
+ char* caps;
+
+ unsigned long created;
+ unsigned long expire;
+
+ int secret : 1;
+ int invalid : 1;
+ int expired : 1;
+ int disabled : 1;
+
+ struct DnPair *dnarray; /* parsed values from userid[0] */
+};
+
+ /*!
+ Import a certificate from memory.
+ */
+ GpgME::ImportResult importCertificateFromMem( const char* data, size_t length );
+}; // class CryptPlug
+
+class SMIMECryptPlug : public CryptPlug {
+public:
+ SMIMECryptPlug();
+};
+
+class OpenPGPCryptPlug : public CryptPlug {
+public:
+ OpenPGPCryptPlug();
+};
+
+#endif /*CRYPTPLUG_H*/
+