TDE personal information management applications
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

840 lines
32 KiB

  1. /**
  2. * cryptplugwrapper.h
  3. *
  4. * Copyright (c) 2001 Karl-Heinz Zimmer, Klaraelvdalens Datakonsult AB
  5. *
  6. * This CRYPTPLUG wrapper interface is based on cryptplug.h by
  7. * Karl-Heinz Zimmer which is based on 'The Aegypten Plugin API' as
  8. * specified by Matthias Kalle Dalheimer, Klaraelvdalens Datakonsult AB,
  9. * see file mua-integration.sgml located on Aegypten CVS:
  10. * http://www.gnupg.org/aegypten/development.en.html
  11. *
  12. * purpose: Wrap up all Aegypten Plugin API functions in one C++ class
  13. * for usage by KDE programs, e.g. KMail (or KMime, resp.)
  14. *
  15. * This program is free software; you can redistribute it and/or modify
  16. * it under the terms of the GNU General Public License as published by
  17. * the Free Software Foundation; version 2 of the License.
  18. *
  19. * This program is distributed in the hope that it will be useful,
  20. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  22. * GNU General Public License for more details.
  23. *
  24. * You should have received a copy of the GNU General Public License
  25. * along with this program; if not, write to the Free Software
  26. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  27. */
  28. #ifndef cryptplugwrapper_h
  29. #define cryptplugwrapper_h
  30. #include "cryptplug.h"
  31. #ifndef LIBKLEOPATRA_NO_COMPAT
  32. /*
  33. *
  34. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  35. * *
  36. * This file's source comments are optimized for processing by Doxygen. *
  37. * *
  38. * To obtain best results please get an updated version of Doxygen, *
  39. * for sources and binaries goto http://www.doxygen.org/index.html *
  40. * *
  41. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  42. *
  43. */
  44. #include "kleo/cryptobackend.h"
  45. #include <tqdatetime.h>
  46. #include <tqvaluelist.h>
  47. #include <tqpair.h>
  48. #include <tqstringlist.h>
  49. #include <tqstring.h>
  50. #include <tdepimmacros.h>
  51. class TDEConfigBase;
  52. class QGpgMECryptoConfig;
  53. namespace GpgME {
  54. class ImportResult;
  55. class KeyGenerationResult;
  56. }
  57. namespace Kleo {
  58. class KeyListJob;
  59. class EncryptJob;
  60. class DecryptJob;
  61. class SignJob;
  62. class VerifyDetachedJob;
  63. class VerifyOpaqueJob;
  64. class KeyGenerationJob;
  65. class ImportJob;
  66. class ExportJob;
  67. class DownloadJob;
  68. class DeleteJob;
  69. class SignEncryptJob;
  70. class DecryptVerifyJob;
  71. class CryptoConfig;
  72. class RefreshKeysJob;
  73. class SpecialJob;
  74. }
  75. /*! \file cryptplugwrapper.h
  76. \brief C++ wrapper for the CRYPTPLUG library API.
  77. This CRYPTPLUG wrapper interface is based on cryptplug.h by
  78. Karl-Heinz Zimmer which is based on 'The Aegypten Plugin API' as
  79. specified by Matthias Kalle Dalheimer, Klaraelvdalens Datakonsult AB,
  80. see file mua-integration.sgml located on Aegypten CVS:
  81. http://www.gnupg.org/aegypten/development.en.html
  82. purpose: Wrap up all Aegypten Plugin API functions in one C++ class
  83. for usage by KDE programs, e.g. KMail (or KMime, resp.)
  84. CRYPTPLUG is an independent cryptography plug-in API
  85. developed for Sphinx-enabeling KMail and Mutt.
  86. CRYPTPLUG was designed for the Aegypten project, but it may
  87. be used by 3rd party developers as well to design pluggable
  88. crypto backends for the above mentioned MUAs.
  89. \note All string parameters appearing in this API are to be
  90. interpreted as UTF-8 encoded.
  91. \see cryptplugwrapper.cpp
  92. */
  93. /*! \defgroup groupAdmin Constructor, destructor and setting of 'active' flag
  94. The functions in this section are used for general administration of
  95. this CRYPTPLUG wrapper class and for maintaining a separate \c active flag
  96. for environments using more than one CRYPTPLUG library simultaneously.
  97. */
  98. /*! \defgroup groupGeneral Loading and Unloading the Plugin, General Functionality
  99. The functions in this section are used for loading and
  100. unloading the respective CRYPTPLUG library, for (re)setting
  101. it's internal data structures and for retrieving information
  102. on the implementation state of all functions covered by the CRYPTPLUG API.
  103. */
  104. /*! \defgroup groupDisplay Graphical Display Functionality
  105. The functions in this section return stationery that the
  106. MUAs can use in order to display security functionality
  107. graphically. This can be toolbar icons, shortcuts, tooltips,
  108. etc. Not all MUAs will use all this functionality.
  109. */
  110. /*! \defgroup groupConfig Configuration Support
  111. The functions in this section provide the necessary
  112. functionality to configure the security functionality as well
  113. as to query configuration settings. Since all configuration
  114. settings will not be saved with the plugin, but rather with
  115. the MUA, there are also functions to set configuration
  116. settings programmatically; these will be used on startup of
  117. the plugin when the MUA transfers the configuration values it
  118. has read into the plugin. Usually, the functions to query and
  119. set the configuration values are not needed for anything but
  120. saving to and restoring from configuration files.
  121. */
  122. /*! \defgroup groupConfigSign Signature Configuration
  123. \ingroup groupConfig
  124. The functions in this section provide the functionality
  125. to configure signature handling and set and query the
  126. signature configuration.
  127. */
  128. /*! \defgroup groupConfigCrypt Encryption Configuration
  129. \ingroup groupConfig
  130. The functions in this section provide the functionality
  131. to configure encryption handling and set and query the
  132. encryption configuration.
  133. \note Whenever the term <b> encryption</b> is used here,
  134. it is supposed to mean both encryption and decryption,
  135. unless otherwise specified.
  136. */
  137. /*! \defgroup groupConfigDir Directory Service Configuration
  138. \ingroup groupConfig
  139. This section contains messages for configuring the
  140. directory service.
  141. */
  142. /*! \defgroup groupCertHand Certificate Handling
  143. The following methods are used to maintain and query certificates.
  144. */
  145. /*! \defgroup groupSignCryptAct Signing and Encrypting Actions
  146. This section describes methods and structures
  147. used for signing and/or encrypting your mails.
  148. */
  149. /*! \defgroup groupSignAct Signature Actions
  150. \ingroup groupSignCryptAct
  151. This section describes methods that are used for working
  152. with signatures.
  153. */
  154. /*! \defgroup groupCryptAct Encryption and Decryption
  155. \ingroup groupSignCryptAct
  156. The following methods are used to encrypt and decrypt
  157. email messages.
  158. */
  159. /*! \defgroup groupCertAct Certificate Handling Actions
  160. The functions in this section provide local certificate management.
  161. */
  162. /*! \defgroup groupCRLAct CRL Handling Actions
  163. This section describes functions for managing CRLs.
  164. */
  165. /*! \defgroup groupAdUsoInterno Important functions to be used by plugin implementors ONLY.
  166. This section describes functions that have to be used by
  167. plugin implementors but should not be used by plugin users
  168. directly.
  169. If you are not planning to write your own cryptography
  170. plugin <b>you should ignore this</b> section!
  171. */
  172. class CryptPlugWrapper;
  173. /*! \ingroup groupSignCryptAct
  174. \brief This class provides C++ access to the StructuringInfo helper
  175. struct that is specified in cryptplug.h to hold information
  176. returned by signing and by encrypting functions.
  177. Use this information to compose a MIME object containing signed
  178. and/or encrypted content (or to build a text frame around your
  179. flat non-MIME message body, resp.)
  180. \note This class is different from the respective cryptplug.h class
  181. because this one takes care for freeing the char** members' memory
  182. automatically. You must <b>not</b> call the \c free function for
  183. any of it's members - just ignore the advise given in the
  184. cryptplug.h documentation!
  185. <b>If</b> value returned in \c makeMimeObject is <b>TRUE</b> the
  186. text strings returned in \c contentTypeMain and \c contentDispMain
  187. and \c contentTEncMain (and, if required, \c content[..]Version and
  188. \c bodyTextVersion and \c content[..]Sig) should be used to compose
  189. a respective MIME object.<br>
  190. If <b>FALSE</b> the texts returned in \c flatTextPrefix and
  191. \c flatTextSeparator and \c flatTextPostfix are to be used instead.<br>
  192. Always <b>either</b> the \c content[..] and \c bodyTextVersion
  193. parameters <b>or</b> the \c flatText[..] parameters are holding
  194. valid data - never both of them may be used simultaneously
  195. as plugins will just ignore the parameters not matching their
  196. \c makeMimeObject setting.
  197. When creating your MIME object please observe these common rules:
  198. \li Parameters named \c contentType[..] and \c contentDisp[..] and
  199. \c contentTEnc[..] will return the values for the respective MIME
  200. headers 'Content-Type' and 'Content-Disposition' and
  201. 'Content-Transfer-Encoding'. The following applies to these parameters:
  202. \li The relevant MIME part may <b>only</b> be created if the respective
  203. \c contentType[..] parameter is holding a non-zero-length string. If the
  204. \c contentType[..] parameter value is invalid or holding an empty string
  205. the respective \c contentDisp[..] and \c contentTEnc[..] parameters
  206. should be ignored.
  207. \li If the respective \c contentDisp[..] or \c contentTEnc[..] parameter
  208. is NULL or holding a zero-length string it is up to you whether you want
  209. to add the relevant MIME header yourself, but since it in in the
  210. responsibility of the plugin implementors to provide you with all
  211. necessary 'Content-[..]' header information you should <b>not need</b>
  212. to define them if they are not returned by the signing or encrypting
  213. function - otherwise this may be considered as a bug in the plugin and
  214. you could report the missing MIME header information to the address
  215. returned by the \c bugURL() function.
  216. If \c makeMultiMime returns FALSE the \c contentTypeMain returned must
  217. not be altered but used to specify a single part mime object holding the
  218. code bloc, e.g. this is used for 'enveloped-data' single part MIME
  219. objects. In this case you should ignore both the \c content[..]Version
  220. and \c content[..]Code parameters.
  221. If \c makeMultiMime returns TRUE also the following rules apply:
  222. \li If \c includeCleartext is TRUE you should include the cleartext
  223. as first part of our multipart MIME object, typically this is TRUE
  224. when signing mails but FALSE when encrypting.
  225. \li The \c contentTypeMain returned typically starts with
  226. "multipart/" while providing a "protocol" and a "micalg" parameter: just
  227. add an appropriate \c "; boundary=[your \c boundary \c string]" to get
  228. the complete Content-Type value to be used for the MIME object embedding
  229. both the signed part and the signature part (or - in case of
  230. encrypting - the version part and the code part, resp.).
  231. \li If \c contentTypeVersion is holding a non-zero-length string an
  232. additional MIME part must added immediately before the code part, this
  233. version part's MIME headers must have the unaltered values of
  234. \c contentTypeVersion and (if they are holding non-zero-length strings)
  235. \c contentDispVersion and \c contentTEncVersion, the unaltered contents
  236. of \c bodyTextVersion must be it's body.
  237. \li The value returned in \c contentTypeCode is specifying the complete
  238. Content-Type to be used for this multipart MIME object's signature part
  239. (or - in case of encrypting - for the code part following after the
  240. version part, resp.), you should not add/change/remove anything here
  241. but just use it's unaltered value for specifying the Content-Type header
  242. of the respective MIME part.
  243. \li The same applies to the \c contentDispCode value: just use it's
  244. unaltered value to specify the Content-Disposition header entry of
  245. the respective MIME part.
  246. \li The same applies to the \c contentTEncCode value: just use it's
  247. unaltered value to specify the Content-Transfer-Encoding header of
  248. the respective MIME part.
  249. <b>If</b> value returned in \c makeMimeObject is <b>FALSE</b> the
  250. text strings returned in \c flatTextPrefix and \c flatTextPostfix
  251. should be used to build a frame around the cleartext and the code
  252. bloc holding the signature (or - in case of encrypting - the encoded
  253. data bloc, resp.).<br>
  254. If \c includeCleartext is TRUE this frame should also include the
  255. cleartext as first bloc, this bloc should be divided from the code bloc
  256. by the contents of \c flatTextSeparator - typically this is used for
  257. signing but not when encrypting.<br>
  258. If \c includeCleartext is FALSE you should ignore both the cleartext
  259. and the \c flatTextSeparator parameter.
  260. <b>How to use StructuringInfoWrapper data in your program:</b>
  261. \li To compose a signed message please act as described below.
  262. \li For constructing an encrypted message just replace the
  263. \c signMessage() call by the respective \c encryptMessage() call
  264. and then proceed exactly the same way.
  265. \li In any case make <b>sure</b> to free your \c ciphertext when
  266. you are done with processing the data returned by the signing
  267. (or encrypting, resp.) function.
  268. \verbatim
  269. char* ciphertext;
  270. StructuringInfoWrapper structInf;
  271. if( ! signMessage( cleartext, &ciphertext, certificate,
  272. structInf ) ) {
  273. myErrorDialog( "Error: could not sign the message!" );
  274. } else {
  275. if( structInf.data.makeMimeObject ) {
  276. // Build the main MIME object.
  277. // This is done by
  278. // using the header values returned in
  279. // structInf.data.contentTypeMain and in
  280. // structInf.data.contentDispMain and in
  281. // structInf.data.contentTEncMain.
  282. ..
  283. if( ! structInf.data.makeMultiMime ) {
  284. // Build the main MIME object's body.
  285. // This is done by
  286. // using the code bloc returned in
  287. // ciphertext.
  288. ..
  289. } else {
  290. // Build the encapsulated MIME parts.
  291. if( structInf.data.includeCleartext ) {
  292. // Build a MIME part holding the cleartext.
  293. // This is done by
  294. // using the original cleartext's headers and by
  295. // taking it's original body text.
  296. ..
  297. }
  298. if( structInf.data.contentTypeVersion
  299. && 0 < strlen( structInf.data.contentTypeVersion ) ) {
  300. // Build a MIME part holding the version information.
  301. // This is done by
  302. // using the header values returned in
  303. // structInf.data.contentTypeVersion and
  304. // structInf.data.contentDispVersion and
  305. // structInf.data.contentTEncVersion and by
  306. // taking the body contents returned in
  307. // structInf.data.bodyTextVersion.
  308. ..
  309. }
  310. if( structInf.data.contentTypeCode
  311. && 0 < strlen( structInf.data.contentTypeCode ) ) {
  312. // Build a MIME part holding the code information.
  313. // This is done by
  314. // using the header values returned in
  315. // structInf.data.contentTypeCode and
  316. // structInf.data.contentDispCode and
  317. // structInf.data.contentTEncCode and by
  318. // taking the body contents returned in
  319. // ciphertext.
  320. ..
  321. } else {
  322. // Plugin error!
  323. myErrorDialog( "Error: Cryptography plugin returned a main"
  324. "Content-Type=Multipart/.. but did not "
  325. "specify the code bloc's Content-Type header."
  326. "\nYou may report this bug:"
  327. "\n" + cryptplug.bugURL() );
  328. }
  329. }
  330. } else {
  331. // Build a plain message body
  332. // based on the values returned in structInf.
  333. // Note: We do _not_ insert line breaks between the parts since
  334. // it is the plugin job to provide us with ready-to-use
  335. // texts containing all necessary line breaks.
  336. strcpy( myMessageBody, structInf.data.plainTextPrefix );
  337. if( structInf.data.includeCleartext ) {
  338. strcat( myMessageBody, cleartext );
  339. strcat( myMessageBody, structInf.data.plainTextSeparator );
  340. }
  341. strcat( myMessageBody, *ciphertext );
  342. strcat( myMessageBody, structInf.data.plainTextPostfix );
  343. }
  344. // free the memory that was allocated
  345. // for the ciphertext
  346. free( ciphertext );
  347. }
  348. \endverbatim
  349. \see signMessage, encryptMessage, encryptAndSignMessage
  350. */
  351. class StructuringInfoWrapper {
  352. public:
  353. StructuringInfoWrapper( CryptPlugWrapper* wrapper );
  354. ~StructuringInfoWrapper();
  355. void reset();
  356. CryptPlug::StructuringInfo data;
  357. private:
  358. void initMe();
  359. void freeMe();
  360. bool _initDone;
  361. CryptPlugWrapper* _wrapper;
  362. };
  363. /*!
  364. \brief This class provides C++ access to the CRYPTPLUG API.
  365. */
  366. class KDE_EXPORT CryptPlugWrapper : public Kleo::CryptoBackend::Protocol {
  367. public:
  368. static TQString errorIdToText( int errId, bool & isPassphraseError );
  369. /*! \ingroup groupGeneral
  370. \brief Current initialization state.
  371. This flag holding status of previous call of initialize function.
  372. If initialize was not called before return value will be
  373. \c CryptPlugInit_undef.
  374. \sa iniStatus, initialize
  375. */
  376. typedef enum {
  377. IniStatus_undef = 0,
  378. IniStatus_Ok = 1,
  379. IniStatus_NoLibName = 2,
  380. IniStatus_LoadError = 0x1000,
  381. IniStatus_InitError = 0x2000
  382. } IniStatus;
  383. /*! \ingroup groupSignAct
  384. \brief Flags used to compose the SigStatusFlags value.
  385. This status flags are used to compose the SigStatusFlags value
  386. returned in \c SignatureMetaDataExtendedInfo after trying to
  387. verify a signed message part's signature status.
  388. The normal flags may <b>not</b> be used together with the
  389. special SigStatus_NUMERICAL_CODE flag. When finding the special
  390. SigStatus_NUMERICAL_CODE flag in a SigStatusFlags value you
  391. can obtain the respective error code number by substracting
  392. the SigStatusFlags value by SigStatus_NUMERICAL_CODE: this is
  393. used to transport special status information NOT matching
  394. any of the normal predefined status codes.
  395. \note to PlugIn developers: Implementations of the CryptPlug API
  396. should try to express their signature states by bit-wise OR'ing
  397. the normal SigStatusFlags values. Using the SigStatus_NUMERICAL_CODE
  398. flag should only be used as for exceptional situations where no
  399. other flag(s) could be used. By using the normal status flags your
  400. PlugIn's users will be told an understandable description of the
  401. status - when using (SigStatus_NUMERICAL_CODE + internalCode) they
  402. will only be shown the respective code number and have to look
  403. into your PlugIn's manual to learn about it's meaning...
  404. */
  405. enum {
  406. SigStatus_UNKNOWN = 0x0000,
  407. SigStatus_VALID = SigStat_VALID,
  408. SigStatus_GREEN = SigStat_GREEN,
  409. SigStatus_RED = SigStat_RED,
  410. SigStatus_KEY_REVOKED = SigStat_KEY_REVOKED,
  411. SigStatus_KEY_EXPIRED = SigStat_KEY_EXPIRED,
  412. SigStatus_SIG_EXPIRED = SigStat_SIG_EXPIRED,
  413. SigStatus_KEY_MISSING = SigStat_KEY_MISSING,
  414. SigStatus_CRL_MISSING = SigStat_CRL_MISSING,
  415. SigStatus_CRL_TOO_OLD = SigStat_CRL_TOO_OLD,
  416. SigStatus_BAD_POLICY = SigStat_BAD_POLICY,
  417. SigStatus_SYS_ERROR = SigStat_SYS_ERROR,
  418. SigStatus_NUMERICAL_CODE = 0x8000 /* An other error occurred. */
  419. };
  420. typedef unsigned long SigStatusFlags;
  421. enum {
  422. CerStatus_EXPIRES_NEVER = CRYPTPLUG_CERT_DOES_NEVER_EXPIRE
  423. };
  424. /*! \ingroup groupAdmin
  425. \brief Constructor of CRYPTPLUG wrapper class.
  426. This constructor does <b>not</b> call the initialize() method
  427. but just stores some information for later use.
  428. \note Since more than one crypto plug-in might be specified (using
  429. multiple instances of the warpper class) it is necessary to
  430. set \c active at least one them. Only wrappers that have been
  431. activated may be initialized or configured or used to perform
  432. crypto actions.
  433. \param name The external name that is visible in lists, messages,
  434. etc.
  435. \param libName Complete path+name of CRYPTPLUG library that is to
  436. be used by this instance of CryptPlugWrapper.
  437. \param update the URL from where updates can be downloaded
  438. \param active Specify whether the relative library is to be used
  439. or not.
  440. \sa ~CryptPlugWrapper, setActive, active, initialize, deinitialize
  441. \sa iniStatus
  442. */
  443. CryptPlugWrapper( const TQString& name=TQString(),
  444. const TQString& libName=TQString(),
  445. const TQString& update=TQString(),
  446. bool active = false );
  447. /*! \ingroup groupAdmin
  448. \brief Destructor of CRYPTPLUG wrapper class.
  449. This destructor <b>does</b> call the deinitialize() method in case
  450. this was not done by explicitly calling it before.
  451. \sa deinitialize, initialize, CryptPlugWrapper(), setActive, active
  452. \sa
  453. */
  454. ~CryptPlugWrapper();
  455. TQString protocol() const;
  456. TQString name() const {
  457. return protocol();
  458. }
  459. /*! \ingroup groupAdmin
  460. \brief Set this CRYPTPLUG wrapper's internal \c active flag.
  461. Since more than one crypto plug-in might be specified (using
  462. multiple instances of the warpper class) it is necessary to
  463. set \c active at least one them. Only wrappers that have been
  464. activated may be initialized or configured or used to perform
  465. crypto actions.
  466. This flag may be set in the constructor or by calling setActive().
  467. \note Deactivating does <b>not</b> mean resetting the internal
  468. structures - if just prevents the normal functions from
  469. being called erroneously. When deactivated only the following
  470. functions are operational: constructor , destructor ,
  471. setActive , active, setLibName , libName , iniStatus;
  472. calling other functions will be ignored and their return
  473. values will be undefined.
  474. \param active Specify whether the relative library is to be used
  475. or not.
  476. \sa active, CryptPlugWrapper(), ~CryptPlugWrapper
  477. \sa deinitialize, initialize, iniStatus
  478. */
  479. void setActive( bool active );
  480. /*! \ingroup groupAdmin
  481. \brief Returns this CRYPTPLUG wrapper's internal \c active flag.
  482. \return whether the relative library is to be used or not.
  483. \sa setActive
  484. */
  485. bool active() const;
  486. /*! \ingroup groupAdmin
  487. \brief Set the CRYPTPLUG library name.
  488. Complete path+name of CRYPTPLUG library that is to
  489. be used by this instance of CryptPlugWrapper.
  490. This name may be set in the constructor or by calling setLibName().
  491. \note Setting/changing the library name may only be done when
  492. the iniStatus() is <b>not</b> \c IniStatus_Ok.
  493. If you want to change the name of the library after
  494. successfully having called initialize() please make
  495. sure to unload it by calling the deinitialize() function.
  496. \param libName libName Complete path+name of CRYPTPLUG library
  497. that is to be used by this CryptPlugWrapper.
  498. \return whether the library name could be changed; library name
  499. can only be changed when library is not initialized - see
  500. above 'note'.
  501. \sa libName, CryptPlugWrapper(), ~CryptPlugWrapper
  502. \sa deinitialize, initialize, iniStatus
  503. */
  504. bool setLibName( const TQString& libName );
  505. /*! \ingroup groupAdmin
  506. \brief Returns the CRYPTPLUG library name.
  507. \return the complete path+name of CRYPTPLUG library that is to
  508. be used by this instance of CryptPlugWrapper.
  509. \sa setLibName
  510. */
  511. TQString libName() const;
  512. /*! \ingroup groupAdmin
  513. \brief Specifies the external name that is visible in lists,
  514. messages, etc.
  515. */
  516. void setDisplayName( const TQString& name );
  517. /*! \ingroup groupAdmin
  518. \brief Returns the external name.
  519. \return the external name used for display purposes
  520. */
  521. TQString displayName() const;
  522. private:
  523. /*! \ingroup groupGeneral
  524. \brief This function does two things: (a) load the lib and (b) set up all internal structures.
  525. The method tries to load the CRYPTPLUG library specified
  526. in the constructor and returns \c true if the both <b>loading
  527. and initializing</b> the internal data structures was successful
  528. and \c false otherwise. Before this function is called,
  529. no other plugin functions should be called; the behavior is
  530. undefined in this case, this rule does not apply to the functions
  531. \c setActive() and \c setLibName().
  532. \param iniStatus will receive the resulting IniStatus if not NULL
  533. \param errorMsg will receive the system error message if not NULL
  534. \sa iniStatus, deinitialize, CryptPlugWrapper(), ~CryptPlugWrapper
  535. \sa setActive, active
  536. */
  537. bool initialize( IniStatus* iniStatus, TQString* errorMsg );
  538. public:
  539. /*! \ingroup groupGeneral
  540. \brief This function unloads the lib and frees all internal structures.
  541. After this function has been called, no other plugin functions
  542. should be called; the behavior is undefined in this case.
  543. \note Deinitializing sets the internal iniStatus value back
  544. to \c IniStatus_undef.
  545. \sa iniStatus, initialize, CryptPlugWrapper, ~CryptPlugWrapper
  546. \sa setActive, active
  547. */
  548. void deinitialize();
  549. /*! \ingroup groupGeneral
  550. \brief Returns this CRYPTPLUG wrapper's initialization state.
  551. \param errorMsg receives the last system error message, this value
  552. should be ignored if IniStatus value equals \c IniStatus_Ok.
  553. \return whether the relative library was loaded and initialized
  554. correctly
  555. \sa initialize, deinitialize, CryptPlugWrapper(), ~CryptPlugWrapper
  556. \sa setActive, active
  557. */
  558. IniStatus iniStatus( TQString* errorMsg ) const;
  559. /*! \ingroup groupGeneral
  560. \brief This function returns \c true if the
  561. specified feature is available in the plugin, and
  562. \c false otherwise.
  563. Not all plugins will support all features; a complete Sphinx
  564. implementation will support all features contained in the enum,
  565. however.
  566. \note In case this function cannot be executed the system's error
  567. message may be retrieved by calling iniStatus( TQString* ).
  568. \return whether the relative feature is implemented or not
  569. */
  570. bool hasFeature( ::Feature );
  571. /* \ingroup groupSignAct
  572. * Frees the members of a signature meta data struct, but not the
  573. * signature meta data struct itself as this could be allocated on
  574. * the stack.
  575. */
  576. void freeSignatureMetaData( CryptPlug::SignatureMetaData* );
  577. /*! \ingroup groupSignAct
  578. \brief Checks whether the signature of a message is
  579. valid.
  580. \c cleartext must never be 0 but be a valid pointer.
  581. If \c *cleartext > 0 then **cleartext specifies the message text
  582. that was signed and \c signaturetext is the signature itself.
  583. If \c *cleartext == 0 is an empty string then \c signaturetext is
  584. supposed to contain an opaque signed message part. After checking the
  585. data and verifying the signature the cleartext of the message will be
  586. returned in \c cleartext. The user must free the respective memory
  587. occupied by *cleartext.
  588. Depending on the configuration, MUAs might not need to use this.
  589. If \c sigmeta is non-null, the
  590. \c SignatureMetaData object pointed to will
  591. contain meta information about the signature after the
  592. function call.
  593. */
  594. bool checkMessageSignature( char** cleartext,
  595. const char* signaturetext,
  596. bool signatureIsBinary,
  597. int signatureLen,
  598. CryptPlug::SignatureMetaData* sigmeta );
  599. /*! \ingroup groupCryptAct
  600. \brief Tries to decrypt an email message
  601. \c ciphertext and returns the decrypted
  602. message in \c cleartext.
  603. The \c certificate is used for decryption. If
  604. the message could be decrypted, the function returns
  605. \c true, otherwise
  606. \c false.
  607. */
  608. bool decryptMessage( const char* ciphertext,
  609. bool cipherIsBinary,
  610. int cipherLen,
  611. char** cleartext,
  612. const char* certificate,
  613. int* errId,
  614. char** errTxt );
  615. /*! \ingroup groupCryptAct
  616. \brief Combines the functionality of
  617. \c checkMessageSignature() and
  618. \c decryptMessage().
  619. If \c certificate is \c NULL,
  620. the default certificate will be used. If
  621. \c sigmeta is non-null, the
  622. \c SignatureMetaData object pointed to will
  623. contain meta information about the signature after the
  624. function call.
  625. */
  626. bool decryptAndCheckMessage( const char* ciphertext,
  627. bool cipherIsBinary,
  628. int cipherLen,
  629. char** cleartext,
  630. const char* certificate,
  631. bool* signatureFound,
  632. CryptPlug::SignatureMetaData* sigmeta,
  633. int* errId,
  634. char** errTxt );
  635. Kleo::KeyListJob * keyListJob( bool remote=false, bool includeSigs=false, bool validate=true ) const;
  636. Kleo::EncryptJob * encryptJob( bool armor=false, bool textmode=false ) const;
  637. Kleo::DecryptJob * decryptJob() const;
  638. Kleo::SignJob * signJob( bool armor=false, bool textMode=false ) const;
  639. Kleo::VerifyDetachedJob * verifyDetachedJob( bool textmode=false) const;
  640. Kleo::VerifyOpaqueJob * verifyOpaqueJob( bool textmode=false ) const;
  641. Kleo::KeyGenerationJob * keyGenerationJob() const;
  642. Kleo::ImportJob * importJob() const;
  643. Kleo::ExportJob * publicKeyExportJob( bool armor=false ) const;
  644. Kleo::ExportJob * secretKeyExportJob( bool armor=false, const TQString& charset = TQString() ) const;
  645. Kleo::DownloadJob * downloadJob( bool armor=false ) const;
  646. Kleo::DeleteJob * deleteJob() const;
  647. Kleo::SignEncryptJob * signEncryptJob( bool armor=false, bool textmode=false ) const;
  648. Kleo::DecryptVerifyJob * decryptVerifyJob( bool textmode=false ) const;
  649. Kleo::RefreshKeysJob * refreshKeysJob() const;
  650. Kleo::SpecialJob * specialJob( const char *, const TQStringVariantMap & ) const { return 0; }
  651. GpgME::ImportResult importCertificate( const char* data, size_t length );
  652. CryptPlug * cryptPlug() const { return _cp; }
  653. private:
  654. TQString _name;
  655. TQString _libName;
  656. TQString _updateURL;
  657. bool _active;
  658. IniStatus _iniStatus;
  659. TQString _lastError;
  660. CryptPlug* _cp;
  661. // local parameters without representation in cryptplug.h
  662. bool mAlwaysEncryptToSelf;
  663. class Config;
  664. Config * _config;
  665. QGpgMECryptoConfig * _cryptoConfig;
  666. };
  667. #endif // !LIBKLEOPATRA_NO_COMPAT
  668. #endif // cryptplugwrapper_h