Fix typo.
[gpgme.git] / gpgmeplug / cryptplug.h
1 /* -*- Mode: C -*-
2
3   $Id$
4
5   CRYPTPLUG - an independent cryptography plug-in API
6
7   Copyright (C) 2001 by Klarälvdalens Datakonsult AB
8
9   CRYPTPLUG is free software; you can redistribute it and/or modify
10   it under the terms of GNU General Public License as published by
11   the Free Software Foundation; version 2 of the License.
12
13   CRYPTPLUG is distributed in the hope that it will be useful,
14   but WITHOUT ANY WARRANTY; without even the implied warranty of
15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16   GNU General Public License for more details.
17
18   You should have received a copy of the GNU General Public License
19   along with this program; if not, write to the Free Software
20   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
21 */
22
23 #ifndef CRYPTPLUG_H
24 #define CRYPTPLUG_H
25
26 #ifdef __cplusplus
27 extern "C" {
28 #else
29 typedef char bool;
30 #define true 1
31 #define false 0
32 #endif
33
34 #include <stdlib.h>
35 //#include <string.h>
36 //#include <ctype.h>
37
38
39 /*! \file cryptplug.h
40     \brief Common API header for CRYPTPLUG.
41
42     CRYPTPLUG is an independent cryptography plug-in API
43     developed for Sphinx-enabeling KMail and Mutt.
44
45     CRYPTPLUG was designed for the Aegypten project, but it may
46     be used by 3rd party developers as well to design pluggable
47     crypto backends for the above mentioned MUAs.
48
49     \note All string parameters appearing in this API are to be
50     interpreted as UTF-8 encoded.
51
52     \see pgpplugin.c
53     \see gpgplugin.c
54 */
55
56 /*! \defgroup groupGeneral Loading and Unloading the Plugin, General Functionality
57
58     The functions in this section are used for loading and
59     unloading plugins. Note that the actual locating of the plugin
60     and the loading and unloading of the dynamic library is not
61     covered here; this is MUA-specific code for which support code
62     might already exist in the programming environments.
63 */
64
65 /*! \defgroup groupDisplay Graphical Display Functionality
66
67     The functions in this section return stationery that the
68     MUAs can use in order to display security functionality
69     graphically. This can be toolbar icons, shortcuts, tooltips,
70     etc. Not all MUAs will use all this functionality.
71 */
72
73 /*! \defgroup groupConfig Configuration Support
74
75     The functions in this section provide the necessary
76     functionality to configure the security functionality as well
77     as to query configuration settings. Since all configuration
78     settings will not be saved with the plugin, but rather with
79     the MUA, there are also functions to set configuration
80     settings programmatically; these will be used on startup of
81     the plugin when the MUA transfers the configuration values it
82     has read into the plugin. Usually, the functions to query and
83     set the configuration values are not needed for anything but
84     saving to and restoring from configuration files.
85 */
86
87
88 /*! \defgroup groupConfigSign Signature Configuration
89     \ingroup groupConfig
90
91     The functions in this section provide the functionality
92     to configure signature handling and set and query the
93     signature configuration.
94 */
95
96 /*! \defgroup groupConfigCrypt Encryption Configuration
97     \ingroup groupConfig
98
99     The functions in this section provide the functionality
100     to configure encryption handling and set and query the
101     encryption configuration.
102
103     \note Whenever the term <b> encryption</b> is used here,
104     it is supposed to mean both encryption and decryption,
105     unless otherwise specified.
106 */
107
108 /*! \defgroup groupConfigDir Directory Service Configuration
109     \ingroup groupConfig
110
111     This section contains messages for configuring the
112     directory service.
113 */
114
115
116 /*! \defgroup groupCertHand Certificate Handling
117
118     The following methods are used to maintain and query certificates.
119 */
120
121
122 /*! \defgroup groupSignCryptAct Signing and Encrypting Actions
123
124     This section describes methods and structures
125     used for signing and/or encrypting your mails.
126 */
127
128
129 /*! \defgroup groupSignAct Signature Actions
130     \ingroup groupSignCryptAct
131
132     This section describes methods that are used for working
133     with signatures.
134 */
135
136 /*! \defgroup groupCryptAct Encryption and Decryption
137     \ingroup groupSignCryptAct
138
139     The following methods are used to encrypt and decrypt
140     email messages.
141 */
142
143 /*! \defgroup groupCertAct Certificate Handling Actions
144
145     The functions in this section provide local certificate management.
146 */
147
148 /*! \defgroup groupCRLAct CRL Handling Actions
149
150     This section describes functions for managing CRLs.
151 */
152
153 /*! \defgroup groupAdUsoInterno Important functions to be used by plugin implementors ONLY.
154
155     This section describes functions that have to be used by
156     plugin implementors but should not be used by plugin users
157     directly.
158
159     If you are not planning to write your own cryptography
160     plugin <b>you should ignore this</b> section!
161 */
162
163
164 // dummy values:
165 typedef enum {
166   CryptPlugFeat_undef             = 0,
167
168   CryptPlugFeat_SignMessages      = 1,
169   CryptPlugFeat_VerifySignatures  = 2,
170   CryptPlugFeat_EncryptMessages   = 3,
171   CryptPlugFeat_DecryptMessages   = 4   // more to follow ...
172 } Feature;
173
174 // dummy values
175 typedef enum {
176   PinRequest_undef            = 0,
177
178   PinRequest_Always          = 1,
179   PinRequest_WhenAddingCerts = 2,
180   PinRequest_AlwaysWhenSigning = 3,
181   PinRequest_OncePerSession   = 4,
182   PinRequest_AfterMinutes     = 5
183 } PinRequests;
184
185 // dummy values:
186 typedef enum {
187   SendCert_undef              = 0,
188
189   SendCert_DontSend           = 1,
190   SendCert_SendOwn            = 2,
191   SendCert_SendChainWithoutRoot = 3,
192   SendCert_SendChainWithRoot  = 4
193 } SendCertificates;
194
195 // dummy values:
196 typedef enum {
197   SignAlg_undef               = 0,
198
199   SignAlg_SHA1                = 1
200 } SignatureAlgorithm;
201
202
203
204 typedef enum {
205   EncryptAlg_undef            = 0,
206
207   EncryptAlg_RSA              = 1,
208   EncryptAlg_SHA1             = 2,
209   EncryptAlg_TripleDES        = 3
210 } EncryptionAlgorithm;
211
212 typedef enum {
213   SignEmail_undef             = 0,
214
215   SignEmail_SignAll           = 1,
216   SignEmail_Ask               = 2,
217   SignEmail_DontSign          = 3
218 } SignEmail;
219
220 typedef enum {
221   EncryptEmail_undef          = 0,
222
223   EncryptEmail_EncryptAll     = 1,
224   EncryptEmail_Ask            = 2,
225   EncryptEmail_DontEncrypt    = 3
226 } EncryptEmail;
227
228 typedef enum {
229   CertSrc_undef               = 0,
230
231   CertSrc_Server              = 1,
232   CertSrc_Local               = 2,
233   CertSrc_ServerLocal         = CertSrc_Server | CertSrc_Local
234 } CertificateSource;
235
236
237
238
239
240
241 /*! \ingroup groupGeneral
242     \brief This function returns a URL to be used for reporting a bug that
243            you found (or suspect, resp.) in this cryptography plug-in.
244
245    If the plugins for some reason cannot specify an appropriate URL you
246    should at least be provided with a text giving you some advise on
247    how to report a bug.
248
249    \note This function <b>must</b> be implemented by each plug-in using
250    this API specification.
251 */
252 const char* bugURL( void );
253
254 /*! \ingroup groupGeneral
255     \brief This function sets up all internal structures.
256
257    Plugins that need no initialization should provide an empty
258    implementation. The method returns \c true if the initialization was
259    successful and \c false otherwise. Before this function is called,
260    no other plugin functions should be called; the behavior is
261    undefined in this case.
262
263    \note This function <b>must</b> be implemented by each plug-in using
264    this API specification.
265 */
266 bool initialize( void );
267
268 /*! \ingroup groupGeneral
269     \brief This function frees all internal structures.
270
271     Plugins that do not keep any internal structures should provide an
272     empty implementation. After this function has been called,
273     no other plugin functions should be called; the behavior is
274     undefined in this case.
275
276    \note This function <b>must</b> be implemented by each plug-in using
277    this API specification.
278 */
279 void deinitialize( void );
280
281 /*! \ingroup groupGeneral
282    \brief This function returns \c true if the
283           specified feature is available in the plugin, and
284           \c false otherwise.
285
286    Not all plugins will support all features; a complete Sphinx
287    implementation will support all features contained in the enum,
288    however.
289
290    \note This function <b>must</b> be implemented by each plug-in using
291    this API specification.
292 */
293 bool hasFeature( Feature );
294
295
296 /*! \ingroup groupDisplay
297    \brief Returns stationery to indicate unsafe emails.
298 */
299 void unsafeStationery( void** pixmap, const char** menutext, char* accel,
300           const char** tooltip, const char** statusbartext );
301
302 /*! \ingroup groupDisplay
303    \brief Returns stationery to indicate signed emails.
304 */
305 void signedStationery( void** pixmap, const char** menutext, char* accel,
306           const char** tooltip, const char** statusbartext );
307
308 /*! \ingroup groupDisplay
309    \brief Returns stationery to indicate encrypted emails.
310 */
311 void encryptedStationery( void** pixmap, const char**
312           menutext, char* accel,
313           const char** tooltip, const char** statusbartext );
314
315 /*! \ingroup groupDisplay
316    \brief Returns stationery to indicate signed and encrypted emails.
317 */
318 void signedEncryptedStationery( void** pixmap, const char**
319           menutext, char* accel,
320           const char** tooltip, const char** statusbartext );
321
322 /*! \ingroup groupConfigSign
323    \brief This function returns an XML representation of a
324             configuration dialog for configuring signature
325             handling.
326             
327    The syntax is that of <filename>.ui</filename>
328             files as specified in the <emphasis>Imhotep</emphasis>
329             documentation. This function does not execute or show the
330             dialog in any way; this is up to the MUA. Also, what the
331             MUA makes of the information provided highly depends on
332             the MUA itself. A GUI-based MUA will probably create a
333             dialog window (possibly integrated into an existing
334             configuration dialog in the application), while a
335             terminal-based MUA might generate a series of questions or
336             a terminal based menu selection.
337 */
338 const char* signatureConfigurationDialog( void );
339
340 /*! \ingroup groupConfigSign
341    \brief This function returns an XML representation of a
342             configuration dialog for selecting a signature key.
343
344    This will typically be used when the user wants to select a
345             signature key for one specific message only; the defaults
346             are set in the dialog returned by
347             signatureConfigurationDialog().
348 */
349 const char* signatureKeySelectionDialog( void );
350
351 /*! \ingroup groupConfigSign
352    \brief This function returns an XML representation of a
353             configuration dialog for selecting a signature
354             algorithm.
355
356    This will typically be used when the user wants
357           to select a signature algorithm for one specific message only; the
358           defaults are set in the dialog returned by
359             signatureConfigurationDialog().
360 */
361 const char* signatureAlgorithmDialog( void );
362
363 /*! \ingroup groupConfigSign
364    \brief This function returns an XML representation of a
365             configuration dialog for selecting whether an email
366             message and its attachments should be sent with or
367             without signatures.
368
369    This will typically be used when the
370             user wants to select a signature key for one specific
371             message only; the defaults are set in the dialog returned
372             by signatureConfigurationDialog().
373 */
374 const char* signatureHandlingDialog( void );
375
376 /*! \ingroup groupConfigSign
377    \brief Sets the signature key certificate that identifies the
378           role of the signer.
379 */
380 void setSignatureKeyCertificate( const char* certificate );
381
382 /*! \ingroup groupConfigSign
383    \brief Returns the signature key certificate that identifies
384             the role of the signer.
385 */
386 const char* signatureKeyCertificate( void );
387
388 /*! \ingroup groupConfigSign
389    \brief Sets the algorithm used for signing.
390 */
391 void setSignatureAlgorithm( SignatureAlgorithm );
392
393 /*! \ingroup groupConfigSign
394    \brief Returns the algorithm used for signing.
395 */
396 SignatureAlgorithm signatureAlgorithm( void );
397
398 /*! \ingroup groupConfigSign
399    \brief Sets which certificates should be sent with the
400             message.
401 */
402 void setSendCertificates( SendCertificates );
403 /*! \ingroup groupConfigSign
404    \brief Returns which certificates should be sent with the
405             message.
406 */
407 SendCertificates sendCertificates( void );
408
409 /*! \ingroup groupConfigSign
410    \brief Specifies whether email should be automatically
411             signed, signed after confirmation, signed after
412             confirmation for each part or not signed at all.
413 */
414 void setSignEmail( SignEmail );
415
416 /*! \ingroup groupConfigSign
417    \brief Returns whether email should be automatically
418             signed, signed after confirmation, signed after
419             confirmation for each part or not signed at all.
420 */
421 SignEmail signEmail( void );
422
423     
424 /*! \ingroup groupConfigSign
425   \brief Specifies whether a warning should be emitted when the user
426   tries to send an email message unsigned.
427 */
428 void setWarnSendUnsigned( bool );    
429
430     
431 /*! \ingroup groupConfigSign
432   \brief Returns whether a warning should be emitted when the user
433   tries to send an email message unsigned.
434 */
435 bool warnSendUnsigned( void );
436
437     
438 /*! \ingroup groupConfigSign
439    \brief Specifies whether sent email messages should be stored
440           with or without their signatures.
441 */
442 void setSaveSentSignatures( bool );
443
444 /*! \ingroup groupConfigSign
445    \brief Returns whether sent email messages should be stored
446             with or without their signatures.
447 */
448 bool saveSentSignatures( void );
449
450 /*! \ingroup groupConfigSign
451    \brief Specifies whether a warning should be emitted if the
452             email address of the sender is not contained in the
453             certificate.
454 */
455 void setWarnNoCertificate( bool );
456
457 /*! \ingroup groupConfigSign
458    \brief Returns whether a warning should be emitted if the
459             email address of the sender is not contained in the
460             certificate.
461 */
462 bool warnNoCertificate( void );
463
464 /*! \ingroup groupConfigSign
465    \brief Specifies how often the PIN is requested when
466             accessing the secret signature key.
467 */
468 void setNumPINRequests( PinRequests );
469
470 /*! \ingroup groupConfigSign
471    \brief Returns how often the PIN is requested when
472             accessing the secret signature key.
473 */
474 PinRequests numPINRequests( void );
475
476 /*! \ingroup groupConfigSign
477   \brief Specifies the interval in minutes the PIN must be reentered if
478   numPINRequests() is PinRequest_AfterMinutes.
479 */
480 void setNumPINRequestsInterval( int );
481
482     
483 /*! \ingroup groupConfigSign
484   \brief Returns the interval in minutes the PIN must be reentered if
485   numPINRequests() is PinRequest_AfterMinutes.
486 */
487 int numPINRequestsInterval( void );
488
489
490 /*! \ingroup groupConfigSign
491    \brief Specifies whether the certificate path should be
492             followed to the root certificate or whether locally stored
493             certificates may be used.
494 */
495 void setCheckSignatureCertificatePathToRoot( bool );
496
497 /*! \ingroup groupConfigSign
498    \brief Returns whether the certificate path should be
499             followed to the root certificate or whether locally stored
500             certificates may be used.
501 */
502 bool checkSignatureCertificatePathToRoot( void );
503
504 /*! \ingroup groupConfigSign
505    \brief Specifies whether certificate revocation lists should
506             be used.
507 */
508 void setSignatureUseCRLs( bool );
509
510 /*! \ingroup groupConfigSign
511    \brief Returns whether certificate revocation lists should
512             be used.
513 */
514 bool signatureUseCRLs( void );
515
516 /*! \ingroup groupConfigSign
517    \brief Specifies whether a warning should be emitted if the
518    signature certificate expires in the near future.
519 */
520 void setSignatureCertificateExpiryNearWarning( bool );
521
522 /*! \ingroup groupConfigSign
523    \brief Returns whether a warning should be emitted if
524    the signature certificate expires in the near future.
525 */
526 bool signatureCertificateExpiryNearWarning( void );
527
528 /*! \ingroup groupConfigSign
529    \brief Specifies the number of days which a signature certificate must
530    be valid before it is considered to expire in the near
531    future.
532 */
533 void setSignatureCertificateExpiryNearInterval( int );
534
535 /*! \ingroup groupConfigSign
536    \brief Returns the number of days which a signature certificate must
537             be valid before it is considered to expire in the near
538             future.
539 */
540 int signatureCertificateExpiryNearInterval( void );
541
542 /*! \ingroup groupConfigSign
543    \brief Specifies whether a warning should be emitted if the
544    CA certificate expires in the near future.
545 */
546 void setCACertificateExpiryNearWarning( bool );
547
548 /*! \ingroup groupConfigSign
549    \brief Returns whether a warning should be emitted if
550    the CA certificate expires in the near future.
551 */
552 bool caCertificateExpiryNearWarning( void );
553
554 /*! \ingroup groupConfigSign
555    \brief Specifies the number of days which a CA certificate must
556    be valid before it is considered to expire in the near
557    future.
558 */
559 void setCACertificateExpiryNearInterval( int );
560
561 /*! \ingroup groupConfigSign
562    \brief Returns the number of days which a CA certificate must
563             be valid before it is considered to expire in the near
564             future.
565 */
566 int caCertificateExpiryNearInterval( void );
567
568 /*! \ingroup groupConfigSign
569    \brief Specifies whether a warning should be emitted if the
570    root certificate expires in the near future.
571 */
572 void setRootCertificateExpiryNearWarning( bool );
573
574 /*! \ingroup groupConfigSign
575    \brief Returns whether a warning should be emitted if
576    the root certificate expires in the near future.
577 */
578 bool rootCertificateExpiryNearWarning( void );
579
580 /*! \ingroup groupConfigSign
581    \brief Specifies the number of days which a root certificate must
582    be valid before it is considered to expire in the near
583    future.
584 */
585 void setRootCertificateExpiryNearInterval( int );
586
587 /*! \ingroup groupConfigSign
588    \brief Returns the number of days which a signature certificate must
589             be valid before it is considered to expire in the near
590             future.
591 */
592 int rootCertificateExpiryNearInterval( void );
593
594
595     
596
597 /*! \ingroup groupConfigCrypt
598    \brief This function returns an XML representation of a
599             configuration dialog for configuring encryption
600             handling.
601
602    The syntax is that of <filename>.ui</filename>
603             files as specified in the <emphasis>Imhotep</emphasis>
604             documentation. This function does not execute or show the
605             dialog in any way; this is up to the MUA. Also, what the
606             MUA makes of the information provided highly depends on
607             the MUA itself. A GUI-based MUA will probably create a
608             dialog window (possibly integrated into an existing
609             configuration dialog in the application), while a
610             terminal-based MUA might generate a series of questions or
611             a terminal based menu selection.
612 */
613 const char* encryptionConfigurationDialog( void );
614
615 /*! \ingroup groupConfigCrypt
616    \brief This function returns an XML representation of a
617             configuration dialog for selecting an encryption
618             algorithm.
619             
620    This will typically be used when the user wants
621           to select an encryption algorithm for one specific message only; the
622           defaults are set in the dialog returned by
623             encryptionConfigurationDialog().
624 */
625 const char* encryptionAlgorithmDialog( void );
626
627 /*! \ingroup groupConfigCrypt
628    \brief This function returns an XML representation of a
629             configuration dialog for selecting whether an email
630             message and its attachments should be encrypted.
631
632    This will typically be used when the
633             user wants to select an encryption key for one specific
634             message only; the defaults are set in the dialog returned
635             by encryptionConfigurationDialog().
636 */
637 const char* encryptionHandlingDialog( void );
638
639 /*! \ingroup groupConfigCrypt
640    \brief This function returns an XML representation of a
641             dialog that lets the user select the certificate to use
642             for encrypting.
643
644    If it was not possible to determine the
645             correct certificate from the information in the email
646             message, the user is presented with a list of possible
647             certificates to choose from. If a unique certificate was
648             found, this is presented to the user, who needs to confirm
649           the selection of the certificate. This procedure is repeated
650           for each recipient of the email message.
651 */
652 const char* encryptionReceiverDialog( void );
653
654 /*! \ingroup groupConfigCrypt
655    \brief Sets the algorithm used for encrypting.
656 */
657 void setEncryptionAlgorithm( EncryptionAlgorithm );
658
659 /*! \ingroup groupConfigCrypt
660    \brief Returns the algorithm used for encrypting.
661 */
662 EncryptionAlgorithm encryptionAlgorithm( void );
663
664 /*! \ingroup groupConfigCrypt
665    \brief Specifies whether email should be automatically
666             encrypted, encrypted after confirmation, encrypted after
667             confirmation for each part or not encrypted at all.
668 */
669 void setEncryptEmail( EncryptEmail );
670
671 /*! \ingroup groupConfigCrypt
672    \brief Returns whether email should be automatically
673             encrypted, encrypted after confirmation, encrypted after
674             confirmation for each part or not encrypted at all.
675 */
676 EncryptEmail encryptEmail( void );
677
678 /*! \ingroup groupConfigSign
679   \brief Specifies whether a warning should be emitted when the user
680   tries to send an email message unencrypted.
681 */
682 void setWarnSendUnencrypted( bool );
683
684
685 /*! \ingroup groupConfigSign
686   \brief Returns whether a warning should be emitted when the user
687   tries to send an email message unencrypted.
688 */
689 bool warnSendUnencrypted( void );    
690     
691
692 /*! \ingroup groupConfigCrypt
693    \brief Specifies whether encrypted email messages should be
694             stored encrypted or decrypted.
695 */
696 void setSaveMessagesEncrypted( bool );
697
698 /*! \ingroup groupConfigCrypt
699    \brief Returns whether encrypted email messages should be stored
700             encrypted or decrypted.
701 */
702 bool saveMessagesEncrypted( void );
703
704
705 /*! \ingroup groupConfigCrypt
706   \brief Specifies whether the certificate path should be checked
707   during encryption.
708 */
709 void setCheckCertificatePath( bool );
710
711 /*! \ingroup groupConfigCrypt
712   \brief Returns whether the certificate path should be checked
713   during encryption.
714 */
715 bool checkCertificatePath( void );
716
717     
718 /*! \ingroup groupConfigCrypt
719    \brief Specifies whether the certificate path should be
720             followed to the root certificate or whether locally stored
721             certificates may be used.
722 */
723 void setCheckEncryptionCertificatePathToRoot( bool );
724
725 /*! \ingroup groupConfigCrypt
726    \brief Returns whether the certificate path should be
727             followed to the root certificate or whether locally stored
728             certificates may be used.
729 */
730 bool checkEncryptionCertificatePathToRoot( void );
731
732     
733 /*! \ingroup groupConfigCrypt
734   \brief Specifies whether a warning should be emitted if the
735   certificate of the receiver expires in the near future.
736 */
737 void setReceiverCertificateExpiryNearWarning( bool );
738
739 /*! \ingroup groupConfigCrypt
740   \brief Returns whether a warning should be emitted if the
741   certificate of the receiver expires in the near future.
742 */
743 bool receiverCertificateExpiryNearWarning( void );
744     
745
746 /*! \ingroup groupConfigCrypt
747   \brief Specifies the number of days which a receiver certificate
748   must be valid before it is considered to expire in the near future.
749 */
750 void setReceiverCertificateExpiryNearWarningInterval( int );
751     
752 /*! \ingroup groupConfigCrypt
753   \brief Returns the number of days which a receiver certificate
754   must be valid before it is considered to expire in the near future.
755 */
756 int receiverCertificateExpiryNearWarningInterval( void );
757
758 /*! \ingroup groupConfigCrypt
759   \brief Specifies whether a warning should be emitted if 
760   a certificate in the chain expires in the near future.
761 */
762 void setCertificateInChainExpiryNearWarning( bool );
763
764     
765 /*! \ingroup groupConfigCrypt
766   \brief Returns whether a warning should be emitted if a
767   certificate in the chain expires in the near future.
768 */
769 bool certificateInChainExpiryNearWarning( void );
770
771     
772     
773 /*! \ingroup groupConfigCrypt
774   \brief Specifies the number of days which a certificate in the chain
775   must be valid before it is considered to expire in the near future.
776 */
777 void setCertificateInChainExpiryNearWarningInterval( int );
778
779 /*! \ingroup groupConfigCrypt
780   \brief Returns the number of days which a certificate in the chain
781   must be valid before it is considered to expire in the near future.
782 */
783 int certificateInChainExpiryNearWarningInterval( void );
784
785     
786 /*! \ingroup groupConfigCrypt
787   \brief Specifies whether a warning is emitted if the email address
788   of the receiver does not appear in the certificate.
789 */
790 void setReceiverEmailAddressNotInCertificateWarning( bool );    
791
792 /*! \ingroup groupConfigCrypt
793   \brief Returns whether a warning is emitted if the email address
794   of the receiver does not appear in the certificate.
795 */
796 bool receiverEmailAddressNotInCertificateWarning( void );
797
798
799 /*! \ingroup groupConfigCrypt
800    \brief Specifies whether certificate revocation lists should
801             be used.
802 */
803 void setEncryptionUseCRLs( bool );
804
805 /*! \ingroup groupConfigCrypt
806    \brief Returns whether certificate revocation lists should
807             be used.
808 */
809 bool encryptionUseCRLs( void );
810
811 /*! \ingroup groupConfigCrypt
812    \brief Specifies whether a warning should be emitted if any
813             of the certificates involved in the signing process
814             expires in the near future.
815 */
816 void setEncryptionCRLExpiryNearWarning( bool );
817
818 /*! \ingroup groupConfigCrypt
819    \brief Returns whether a warning should be emitted if any
820             of the certificates involved in the signing process
821             expires in the near future.
822 */
823 bool encryptionCRLExpiryNearWarning( void );
824
825 /*! \ingroup groupConfigCrypt
826    \brief Specifies the number of days which a certificate must
827             be valid before it is considered to expire in the near
828             future.
829 */
830 void setEncryptionCRLNearExpiryInterval( int );
831
832 /*! \ingroup groupConfigCrypt
833    \brief Returns the number of days which a certificate must
834             be valid before it is considered to expire in the near
835             future.
836 */
837 int encryptionCRLNearExpiryInterval( void );
838
839
840 /*! \ingroup groupConfigDir
841    \brief This function returns an XML representation of a
842             configuration dialog for selecting a directory
843             server.
844 */
845 const char* directoryServiceConfigurationDialog( void );
846
847 /*! \ingroup groupConfigDir
848    \brief Lets you configure how certificates and certificate
849    revocation lists are retrieved (both locally and from directory
850    services).
851
852    Will mainly be used for restoring
853             configuration data; interactive configuration will be done
854             via the configuration dialog returned by
855             \c directoryServiceConfigurationDialog().
856 */
857 void appendDirectoryServer( const char* servername, int port,
858                             const char* description );
859
860
861
862
863 /*! \ingroup groupConfigDir
864 */
865 struct DirectoryServer {
866     char* servername;
867     int port;
868     char* description;
869 };
870
871
872 /*! \ingroup groupConfigDir
873    \brief Specifies a list of directory servers.
874
875    Will mainly be used for restoring
876             configuration data; interactive configuration will be done
877             via the configuration dialog returned by
878             \c directoryServiceConfigurationDialog().
879 */
880 void setDirectoryServers( struct DirectoryServer[], unsigned int size );
881
882 /*! \ingroup groupConfigDir
883    \brief Returns the list of directory servers.
884
885    Will mainly be used for saving configuration data; interactive
886             configuration will be done via the configuration dialog
887             returned by
888             \c directoryServiceConfigurationDialog().
889 */
890 struct DirectoryServer* directoryServers( int* numServers );
891
892 /*! \ingroup groupConfigDir
893    \brief Specifies whether certificates should be retrieved
894             from a directory server, only locally, or both.
895 */
896 void setCertificateSource( CertificateSource );
897
898 /*! \ingroup groupConfigDir
899    \brief Returns whether certificates should be retrieved
900             from a directory server, only locally, or both.
901 */
902 CertificateSource certificateSource( void );
903
904 /*! \ingroup groupConfigDir
905    \brief Specifies whether certificates should be retrieved
906             from a directory server, only locally, or both.
907 */
908 void setCRLSource( CertificateSource );
909
910 /*! \ingroup groupConfigDir
911    \brief Returns whether certificates should be retrieved
912             from a directory server, only locally, or both.
913 */
914 CertificateSource crlSource( void );
915
916
917 /*! \ingroup groupCertHand
918    \brief Returns \c true if and only if the
919           certificates in the certificate chain starting at
920           \c certificate are valid.
921
922    If \c level is non-null, the parameter contains
923           the degree of trust on a backend-specific scale. In an X.509
924           implementation, this will either be \c 1
925           (valid up to the root certificate) or \c 0
926           (not valid up to the root certificate).
927 */
928 bool certificateValidity( const char* certificate, int* level );
929
930
931 /*! \ingroup groupSignCryptAct
932    \brief Information record returned by signing and by encrypting
933    functions - this record should be used together with a
934    corresponding \c free_StructuringInfo() function call.
935
936    Use this information to compose a MIME object containing signed
937    and/or encrypted content (or to build a text frame around your
938    flat non-MIME message body, resp.)
939
940    <b>If</b> value returned in \c makeMimeObject is <b>TRUE</b> the
941    text strings returned in \c contentTypeMain and \c contentDispMain
942    and \c contentTEncMain (and, if required, \c content[..]Version and
943    \c bodyTextVersion and \c content[..]Sig) should be used to compose
944    a respective MIME object.<br>
945    If <b>FALSE</b> the texts returned in \c flatTextPrefix and
946    \c flatTextSeparator and \c flatTextPostfix are to be used instead.<br>
947    Allways <b>either</b> the \c content[..] and \c bodyTextVersion
948    parameters <b>or</b> the \c flatText[..] parameters are holding
949    valid data - never both of them may be used simultaneously
950    as plugins will just ignore the parameters not matching their
951    \c makeMimeObject setting.
952
953    When creating your MIME object please observe these common rules:
954    \li Parameters named \c contentType[..] and \c contentDisp[..] and
955    \c contentTEnc[..] will return the values for the respective MIME
956    headers 'Content-Type' and 'Content-Disposition' and
957    'Content-Transfer-Encoding'. The following applies to these parameters:
958    \li The relevant MIME part may <b>only</b> be created if the respective
959    \c contentType[..] parameter is holding a non-zero-length string. If the
960    \c contentType[..] parameter value is invalid or holding an empty string
961    the respective \c contentDisp[..] and \c contentTEnc[..] parameters
962    should be ignored.
963    \li If the respective \c contentDisp[..] or \c contentTEnc[..] parameter
964    is NULL or holding a zero-length string it is up to you whether you want
965    to add the relevant MIME header yourself, but since it in in the
966    responsibility of the plugin implementors to provide you with all
967    neccessary 'Content-[..]' header information you should <b>not need</b>
968    to define them if they are not returned by the signing or encrypting
969    function - otherwise this may be considered as a bug in the plugin and
970    you could report the missing MIME header information to the address
971    returned by the \c bugURL() function.
972
973    If \c makeMultiMime returns FALSE the \c contentTypeMain returned must
974    not be altered but used to specify a single part mime object holding the
975    code bloc, e.g. this is used for 'enveloped-data' single part MIME
976    objects. In this case you should ignore both the \c content[..]Version
977    and \c content[..]Code parameters.
978
979    If \c makeMultiMime returns TRUE also the following rules apply:
980    \li If \c includeCleartext is TRUE you should include the cleartext
981    as first part of our multipart MIME object, typically this is TRUE
982    when signing mails but FALSE when encrypting.
983    \li The \c contentTypeMain returned typically starts with
984    "multipart/" while providing a "protocol" and a "micalg" parameter: just
985    add an appropriate \c "; boundary=[your \c boundary \c string]" to get
986    the complete Content-Type value to be used for the MIME object embedding
987    both the signed part and the signature part (or - in case of
988    encrypting - the version part and the code part, resp.).
989    \li If \c contentTypeVersion is holding a non-zero-length string an
990    additional MIME part must added immediately before the code part, this
991    version part's MIME headers must have the unaltered values of
992    \c contentTypeVersion and (if they are holding non-zero-length strings)
993    \c contentDispVersion and \c contentTEncVersion, the unaltered contents
994    of \c bodyTextVersion must be it's body.
995    \li The value returned in \c contentTypeCode is specifying the complete
996    Content-Type to be used for this multipart MIME object's signature part
997    (or - in case of encrypting - for the code part following after the
998    version part, resp.), you should not add/change/remove anything here
999    but just use it's unaltered value for specifying the Content-Type header
1000    of the respective MIME part.
1001    \li The same applies to the \c contentDispCode value: just use it's
1002    unaltered value to specify the Content-Disposition header entry of
1003    the respective MIME part.
1004    \li The same applies to the \c contentTEncCode value: just use it's
1005    unaltered value to specify the Content-Transfer-Encoding header of
1006    the respective MIME part.
1007
1008    <b>If</b> value returned in \c makeMimeObject is <b>FALSE</b> the
1009    text strings returned in \c flatTextPrefix and \c flatTextPostfix
1010    should be used to build a frame around the cleartext and the code
1011    bloc holding the signature (or - in case of encrypting - the encoded
1012    data bloc, resp.).<br>
1013    If \c includeCleartext is TRUE this frame should also include the
1014    cleartext as first bloc, this bloc should be divided from the code bloc
1015    by the contents of \c flatTextSeparator - typically this is used for
1016    signing but not when encrypting.<br>
1017    If \c includeCleartext is FALSE you should ignore both the cleartext
1018    and the \c flatTextSeparator parameter.
1019
1020    <b>How to use StructuringInfo data in your program:</b>
1021    \li To compose a signed message please act as described below.
1022    \li For constructing an encrypted message just replace the
1023    \c signMessage() call by the respective \c encryptMessage() call
1024    and then proceed exactly the same way.
1025    \li In any case make <b>sure</b> to free your \c ciphertext <b>and</b>
1026    to call \c free_StructuringInfo() when you are done with processing
1027    the data returned by the signing (or encrypting, resp.) function.
1028
1029 \verbatim
1030
1031     char* ciphertext;
1032     StructuringInfo structInf;
1033
1034     if( ! signMessage( cleartext, &ciphertext, certificate,
1035                        &structuring ) ) {
1036
1037         myErrorDialog( "Error: could not sign the message!" );
1038
1039     } else {
1040       if( structInf.makeMimeObject ) {
1041
1042         // Build the main MIME object.
1043         // This is done by
1044         // using the header values returned in
1045         // structInf.contentTypeMain and in
1046         // structInf.contentDispMain and in
1047         // structInf.contentTEncMain.
1048         ..
1049
1050         if( ! structInf.makeMultiMime ) {
1051
1052           // Build the main MIME object's body.
1053           // This is done by
1054           // using the code bloc returned in
1055           // ciphertext.
1056           ..
1057
1058         } else {
1059
1060           // Build the encapsulated MIME parts.
1061           if( structInf.includeCleartext ) {
1062
1063             // Build a MIME part holding the cleartext.
1064             // This is done by
1065             // using the original cleartext's headers and by
1066             // taking it's original body text.
1067             ..
1068
1069           }
1070           if(    structInf.contentTypeVersion
1071               && 0 < strlen( structInf.contentTypeVersion ) ) {
1072
1073             // Build a MIME part holding the version information.
1074             // This is done by
1075             // using the header values returned in
1076             // structInf.contentTypeVersion and
1077             // structInf.contentDispVersion and
1078             // structInf.contentTEncVersion and by
1079             // taking the body contents returned in
1080             // structInf.bodyTextVersion.
1081             ..
1082
1083           }
1084           if(    structInf.contentTypeCode
1085               && 0 < strlen( structInf.contentTypeCode ) ) {
1086
1087             // Build a MIME part holding the code information.
1088             // This is done by
1089             // using the header values returned in
1090             // structInf.contentTypeCode and
1091             // structInf.contentDispCode and
1092             // structInf.contentTEncCode and by
1093             // taking the body contents returned in
1094             // ciphertext.
1095             ..
1096
1097           } else {
1098
1099             // Plugin error!
1100             myErrorDialog( "Error: Cryptography plugin returned a main"
1101                            "Content-Type=Multipart/.. but did not "
1102                            "specify the code bloc's Content-Type header."
1103                            "\nYou may report this bug:"
1104                            "\n" + cryptplug.bugURL() );
1105           }
1106         }
1107       } else  {
1108
1109         // Build a plain message body
1110         // based on the values returned in structInf.
1111         // Note: We do _not_ insert line breaks between the parts since
1112         //       it is the plugin job to provide us with ready-to-use
1113         //       texts containing all neccessary line breaks.
1114         strcpy( myMessageBody, structInf.plainTextPrefix );
1115         if( structInf.includeCleartext ) {
1116           strcat( myMessageBody, cleartext );
1117           strcat( myMessageBody, structInf.plainTextSeparator );
1118         }
1119         strcat( myMessageBody, *ciphertext );
1120         strcat( myMessageBody, structInf.plainTextPostfix );
1121       }
1122
1123       // free the memory that was allocated
1124       // for the ciphertext
1125       free( ciphertext );
1126
1127       // free the memory that was allocated
1128       // for our StructuringInfo's char* members
1129       free_StructuringInfo( &structuring );
1130     }
1131
1132 \endverbatim
1133
1134    \note Make sure to call \c free_StructuringInfo() when you are done
1135    with processing the StructuringInfo data!
1136
1137   \see free_StructuringInfo
1138   \see signMessage, encryptMessage, encryptAndSignMessage
1139 */
1140 struct StructuringInfo {
1141   bool includeCleartext;     /*!< specifies whether we should include the
1142                                   cleartext as first part of our multipart
1143                                   MIME object (or - for non-MIME
1144                                   messages - as flat text to be set before
1145                                   the ciphertext, resp.), typically this
1146                                   is TRUE when signing mails but FALSE
1147                                   when encrypting<br>
1148                                   (this parameter is relevant no matter
1149                                   whether \c makeMimeObject is TRUE or
1150                                   FALSE) */
1151   bool  makeMimeObject;      /*!< specifies whether we should create a MIME
1152                                   object or a flat text message body */
1153   // the following are used for MIME messages only
1154   bool  makeMultiMime;       /*!< specifies whether we should create a
1155                                   'Multipart' MIME object or a single part
1156                                   object, if FALSE only \c contentTypeMain,
1157                                   \c contentDispMain and \c contentTEncMain
1158                                   may be used and all other parameters have
1159                                   to be ignored<br>
1160                                   (ignore this parameter if \c makeMimeObject
1161                                   is FALSE) */
1162   char* contentTypeMain;     /*!< value of the main 'Content-Type'
1163                                   header<br>
1164                                   (ignore this parameter if \c makeMimeObject
1165                                   is FALSE) */
1166   char* contentDispMain;     /*!< value of the main 'Content-Disposition'
1167                                   header<br>
1168                                   (ignore this parameter if \c makeMimeObject
1169                                   is FALSE) */
1170   char* contentTEncMain;     /*!< value of the main
1171                                   'Content-TransferEncoding' header<br>
1172                                   (ignore this parameter if \c makeMimeObject
1173                                   is FALSE) */
1174   char* contentTypeVersion;  /*!< 'Content-Type' of the additional version
1175                                   part that might preceed the code part -
1176                                   if NULL or zero length no version part
1177                                   must be created<br>
1178                                   (ignore this parameter if either
1179                                   \c makeMimeObject or \c makeMultiMime
1180                                   is FALSE) */
1181   char* contentDispVersion;  /*!< 'Content-Disposition' of the additional
1182                                   preceeding the code part (only valid if
1183                                   \c contentTypeVersion holds a
1184                                   non-zero-length string)<br>
1185                                   (ignore this parameter if either
1186                                   \c makeMimeObject or \c makeMultiMime
1187                                   is FALSE or if \c contentTypeVersion does
1188                                   not return a non-zero-length string) */
1189   char* contentTEncVersion;  /*!< 'Content-Transfer-Encoding' of the
1190                                   additional version part (only valid if
1191                                   \c contentTypeVersion holds a
1192                                   non-zero-length string)<br>
1193                                   (ignore this parameter if either
1194                                   \c makeMimeObject or \c makeMultiMime
1195                                   is FALSE or if \c contentTypeVersion does
1196                                   not return a non-zero-length string) */
1197   char* bodyTextVersion;     /*!< body text of the additional version part
1198                                   (only valid if \c contentTypeVersion
1199                                   holds a non-zero-length string)<br>
1200                                   (ignore this parameter if either
1201                                   \c makeMimeObject or \c makeMultiMime
1202                                   is FALSE or if \c contentTypeVersion does
1203                                   not return a non-zero-length string) */
1204   char* contentTypeCode;     /*!< 'Content-Type' of the code part holding
1205                                   the signature code (or the encrypted
1206                                   data, resp.)<br>
1207                                   (ignore this parameter if either
1208                                   \c makeMimeObject or \c makeMultiMime
1209                                   is FALSE) */
1210   char* contentDispCode;     /*!< 'Content-Disposition' of the code part<br>
1211                                   (ignore this parameter if either
1212                                   \c makeMimeObject or \c makeMultiMime
1213                                   is FALSE or if \c contentTypeCode does
1214                                   not return a non-zero-length string) */
1215   char* contentTEncCode;     /*!< 'Content-Type' of the code part<br>
1216                                   (ignore this parameter if either
1217                                   \c makeMimeObject or \c makeMultiMime
1218                                   is FALSE or if \c contentTypeCode does
1219                                   not return a non-zero-length string) */
1220   // the following are used for flat non-MIME messages only
1221   char* flatTextPrefix;      /*!< text to preceed the main text (or the
1222                                   code bloc containing the encrypted main
1223                                   text, resp.)<br>
1224                                   (ignore this parameter if
1225                                   \c makeMimeObject is TRUE) */
1226   char* flatTextSeparator;   /*!< text to be put between the main text and
1227                                   the signature code bloc (not used when
1228                                   encrypting)<br>
1229                                   (ignore this parameter if
1230                                   \c makeMimeObject is TRUE or if
1231                                   \c includeCleartext is FALSE) */
1232   char* flatTextPostfix;     /*!< text to follow the signature code bloc
1233                                   (or the encrypted data bloc, resp.)<br>
1234                                   (ignore this parameter if
1235                                   \c makeMimeObject is TRUE) */
1236 };
1237
1238
1239 /*! \ingroup groupAdUsoInterno
1240     \brief If you are not planning to write your own cryptography
1241     plugin <b>you should ignore this</b> function!
1242
1243     Usage of this function is depreciated for plugin users but highly
1244     recommended for plugin implementors since this is an internal
1245     function for initializing all char* members of a \c StructuringInfo
1246     struct.<br>
1247     This function <b>must</b> be called in <b>any</b> plugin's
1248     implementations of the following functions:
1249
1250     \c signMessage() <br>
1251     \c encryptMessage() <br>
1252     \c encryptAndSignMessage()
1253
1254     Calling this function makes sure the corresponding
1255     \c free_StructuringInfo() calls which will be embedded by
1256     your plugin's users into their code will be able to
1257     determine which of the char* members belonging to the
1258     respective's StructuringInfo had been allocated memory
1259     for during previous signing or encrypting actions.
1260
1261     \see free_StructuringInfo, StructuringInfo
1262     \see signMessage, encryptMessage, encryptAndSignMessage
1263 */
1264   void init_StructuringInfo( struct StructuringInfo* s )
1265   {
1266     if( ! s ) return;
1267
1268     s->includeCleartext = false;
1269
1270     s->makeMimeObject = false;
1271     s->makeMultiMime = false;
1272
1273     s->contentTypeMain = 0;
1274     s->contentDispMain = 0;
1275     s->contentTEncMain = 0;
1276
1277     s->contentTypeVersion = 0;
1278     s->contentDispVersion = 0;
1279     s->contentTEncVersion = 0;
1280     s->bodyTextVersion = 0;
1281
1282     s->contentTypeCode = 0;
1283     s->contentDispCode = 0;
1284     s->contentTEncCode = 0;
1285
1286     s->flatTextPrefix = 0;
1287     s->flatTextSeparator = 0;
1288     s->flatTextPostfix = 0;
1289   }
1290
1291 /*! \ingroup groupSignCryptAct
1292     \brief Important method for freeing all memory that was allocated
1293     for the char* members of a \c StructuringInfo struct - use
1294     this function after <b>each</b> signing or encrypting function
1295     call.
1296
1297     \note Even when intending to call \c encryptMessage() immediately
1298     after having called \c signMessage() you first <b>must</b> call
1299     the \c free_StructuringInfo() function to make sure all memory is
1300     set free that was allocated for your StructuringInfo's char* members
1301     by the \c signMessage() function!
1302
1303     \see StructuringInfo
1304 */
1305   void free_StructuringInfo( struct StructuringInfo* s )
1306   {
1307     if( ! s ) return;
1308     if( s->contentTypeMain )    free( s->contentTypeMain );
1309     if( s->contentDispMain )    free( s->contentDispMain );
1310     if( s->contentTEncMain )    free( s->contentTEncMain );
1311     if( s->contentTypeVersion ) free( s->contentTypeVersion );
1312     if( s->contentDispVersion ) free( s->contentDispVersion );
1313     if( s->contentTEncVersion ) free( s->contentTEncVersion );
1314     if( s->bodyTextVersion )    free( s->bodyTextVersion );
1315     if( s->contentTypeCode )    free( s->contentTypeCode );
1316     if( s->contentDispCode )    free( s->contentDispCode );
1317     if( s->contentTEncCode )    free( s->contentTEncCode );
1318     if( s->flatTextPrefix )     free( s->flatTextPrefix );
1319     if( s->flatTextSeparator )  free( s->flatTextSeparator );
1320     if( s->flatTextPostfix )    free( s->flatTextPostfix );
1321   }
1322
1323
1324 /*! \ingroup groupSignAct
1325    \brief Signs a message \c cleartext and returns
1326           in \c *ciphertext the signature data bloc that
1327           is to be added to the message.
1328
1329    The signature role is specified by \c certificate.
1330    If \c certificate is \c NULL, the default certificate is used.
1331
1332    If the message could be signed, the function returns
1333           \c true, otherwise
1334           \c false.
1335
1336    Use the StructuringInfo data returned in parameter \c structuring
1337    to find out how to build the respective MIME object (or the plain
1338    text message body, resp.).
1339
1340    \note The function allocates memory for the \c *ciphertext, so
1341          make sure you set free that memory when no longer needing
1342          it (as shown in example code provided with documentation
1343          of the struct \c StructuringInfo).
1344
1345    \note The function also allocates memory for some char* members
1346     of the StructuringInfo* parameter that you are providing,
1347     therefore you <b>must</b> call the \c free_StructuringInfo() function
1348     to make sure all memory is set free that was allocated. This must be
1349     done <b>before</b> calling the next cryptography function - even if
1350     you intend to call \c encryptMessage() immediately after
1351     \c signMessage().
1352
1353    \see StructuringInfo, free_StructuringInfo
1354 */
1355 bool signMessage( const char*  cleartext,
1356                   const char** ciphertext,
1357                   const char*  certificate,
1358                   struct StructuringInfo* structuring );
1359
1360
1361 /*! \ingroup groupSignAct
1362  */
1363 struct SignatureMetaDataExtendedInfo
1364 {
1365     struct tm* creation_time;
1366     char* status_text;
1367     char* fingerprint;
1368 };
1369
1370 /*! \ingroup groupSignAct
1371 */
1372 struct SignatureMetaData {
1373     char* status;
1374     struct SignatureMetaDataExtendedInfo* extended_info;
1375     int extended_info_count;
1376     char* nota_xml;
1377     int status_code;
1378 };
1379
1380 /*! \ingroup groupSignAct
1381    \brief Checks whether the signature of a message is
1382           valid. \c ciphertext specifies the signed message
1383           as it was received by the MUA, \c signaturetext is the
1384           signature itself.
1385
1386    Depending on the configuration, MUAs might not need to use this.
1387    If \c sigmeta is non-null, the
1388           \c SignatureMetaData object pointed to will
1389           contain meta information about the signature after the
1390           function call.
1391 */
1392 bool checkMessageSignature( const char* ciphertext,
1393                             const char* signaturetext,
1394                             struct SignatureMetaData* sigmeta );
1395
1396 /*! \ingroup groupSignAct
1397    \brief Stores the certificates that follow with the message
1398           \c ciphertext locally.
1399 */
1400 bool storeCertificatesFromMessage( const char* ciphertext );
1401
1402
1403 /*! \ingroup groupCryptAct
1404    \brief Encrypts an email message in
1405           \c cleartext according to the \c addressee and
1406           the current settings (algorithm, etc.) and
1407           returns the encoded data bloc in \c *ciphertext.
1408
1409    If the message could be encrypted, the function returns
1410           \c true, otherwise
1411           \c false.
1412
1413    Use the StructuringInfo data returned in parameter \c structuring
1414    to find out how to build the respective MIME object (or the plain
1415    text message body, resp.).
1416
1417    \note The function allocates memory for the \c *ciphertext, so
1418          make sure you set free that memory when no longer needing
1419          it (as shown in example code provided with documentation
1420          of the struct \c StructuringInfo).
1421
1422    \note The function also allocates memory for some char* members
1423     of the StructuringInfo* parameter that you are providing,
1424     therefore you <b>must</b> call the \c free_StructuringInfo() function
1425     to make sure all memory is set free that was allocated. This must be
1426     done <b>before</b> calling the next cryptography function!
1427
1428    \see StructuringInfo, free_StructuringInfo
1429 */
1430 bool encryptMessage( const char*  cleartext,
1431                      const char** ciphertext,
1432                      const char*  addressee,
1433                      struct StructuringInfo* structuring );
1434
1435
1436 /*! \ingroup groupCryptAct
1437    \brief Combines the functionality of
1438           \c encryptMessage() and
1439           \c signMessage().
1440
1441    If \c certificate is \c NULL,
1442    the default certificate will be used.
1443
1444    If the message could be signed and encrypted, the function returns
1445           \c true, otherwise
1446           \c false.
1447
1448    Use the StructuringInfo data returned in parameter \c structuring
1449    to find out how to build the respective MIME object (or the plain
1450    text message body, resp.).
1451
1452    \note The function allocates memory for the \c *ciphertext, so
1453          make sure you set free that memory when no longer needing
1454          it (as shown in example code provided with documentation
1455          of the struct \c StructuringInfo).
1456
1457    \note The function also allocates memory for some char* members
1458     of the StructuringInfo* parameter that you are providing,
1459     therefore you <b>must</b> call the \c free_StructuringInfo() function
1460     to make sure all memory is set free that was allocated. This must be
1461     done <b>before</b> calling the next cryptography function!
1462
1463    \see StructuringInfo, free_StructuringInfo
1464 */
1465 bool encryptAndSignMessage( const char* cleartext,
1466                             const char** ciphertext,
1467                             const char* certificate,
1468                             struct StructuringInfo* structuring );
1469
1470 /*! \ingroup groupCryptAct
1471    \brief Tries to decrypt an email message
1472           \c ciphertext and returns the decrypted
1473           message in \c cleartext.
1474
1475    The \c certificate is used for decryption. If
1476           the message could be decrypted, the function returns
1477           \c true, otherwise
1478           \c false.
1479 */
1480 bool decryptMessage( const char* ciphertext, const
1481           char** cleartext, const char* certificate );
1482
1483 /*! \ingroup groupCryptAct
1484    \brief Combines the functionality of
1485           \c checkMessageSignature() and
1486           \c decryptMessage().
1487
1488    If \c certificate is \c NULL,
1489    the default certificate will be used.
1490    If \c sigmeta is non-null, the \c SignatureMetaData
1491    object pointed to will contain meta information about
1492    the signature after the function call.
1493 */
1494 bool decryptAndCheckMessage( const char* ciphertext,
1495                              const char** cleartext,
1496                              const char* certificate,
1497                              struct SignatureMetaData* sigmeta );
1498
1499
1500 /*! \ingroup groupCertAct
1501    \brief This function returns an XML representation of a dialog
1502           that can be used to fill in the data for requesting a
1503           certificate (which in turn is done with the function
1504           \c requestCertificate() described
1505           next.
1506 */
1507 const char* requestCertificateDialog( void );
1508
1509 /*! \ingroup groupCertAct
1510    \brief Generates a prototype certificate with the data provided
1511         in the first four parameters and sends it via email to the CA
1512           specified in \c ca_address.
1513 */
1514 bool requestDecentralCertificate( const char* name, const char*
1515           email, const char* organization, const char* department,
1516           const char* ca_address );
1517
1518 /*! \ingroup groupCertAct
1519    \brief Requests a certificate in a PSE from the CA
1520           specified in \c ca_address.
1521 */
1522 bool requestCentralCertificateAndPSE( const char* name,
1523           const char* email, const char* organization, const char* department,
1524           const char* ca_address );
1525
1526 /*! \ingroup groupCertAct
1527    \brief Creates a local PSE.
1528 */
1529 bool createPSE( void );
1530
1531 /*! \ingroup groupCertAct
1532    \brief Parses and adds a certificate returned by a CA upon
1533           request with
1534           \c requestDecentralCertificate() or
1535           \c requestCentralCertificate().
1536
1537    If the certificate was requested with
1538           \c requestCentralCertificate(), the
1539           certificate returned will come complete with a PSE which is
1540           also registered with this method.
1541 */
1542 bool registerCertificate( const char* );
1543
1544 /*! \ingroup groupCertAct
1545    \brief Requests the prolongation of the certificate
1546           \c certificate from the CA
1547           \c ca_address.
1548 */
1549 bool requestCertificateProlongation( const char*
1550           certificate, const char* ca_address );
1551
1552 /*! \ingroup groupCertAct
1553    \brief Returns an HTML 2-formatted string that describes the
1554           certificate chain of the user's certificate.
1555           
1556    Data displayed is at least the issuer of the certificate, the serial number
1557         of the certificate, the owner of the certificate, the checksum
1558         of the certificate, the validity duration of the certificate,
1559           the usage of the certificate, and the contained email
1560           addresses, if any.
1561 */
1562 const char* certificateChain( void );
1563
1564 /*! \ingroup groupCertAct
1565    \brief Deletes the specified user certificate from the current
1566           PSE.
1567 */
1568 bool deleteCertificate( const char* certificate );
1569
1570 /*! \ingroup groupCertAct
1571    \brief Archives the specified user certificate in the current PSE.
1572
1573    The certificate cannot be used any longer after this
1574           operation unless it is unarchived.
1575 */
1576 bool archiveCertificate( const char* certificate );
1577
1578
1579 /*! \ingroup groupCRLAct
1580    \brief Returns a HTML 2-formatted string that describes the
1581           CRL, suitable for display in the MUA.
1582 */
1583 const char* displayCRL( void );
1584
1585 /*! \ingroup groupCRLAct
1586    \brief Manually update the CRL. CRLs will also be automatically
1587         updated on demand by the backend.
1588         
1589    If there is a local version of a CRL saved, it will be overwritten
1590    with the new CRL from the CA.
1591 */
1592 void updateCRL( void );
1593
1594 #ifdef __cplusplus
1595 }
1596 #endif
1597 #endif /*CRYPTPLUG_H*/
1598