Support for warning when a CRL expires
[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 /*!
465   \ingroup groupConfigSign
466   \brief Returns true if the specified email address is contained
467   in the specified certificate.
468 */
469 bool isEmailInCertificate( const char* email, const char* certificate );
470
471 /*! \ingroup groupConfigSign
472    \brief Specifies how often the PIN is requested when
473             accessing the secret signature key.
474 */
475 void setNumPINRequests( PinRequests );
476
477 /*! \ingroup groupConfigSign
478    \brief Returns how often the PIN is requested when
479             accessing the secret signature key.
480 */
481 PinRequests numPINRequests( void );
482
483 /*! \ingroup groupConfigSign
484   \brief Specifies the interval in minutes the PIN must be reentered if
485   numPINRequests() is PinRequest_AfterMinutes.
486 */
487 void setNumPINRequestsInterval( int );
488
489     
490 /*! \ingroup groupConfigSign
491   \brief Returns the interval in minutes the PIN must be reentered if
492   numPINRequests() is PinRequest_AfterMinutes.
493 */
494 int numPINRequestsInterval( void );
495
496
497 /*! \ingroup groupConfigSign
498    \brief Specifies whether the certificate path should be
499             followed to the root certificate or whether locally stored
500             certificates may be used.
501 */
502 void setCheckSignatureCertificatePathToRoot( bool );
503
504 /*! \ingroup groupConfigSign
505    \brief Returns whether the certificate path should be
506             followed to the root certificate or whether locally stored
507             certificates may be used.
508 */
509 bool checkSignatureCertificatePathToRoot( void );
510
511 /*! \ingroup groupConfigSign
512    \brief Specifies whether certificate revocation lists should
513             be used.
514 */
515 void setSignatureUseCRLs( bool );
516
517 /*! \ingroup groupConfigSign
518    \brief Returns whether certificate revocation lists should
519             be used.
520 */
521 bool signatureUseCRLs( void );
522
523 /*! \ingroup groupConfigSign
524    \brief Specifies whether a warning should be emitted if the
525    signature certificate expires in the near future.
526 */
527 void setSignatureCertificateExpiryNearWarning( bool );
528
529 /*! \ingroup groupConfigSign
530    \brief Returns whether a warning should be emitted if
531    the signature certificate expires in the near future.
532 */
533 bool signatureCertificateExpiryNearWarning( void );
534
535     /*! \ingroup groupConfigSign
536       \brief Returns the number of days that are left until the
537       specified certificate expires. 
538       \param certificate the certificate to check
539     */
540     int signatureCertificateDaysLeftToExpiry( const char* certificate );
541
542 /*! \ingroup groupConfigSign
543    \brief Specifies the number of days which a signature certificate must
544    be valid before it is considered to expire in the near
545    future.
546 */
547 void setSignatureCertificateExpiryNearInterval( int );
548
549 /*! \ingroup groupConfigSign
550    \brief Returns the number of days which a signature certificate must
551             be valid before it is considered to expire in the near
552             future.
553 */
554 int signatureCertificateExpiryNearInterval( void );
555
556 /*! \ingroup groupConfigSign
557    \brief Specifies whether a warning should be emitted if the
558    CA certificate expires in the near future.
559 */
560 void setCACertificateExpiryNearWarning( bool );
561
562 /*! \ingroup groupConfigSign
563    \brief Returns whether a warning should be emitted if
564    the CA certificate expires in the near future.
565 */
566 bool caCertificateExpiryNearWarning( void );
567
568     /*! \ingroup groupConfigSign
569       \brief Returns the number of days that are left until the
570       CA certificate of the specified certificate expires. 
571       \param certificate the certificate to check
572     */
573     int caCertificateDaysLeftToExpiry( const char* certificate );
574
575 /*! \ingroup groupConfigSign
576    \brief Specifies the number of days which a CA certificate must
577    be valid before it is considered to expire in the near
578    future.
579 */
580 void setCACertificateExpiryNearInterval( int );
581
582 /*! \ingroup groupConfigSign
583    \brief Returns the number of days which a CA certificate must
584             be valid before it is considered to expire in the near
585             future.
586 */
587 int caCertificateExpiryNearInterval( void );
588
589 /*! \ingroup groupConfigSign
590    \brief Specifies whether a warning should be emitted if the
591    root certificate expires in the near future.
592 */
593 void setRootCertificateExpiryNearWarning( bool );
594
595 /*! \ingroup groupConfigSign
596    \brief Returns whether a warning should be emitted if
597    the root certificate expires in the near future.
598 */
599 bool rootCertificateExpiryNearWarning( void );
600
601     /*! \ingroup groupConfigSign
602       \brief Returns the number of days that are left until the
603       root certificate of the specified certificate expires. 
604       \param certificate the certificate to check
605     */
606     int rootCertificateDaysLeftToExpiry( const char* certificate );
607
608 /*! \ingroup groupConfigSign
609    \brief Specifies the number of days which a root certificate must
610    be valid before it is considered to expire in the near
611    future.
612 */
613 void setRootCertificateExpiryNearInterval( int );
614
615 /*! \ingroup groupConfigSign
616    \brief Returns the number of days which a signature certificate must
617             be valid before it is considered to expire in the near
618             future.
619 */
620 int rootCertificateExpiryNearInterval( void );
621
622
623     
624
625 /*! \ingroup groupConfigCrypt
626    \brief This function returns an XML representation of a
627             configuration dialog for configuring encryption
628             handling.
629
630    The syntax is that of <filename>.ui</filename>
631             files as specified in the <emphasis>Imhotep</emphasis>
632             documentation. This function does not execute or show the
633             dialog in any way; this is up to the MUA. Also, what the
634             MUA makes of the information provided highly depends on
635             the MUA itself. A GUI-based MUA will probably create a
636             dialog window (possibly integrated into an existing
637             configuration dialog in the application), while a
638             terminal-based MUA might generate a series of questions or
639             a terminal based menu selection.
640 */
641 const char* encryptionConfigurationDialog( void );
642
643 /*! \ingroup groupConfigCrypt
644    \brief This function returns an XML representation of a
645             configuration dialog for selecting an encryption
646             algorithm.
647             
648    This will typically be used when the user wants
649           to select an encryption algorithm for one specific message only; the
650           defaults are set in the dialog returned by
651             encryptionConfigurationDialog().
652 */
653 const char* encryptionAlgorithmDialog( void );
654
655 /*! \ingroup groupConfigCrypt
656    \brief This function returns an XML representation of a
657             configuration dialog for selecting whether an email
658             message and its attachments should be encrypted.
659
660    This will typically be used when the
661             user wants to select an encryption key for one specific
662             message only; the defaults are set in the dialog returned
663             by encryptionConfigurationDialog().
664 */
665 const char* encryptionHandlingDialog( void );
666
667 /*! \ingroup groupConfigCrypt
668    \brief This function returns an XML representation of a
669             dialog that lets the user select the certificate to use
670             for encrypting.
671
672    If it was not possible to determine the
673             correct certificate from the information in the email
674             message, the user is presented with a list of possible
675             certificates to choose from. If a unique certificate was
676             found, this is presented to the user, who needs to confirm
677           the selection of the certificate. This procedure is repeated
678           for each recipient of the email message.
679 */
680 const char* encryptionReceiverDialog( void );
681
682 /*! \ingroup groupConfigCrypt
683    \brief Sets the algorithm used for encrypting.
684 */
685 void setEncryptionAlgorithm( EncryptionAlgorithm );
686
687 /*! \ingroup groupConfigCrypt
688    \brief Returns the algorithm used for encrypting.
689 */
690 EncryptionAlgorithm encryptionAlgorithm( void );
691
692 /*! \ingroup groupConfigCrypt
693    \brief Specifies whether email should be automatically
694             encrypted, encrypted after confirmation, encrypted after
695             confirmation for each part or not encrypted at all.
696 */
697 void setEncryptEmail( EncryptEmail );
698
699 /*! \ingroup groupConfigCrypt
700    \brief Returns whether email should be automatically
701             encrypted, encrypted after confirmation, encrypted after
702             confirmation for each part or not encrypted at all.
703 */
704 EncryptEmail encryptEmail( void );
705
706 /*! \ingroup groupConfigSign
707   \brief Specifies whether a warning should be emitted when the user
708   tries to send an email message unencrypted.
709 */
710 void setWarnSendUnencrypted( bool );
711
712
713 /*! \ingroup groupConfigSign
714   \brief Returns whether a warning should be emitted when the user
715   tries to send an email message unencrypted.
716 */
717 bool warnSendUnencrypted( void );    
718     
719
720 /*! \ingroup groupConfigCrypt
721    \brief Specifies whether encrypted email messages should be
722             stored encrypted or decrypted.
723 */
724 void setSaveMessagesEncrypted( bool );
725
726 /*! \ingroup groupConfigCrypt
727    \brief Returns whether encrypted email messages should be stored
728             encrypted or decrypted.
729 */
730 bool saveMessagesEncrypted( void );
731
732
733 /*! \ingroup groupConfigCrypt
734   \brief Specifies whether the certificate path should be checked
735   during encryption.
736 */
737 void setCheckCertificatePath( bool );
738
739 /*! \ingroup groupConfigCrypt
740   \brief Returns whether the certificate path should be checked
741   during encryption.
742 */
743 bool checkCertificatePath( void );
744
745     
746 /*! \ingroup groupConfigCrypt
747    \brief Specifies whether the certificate path should be
748             followed to the root certificate or whether locally stored
749             certificates may be used.
750 */
751 void setCheckEncryptionCertificatePathToRoot( bool );
752
753 /*! \ingroup groupConfigCrypt
754    \brief Returns whether the certificate path should be
755             followed to the root certificate or whether locally stored
756             certificates may be used.
757 */
758 bool checkEncryptionCertificatePathToRoot( void );
759
760     
761 /*! \ingroup groupConfigCrypt
762   \brief Specifies whether a warning should be emitted if the
763   certificate of the receiver expires in the near future.
764 */
765 void setReceiverCertificateExpiryNearWarning( bool );
766
767 /*! \ingroup groupConfigCrypt
768   \brief Returns whether a warning should be emitted if the
769   certificate of the receiver expires in the near future.
770 */
771 bool receiverCertificateExpiryNearWarning( void );
772     
773
774 /*! \ingroup groupConfigCrypt
775   \brief Specifies the number of days which a receiver certificate
776   must be valid before it is considered to expire in the near future.
777 */
778 void setReceiverCertificateExpiryNearWarningInterval( int );
779     
780 /*! \ingroup groupConfigCrypt
781   \brief Returns the number of days which a receiver certificate
782   must be valid before it is considered to expire in the near future.
783 */
784 int receiverCertificateExpiryNearWarningInterval( void );
785
786 /*! \ingroup groupConfigCrypt
787   \brief Specifies whether a warning should be emitted if 
788   a certificate in the chain expires in the near future.
789 */
790 void setCertificateInChainExpiryNearWarning( bool );
791
792     
793 /*! \ingroup groupConfigCrypt
794   \brief Returns whether a warning should be emitted if a
795   certificate in the chain expires in the near future.
796 */
797 bool certificateInChainExpiryNearWarning( void );
798
799     
800     
801 /*! \ingroup groupConfigCrypt
802   \brief Specifies the number of days which a certificate in the chain
803   must be valid before it is considered to expire in the near future.
804 */
805 void setCertificateInChainExpiryNearWarningInterval( int );
806
807 /*! \ingroup groupConfigCrypt
808   \brief Returns the number of days which a certificate in the chain
809   must be valid before it is considered to expire in the near future.
810 */
811 int certificateInChainExpiryNearWarningInterval( void );
812
813     
814 /*! \ingroup groupConfigCrypt
815   \brief Specifies whether a warning is emitted if the email address
816   of the receiver does not appear in the certificate.
817 */
818 void setReceiverEmailAddressNotInCertificateWarning( bool );    
819
820 /*! \ingroup groupConfigCrypt
821   \brief Returns whether a warning is emitted if the email address
822   of the receiver does not appear in the certificate.
823 */
824 bool receiverEmailAddressNotInCertificateWarning( void );
825
826
827 /*! \ingroup groupConfigCrypt
828    \brief Specifies whether certificate revocation lists should
829             be used.
830 */
831 void setEncryptionUseCRLs( bool );
832
833 /*! \ingroup groupConfigCrypt
834    \brief Returns whether certificate revocation lists should
835             be used.
836 */
837 bool encryptionUseCRLs( void );
838
839 /*! \ingroup groupConfigCrypt
840    \brief Specifies whether a warning should be emitted if any
841             of the certificates involved in the signing process
842             expires in the near future.
843 */
844 void setEncryptionCRLExpiryNearWarning( bool );
845
846 /*! \ingroup groupConfigCrypt
847    \brief Returns whether a warning should be emitted if any
848             of the certificates involved in the signing process
849             expires in the near future.
850 */
851 bool encryptionCRLExpiryNearWarning( void );
852
853 /*! \ingroup groupConfigCrypt
854    \brief Specifies the number of days which a certificate must
855             be valid before it is considered to expire in the near
856             future.
857 */
858 void setEncryptionCRLNearExpiryInterval( int );
859
860 /*! \ingroup groupConfigCrypt
861    \brief Returns the number of days which a certificate must
862             be valid before it is considered to expire in the near
863             future.
864 */
865 int encryptionCRLNearExpiryInterval( void );
866
867
868 /*! \ingroup groupConfigCrypt
869   \brief Returns the number of days the currently active certification
870   list is still valid. 
871 */
872 int encryptionCRLsDaysLeftToExpiry( void );
873
874
875
876 /*! \ingroup groupConfigDir
877    \brief This function returns an XML representation of a
878             configuration dialog for selecting a directory
879             server.
880 */
881 const char* directoryServiceConfigurationDialog( void );
882
883 /*! \ingroup groupConfigDir
884    \brief Lets you configure how certificates and certificate
885    revocation lists are retrieved (both locally and from directory
886    services).
887
888    Will mainly be used for restoring
889             configuration data; interactive configuration will be done
890             via the configuration dialog returned by
891             \c directoryServiceConfigurationDialog().
892 */
893 void appendDirectoryServer( const char* servername, int port,
894                             const char* description );
895
896
897
898
899 /*! \ingroup groupConfigDir
900 */
901 struct DirectoryServer {
902     char* servername;
903     int port;
904     char* description;
905 };
906
907
908 /*! \ingroup groupConfigDir
909    \brief Specifies a list of directory servers.
910
911    Will mainly be used for restoring
912             configuration data; interactive configuration will be done
913             via the configuration dialog returned by
914             \c directoryServiceConfigurationDialog().
915 */
916 void setDirectoryServers( struct DirectoryServer[], unsigned int size );
917
918 /*! \ingroup groupConfigDir
919    \brief Returns the list of directory servers.
920
921    Will mainly be used for saving configuration data; interactive
922             configuration will be done via the configuration dialog
923             returned by
924             \c directoryServiceConfigurationDialog().
925 */
926 struct DirectoryServer* directoryServers( int* numServers );
927
928 /*! \ingroup groupConfigDir
929    \brief Specifies whether certificates should be retrieved
930             from a directory server, only locally, or both.
931 */
932 void setCertificateSource( CertificateSource );
933
934 /*! \ingroup groupConfigDir
935    \brief Returns whether certificates should be retrieved
936             from a directory server, only locally, or both.
937 */
938 CertificateSource certificateSource( void );
939
940 /*! \ingroup groupConfigDir
941    \brief Specifies whether certificates should be retrieved
942             from a directory server, only locally, or both.
943 */
944 void setCRLSource( CertificateSource );
945
946 /*! \ingroup groupConfigDir
947    \brief Returns whether certificates should be retrieved
948             from a directory server, only locally, or both.
949 */
950 CertificateSource crlSource( void );
951
952
953 /*! \ingroup groupCertHand
954    \brief Returns \c true if and only if the
955           certificates in the certificate chain starting at
956           \c certificate are valid.
957
958    If \c level is non-null, the parameter contains
959           the degree of trust on a backend-specific scale. In an X.509
960           implementation, this will either be \c 1
961           (valid up to the root certificate) or \c 0
962           (not valid up to the root certificate).
963 */
964 bool certificateValidity( const char* certificate, int* level );
965
966
967 /*! \ingroup groupSignCryptAct
968    \brief Information record returned by signing and by encrypting
969    functions - this record should be used together with a
970    corresponding \c free_StructuringInfo() function call.
971
972    Use this information to compose a MIME object containing signed
973    and/or encrypted content (or to build a text frame around your
974    flat non-MIME message body, resp.)
975
976    <b>If</b> value returned in \c makeMimeObject is <b>TRUE</b> the
977    text strings returned in \c contentTypeMain and \c contentDispMain
978    and \c contentTEncMain (and, if required, \c content[..]Version and
979    \c bodyTextVersion and \c content[..]Sig) should be used to compose
980    a respective MIME object.<br>
981    If <b>FALSE</b> the texts returned in \c flatTextPrefix and
982    \c flatTextSeparator and \c flatTextPostfix are to be used instead.<br>
983    Allways <b>either</b> the \c content[..] and \c bodyTextVersion
984    parameters <b>or</b> the \c flatText[..] parameters are holding
985    valid data - never both of them may be used simultaneously
986    as plugins will just ignore the parameters not matching their
987    \c makeMimeObject setting.
988
989    When creating your MIME object please observe these common rules:
990    \li Parameters named \c contentType[..] and \c contentDisp[..] and
991    \c contentTEnc[..] will return the values for the respective MIME
992    headers 'Content-Type' and 'Content-Disposition' and
993    'Content-Transfer-Encoding'. The following applies to these parameters:
994    \li The relevant MIME part may <b>only</b> be created if the respective
995    \c contentType[..] parameter is holding a non-zero-length string. If the
996    \c contentType[..] parameter value is invalid or holding an empty string
997    the respective \c contentDisp[..] and \c contentTEnc[..] parameters
998    should be ignored.
999    \li If the respective \c contentDisp[..] or \c contentTEnc[..] parameter
1000    is NULL or holding a zero-length string it is up to you whether you want
1001    to add the relevant MIME header yourself, but since it in in the
1002    responsibility of the plugin implementors to provide you with all
1003    neccessary 'Content-[..]' header information you should <b>not need</b>
1004    to define them if they are not returned by the signing or encrypting
1005    function - otherwise this may be considered as a bug in the plugin and
1006    you could report the missing MIME header information to the address
1007    returned by the \c bugURL() function.
1008
1009    If \c makeMultiMime returns FALSE the \c contentTypeMain returned must
1010    not be altered but used to specify a single part mime object holding the
1011    code bloc, e.g. this is used for 'enveloped-data' single part MIME
1012    objects. In this case you should ignore both the \c content[..]Version
1013    and \c content[..]Code parameters.
1014
1015    If \c makeMultiMime returns TRUE also the following rules apply:
1016    \li If \c includeCleartext is TRUE you should include the cleartext
1017    as first part of our multipart MIME object, typically this is TRUE
1018    when signing mails but FALSE when encrypting.
1019    \li The \c contentTypeMain returned typically starts with
1020    "multipart/" while providing a "protocol" and a "micalg" parameter: just
1021    add an appropriate \c "; boundary=[your \c boundary \c string]" to get
1022    the complete Content-Type value to be used for the MIME object embedding
1023    both the signed part and the signature part (or - in case of
1024    encrypting - the version part and the code part, resp.).
1025    \li If \c contentTypeVersion is holding a non-zero-length string an
1026    additional MIME part must added immediately before the code part, this
1027    version part's MIME headers must have the unaltered values of
1028    \c contentTypeVersion and (if they are holding non-zero-length strings)
1029    \c contentDispVersion and \c contentTEncVersion, the unaltered contents
1030    of \c bodyTextVersion must be it's body.
1031    \li The value returned in \c contentTypeCode is specifying the complete
1032    Content-Type to be used for this multipart MIME object's signature part
1033    (or - in case of encrypting - for the code part following after the
1034    version part, resp.), you should not add/change/remove anything here
1035    but just use it's unaltered value for specifying the Content-Type header
1036    of the respective MIME part.
1037    \li The same applies to the \c contentDispCode value: just use it's
1038    unaltered value to specify the Content-Disposition header entry of
1039    the respective MIME part.
1040    \li The same applies to the \c contentTEncCode value: just use it's
1041    unaltered value to specify the Content-Transfer-Encoding header of
1042    the respective MIME part.
1043
1044    <b>If</b> value returned in \c makeMimeObject is <b>FALSE</b> the
1045    text strings returned in \c flatTextPrefix and \c flatTextPostfix
1046    should be used to build a frame around the cleartext and the code
1047    bloc holding the signature (or - in case of encrypting - the encoded
1048    data bloc, resp.).<br>
1049    If \c includeCleartext is TRUE this frame should also include the
1050    cleartext as first bloc, this bloc should be divided from the code bloc
1051    by the contents of \c flatTextSeparator - typically this is used for
1052    signing but not when encrypting.<br>
1053    If \c includeCleartext is FALSE you should ignore both the cleartext
1054    and the \c flatTextSeparator parameter.
1055
1056    <b>How to use StructuringInfo data in your program:</b>
1057    \li To compose a signed message please act as described below.
1058    \li For constructing an encrypted message just replace the
1059    \c signMessage() call by the respective \c encryptMessage() call
1060    and then proceed exactly the same way.
1061    \li In any case make <b>sure</b> to free your \c ciphertext <b>and</b>
1062    to call \c free_StructuringInfo() when you are done with processing
1063    the data returned by the signing (or encrypting, resp.) function.
1064
1065 \verbatim
1066
1067     char* ciphertext;
1068     StructuringInfo structInf;
1069
1070     if( ! signMessage( cleartext, &ciphertext, certificate,
1071                        &structuring ) ) {
1072
1073         myErrorDialog( "Error: could not sign the message!" );
1074
1075     } else {
1076       if( structInf.makeMimeObject ) {
1077
1078         // Build the main MIME object.
1079         // This is done by
1080         // using the header values returned in
1081         // structInf.contentTypeMain and in
1082         // structInf.contentDispMain and in
1083         // structInf.contentTEncMain.
1084         ..
1085
1086         if( ! structInf.makeMultiMime ) {
1087
1088           // Build the main MIME object's body.
1089           // This is done by
1090           // using the code bloc returned in
1091           // ciphertext.
1092           ..
1093
1094         } else {
1095
1096           // Build the encapsulated MIME parts.
1097           if( structInf.includeCleartext ) {
1098
1099             // Build a MIME part holding the cleartext.
1100             // This is done by
1101             // using the original cleartext's headers and by
1102             // taking it's original body text.
1103             ..
1104
1105           }
1106           if(    structInf.contentTypeVersion
1107               && 0 < strlen( structInf.contentTypeVersion ) ) {
1108
1109             // Build a MIME part holding the version information.
1110             // This is done by
1111             // using the header values returned in
1112             // structInf.contentTypeVersion and
1113             // structInf.contentDispVersion and
1114             // structInf.contentTEncVersion and by
1115             // taking the body contents returned in
1116             // structInf.bodyTextVersion.
1117             ..
1118
1119           }
1120           if(    structInf.contentTypeCode
1121               && 0 < strlen( structInf.contentTypeCode ) ) {
1122
1123             // Build a MIME part holding the code information.
1124             // This is done by
1125             // using the header values returned in
1126             // structInf.contentTypeCode and
1127             // structInf.contentDispCode and
1128             // structInf.contentTEncCode and by
1129             // taking the body contents returned in
1130             // ciphertext.
1131             ..
1132
1133           } else {
1134
1135             // Plugin error!
1136             myErrorDialog( "Error: Cryptography plugin returned a main"
1137                            "Content-Type=Multipart/.. but did not "
1138                            "specify the code bloc's Content-Type header."
1139                            "\nYou may report this bug:"
1140                            "\n" + cryptplug.bugURL() );
1141           }
1142         }
1143       } else  {
1144
1145         // Build a plain message body
1146         // based on the values returned in structInf.
1147         // Note: We do _not_ insert line breaks between the parts since
1148         //       it is the plugin job to provide us with ready-to-use
1149         //       texts containing all neccessary line breaks.
1150         strcpy( myMessageBody, structInf.plainTextPrefix );
1151         if( structInf.includeCleartext ) {
1152           strcat( myMessageBody, cleartext );
1153           strcat( myMessageBody, structInf.plainTextSeparator );
1154         }
1155         strcat( myMessageBody, *ciphertext );
1156         strcat( myMessageBody, structInf.plainTextPostfix );
1157       }
1158
1159       // free the memory that was allocated
1160       // for the ciphertext
1161       free( ciphertext );
1162
1163       // free the memory that was allocated
1164       // for our StructuringInfo's char* members
1165       free_StructuringInfo( &structuring );
1166     }
1167
1168 \endverbatim
1169
1170    \note Make sure to call \c free_StructuringInfo() when you are done
1171    with processing the StructuringInfo data!
1172
1173   \see free_StructuringInfo
1174   \see signMessage, encryptMessage, encryptAndSignMessage
1175 */
1176 struct StructuringInfo {
1177   bool includeCleartext;     /*!< specifies whether we should include the
1178                                   cleartext as first part of our multipart
1179                                   MIME object (or - for non-MIME
1180                                   messages - as flat text to be set before
1181                                   the ciphertext, resp.), typically this
1182                                   is TRUE when signing mails but FALSE
1183                                   when encrypting<br>
1184                                   (this parameter is relevant no matter
1185                                   whether \c makeMimeObject is TRUE or
1186                                   FALSE) */
1187   bool  makeMimeObject;      /*!< specifies whether we should create a MIME
1188                                   object or a flat text message body */
1189   // the following are used for MIME messages only
1190   bool  makeMultiMime;       /*!< specifies whether we should create a
1191                                   'Multipart' MIME object or a single part
1192                                   object, if FALSE only \c contentTypeMain,
1193                                   \c contentDispMain and \c contentTEncMain
1194                                   may be used and all other parameters have
1195                                   to be ignored<br>
1196                                   (ignore this parameter if \c makeMimeObject
1197                                   is FALSE) */
1198   char* contentTypeMain;     /*!< value of the main 'Content-Type'
1199                                   header<br>
1200                                   (ignore this parameter if \c makeMimeObject
1201                                   is FALSE) */
1202   char* contentDispMain;     /*!< value of the main 'Content-Disposition'
1203                                   header<br>
1204                                   (ignore this parameter if \c makeMimeObject
1205                                   is FALSE) */
1206   char* contentTEncMain;     /*!< value of the main
1207                                   'Content-TransferEncoding' header<br>
1208                                   (ignore this parameter if \c makeMimeObject
1209                                   is FALSE) */
1210   char* contentTypeVersion;  /*!< 'Content-Type' of the additional version
1211                                   part that might preceed the code part -
1212                                   if NULL or zero length no version part
1213                                   must be created<br>
1214                                   (ignore this parameter if either
1215                                   \c makeMimeObject or \c makeMultiMime
1216                                   is FALSE) */
1217   char* contentDispVersion;  /*!< 'Content-Disposition' of the additional
1218                                   preceeding the code part (only valid if
1219                                   \c contentTypeVersion holds a
1220                                   non-zero-length string)<br>
1221                                   (ignore this parameter if either
1222                                   \c makeMimeObject or \c makeMultiMime
1223                                   is FALSE or if \c contentTypeVersion does
1224                                   not return a non-zero-length string) */
1225   char* contentTEncVersion;  /*!< 'Content-Transfer-Encoding' of the
1226                                   additional version part (only valid if
1227                                   \c contentTypeVersion holds a
1228                                   non-zero-length string)<br>
1229                                   (ignore this parameter if either
1230                                   \c makeMimeObject or \c makeMultiMime
1231                                   is FALSE or if \c contentTypeVersion does
1232                                   not return a non-zero-length string) */
1233   char* bodyTextVersion;     /*!< body text of the additional version part
1234                                   (only valid if \c contentTypeVersion
1235                                   holds a non-zero-length string)<br>
1236                                   (ignore this parameter if either
1237                                   \c makeMimeObject or \c makeMultiMime
1238                                   is FALSE or if \c contentTypeVersion does
1239                                   not return a non-zero-length string) */
1240   char* contentTypeCode;     /*!< 'Content-Type' of the code part holding
1241                                   the signature code (or the encrypted
1242                                   data, resp.)<br>
1243                                   (ignore this parameter if either
1244                                   \c makeMimeObject or \c makeMultiMime
1245                                   is FALSE) */
1246   char* contentDispCode;     /*!< 'Content-Disposition' of the code part<br>
1247                                   (ignore this parameter if either
1248                                   \c makeMimeObject or \c makeMultiMime
1249                                   is FALSE or if \c contentTypeCode does
1250                                   not return a non-zero-length string) */
1251   char* contentTEncCode;     /*!< 'Content-Type' of the code part<br>
1252                                   (ignore this parameter if either
1253                                   \c makeMimeObject or \c makeMultiMime
1254                                   is FALSE or if \c contentTypeCode does
1255                                   not return a non-zero-length string) */
1256   // the following are used for flat non-MIME messages only
1257   char* flatTextPrefix;      /*!< text to preceed the main text (or the
1258                                   code bloc containing the encrypted main
1259                                   text, resp.)<br>
1260                                   (ignore this parameter if
1261                                   \c makeMimeObject is TRUE) */
1262   char* flatTextSeparator;   /*!< text to be put between the main text and
1263                                   the signature code bloc (not used when
1264                                   encrypting)<br>
1265                                   (ignore this parameter if
1266                                   \c makeMimeObject is TRUE or if
1267                                   \c includeCleartext is FALSE) */
1268   char* flatTextPostfix;     /*!< text to follow the signature code bloc
1269                                   (or the encrypted data bloc, resp.)<br>
1270                                   (ignore this parameter if
1271                                   \c makeMimeObject is TRUE) */
1272 };
1273
1274
1275 /*! \ingroup groupAdUsoInterno
1276     \brief If you are not planning to write your own cryptography
1277     plugin <b>you should ignore this</b> function!
1278
1279     Usage of this function is depreciated for plugin users but highly
1280     recommended for plugin implementors since this is an internal
1281     function for initializing all char* members of a \c StructuringInfo
1282     struct.<br>
1283     This function <b>must</b> be called in <b>any</b> plugin's
1284     implementations of the following functions:
1285
1286     \c signMessage() <br>
1287     \c encryptMessage() <br>
1288     \c encryptAndSignMessage()
1289
1290     Calling this function makes sure the corresponding
1291     \c free_StructuringInfo() calls which will be embedded by
1292     your plugin's users into their code will be able to
1293     determine which of the char* members belonging to the
1294     respective's StructuringInfo had been allocated memory
1295     for during previous signing or encrypting actions.
1296
1297     \see free_StructuringInfo, StructuringInfo
1298     \see signMessage, encryptMessage, encryptAndSignMessage
1299 */
1300   void init_StructuringInfo( struct StructuringInfo* s )
1301   {
1302     if( ! s ) return;
1303
1304     s->includeCleartext = false;
1305
1306     s->makeMimeObject = false;
1307     s->makeMultiMime = false;
1308
1309     s->contentTypeMain = 0;
1310     s->contentDispMain = 0;
1311     s->contentTEncMain = 0;
1312
1313     s->contentTypeVersion = 0;
1314     s->contentDispVersion = 0;
1315     s->contentTEncVersion = 0;
1316     s->bodyTextVersion = 0;
1317
1318     s->contentTypeCode = 0;
1319     s->contentDispCode = 0;
1320     s->contentTEncCode = 0;
1321
1322     s->flatTextPrefix = 0;
1323     s->flatTextSeparator = 0;
1324     s->flatTextPostfix = 0;
1325   }
1326
1327 /*! \ingroup groupSignCryptAct
1328     \brief Important method for freeing all memory that was allocated
1329     for the char* members of a \c StructuringInfo struct - use
1330     this function after <b>each</b> signing or encrypting function
1331     call.
1332
1333     \note Even when intending to call \c encryptMessage() immediately
1334     after having called \c signMessage() you first <b>must</b> call
1335     the \c free_StructuringInfo() function to make sure all memory is
1336     set free that was allocated for your StructuringInfo's char* members
1337     by the \c signMessage() function!
1338
1339     \see StructuringInfo
1340 */
1341   void free_StructuringInfo( struct StructuringInfo* s )
1342   {
1343     if( ! s ) return;
1344     if( s->contentTypeMain )    free( s->contentTypeMain );
1345     if( s->contentDispMain )    free( s->contentDispMain );
1346     if( s->contentTEncMain )    free( s->contentTEncMain );
1347     if( s->contentTypeVersion ) free( s->contentTypeVersion );
1348     if( s->contentDispVersion ) free( s->contentDispVersion );
1349     if( s->contentTEncVersion ) free( s->contentTEncVersion );
1350     if( s->bodyTextVersion )    free( s->bodyTextVersion );
1351     if( s->contentTypeCode )    free( s->contentTypeCode );
1352     if( s->contentDispCode )    free( s->contentDispCode );
1353     if( s->contentTEncCode )    free( s->contentTEncCode );
1354     if( s->flatTextPrefix )     free( s->flatTextPrefix );
1355     if( s->flatTextSeparator )  free( s->flatTextSeparator );
1356     if( s->flatTextPostfix )    free( s->flatTextPostfix );
1357   }
1358
1359
1360 /*! \ingroup groupSignAct
1361    \brief Signs a message \c cleartext and returns
1362           in \c *ciphertext the signature data bloc that
1363           is to be added to the message.
1364
1365    The signature role is specified by \c certificate.
1366    If \c certificate is \c NULL, the default certificate is used.
1367
1368    If the message could be signed, the function returns
1369           \c true, otherwise
1370           \c false.
1371
1372    Use the StructuringInfo data returned in parameter \c structuring
1373    to find out how to build the respective MIME object (or the plain
1374    text message body, resp.).
1375
1376    \note The function allocates memory for the \c *ciphertext, so
1377          make sure you set free that memory when no longer needing
1378          it (as shown in example code provided with documentation
1379          of the struct \c StructuringInfo).
1380
1381    \note The function also allocates memory for some char* members
1382     of the StructuringInfo* parameter that you are providing,
1383     therefore you <b>must</b> call the \c free_StructuringInfo() function
1384     to make sure all memory is set free that was allocated. This must be
1385     done <b>before</b> calling the next cryptography function - even if
1386     you intend to call \c encryptMessage() immediately after
1387     \c signMessage().
1388
1389    \see StructuringInfo, free_StructuringInfo
1390 */
1391 bool signMessage( const char*  cleartext,
1392                   const char** ciphertext,
1393                   const char*  certificate,
1394                   struct StructuringInfo* structuring );
1395
1396
1397 /*! \ingroup groupSignAct
1398  */
1399 struct SignatureMetaDataExtendedInfo
1400 {
1401     struct tm* creation_time;
1402     char* status_text;
1403     char* fingerprint;
1404 };
1405
1406 /*! \ingroup groupSignAct
1407 */
1408 struct SignatureMetaData {
1409     char* status;
1410     struct SignatureMetaDataExtendedInfo* extended_info;
1411     int extended_info_count;
1412     char* nota_xml;
1413     int status_code;
1414 };
1415
1416 /*! \ingroup groupSignAct
1417    \brief Checks whether the signature of a message is
1418           valid. \c ciphertext specifies the signed message
1419           as it was received by the MUA, \c signaturetext is the
1420           signature itself.
1421
1422    Depending on the configuration, MUAs might not need to use this.
1423    If \c sigmeta is non-null, the
1424           \c SignatureMetaData object pointed to will
1425           contain meta information about the signature after the
1426           function call.
1427 */
1428 bool checkMessageSignature( const char* ciphertext,
1429                             const char* signaturetext,
1430                             struct SignatureMetaData* sigmeta );
1431
1432 /*! \ingroup groupSignAct
1433    \brief Stores the certificates that follow with the message
1434           \c ciphertext locally.
1435 */
1436 bool storeCertificatesFromMessage( const char* ciphertext );
1437
1438
1439 /*! \ingroup groupCryptAct
1440    \brief Encrypts an email message in
1441           \c cleartext according to the \c addressee and
1442           the current settings (algorithm, etc.) and
1443           returns the encoded data bloc in \c *ciphertext.
1444
1445    If the message could be encrypted, the function returns
1446           \c true, otherwise
1447           \c false.
1448
1449    Use the StructuringInfo data returned in parameter \c structuring
1450    to find out how to build the respective MIME object (or the plain
1451    text message body, resp.).
1452
1453    \note The function allocates memory for the \c *ciphertext, so
1454          make sure you set free that memory when no longer needing
1455          it (as shown in example code provided with documentation
1456          of the struct \c StructuringInfo).
1457
1458    \note The function also allocates memory for some char* members
1459     of the StructuringInfo* parameter that you are providing,
1460     therefore you <b>must</b> call the \c free_StructuringInfo() function
1461     to make sure all memory is set free that was allocated. This must be
1462     done <b>before</b> calling the next cryptography function!
1463
1464    \see StructuringInfo, free_StructuringInfo
1465 */
1466 bool encryptMessage( const char*  cleartext,
1467                      const char** ciphertext,
1468                      const char*  addressee,
1469                      struct StructuringInfo* structuring );
1470
1471
1472 /*! \ingroup groupCryptAct
1473    \brief Combines the functionality of
1474           \c encryptMessage() and
1475           \c signMessage().
1476
1477    If \c certificate is \c NULL,
1478    the default certificate will be used.
1479
1480    If the message could be signed and encrypted, the function returns
1481           \c true, otherwise
1482           \c false.
1483
1484    Use the StructuringInfo data returned in parameter \c structuring
1485    to find out how to build the respective MIME object (or the plain
1486    text message body, resp.).
1487
1488    \note The function allocates memory for the \c *ciphertext, so
1489          make sure you set free that memory when no longer needing
1490          it (as shown in example code provided with documentation
1491          of the struct \c StructuringInfo).
1492
1493    \note The function also allocates memory for some char* members
1494     of the StructuringInfo* parameter that you are providing,
1495     therefore you <b>must</b> call the \c free_StructuringInfo() function
1496     to make sure all memory is set free that was allocated. This must be
1497     done <b>before</b> calling the next cryptography function!
1498
1499    \see StructuringInfo, free_StructuringInfo
1500 */
1501 bool encryptAndSignMessage( const char* cleartext,
1502                             const char** ciphertext,
1503                             const char* certificate,
1504                             struct StructuringInfo* structuring );
1505
1506 /*! \ingroup groupCryptAct
1507    \brief Tries to decrypt an email message
1508           \c ciphertext and returns the decrypted
1509           message in \c cleartext.
1510
1511    The \c certificate is used for decryption. If
1512           the message could be decrypted, the function returns
1513           \c true, otherwise
1514           \c false.
1515 */
1516 bool decryptMessage( const char* ciphertext, const
1517           char** cleartext, const char* certificate );
1518
1519 /*! \ingroup groupCryptAct
1520    \brief Combines the functionality of
1521           \c checkMessageSignature() and
1522           \c decryptMessage().
1523
1524    If \c certificate is \c NULL,
1525    the default certificate will be used.
1526    If \c sigmeta is non-null, the \c SignatureMetaData
1527    object pointed to will contain meta information about
1528    the signature after the function call.
1529 */
1530 bool decryptAndCheckMessage( const char* ciphertext,
1531                              const char** cleartext,
1532                              const char* certificate,
1533                              struct SignatureMetaData* sigmeta );
1534
1535
1536 /*! \ingroup groupCertAct
1537    \brief This function returns an XML representation of a dialog
1538           that can be used to fill in the data for requesting a
1539           certificate (which in turn is done with the function
1540           \c requestCertificate() described
1541           next.
1542 */
1543 const char* requestCertificateDialog( void );
1544
1545 /*! \ingroup groupCertAct
1546    \brief Generates a prototype certificate with the data provided
1547         in the first four parameters and sends it via email to the CA
1548           specified in \c ca_address.
1549 */
1550 bool requestDecentralCertificate( const char* name, const char*
1551           email, const char* organization, const char* department,
1552           const char* ca_address );
1553
1554 /*! \ingroup groupCertAct
1555    \brief Requests a certificate in a PSE from the CA
1556           specified in \c ca_address.
1557 */
1558 bool requestCentralCertificateAndPSE( const char* name,
1559           const char* email, const char* organization, const char* department,
1560           const char* ca_address );
1561
1562 /*! \ingroup groupCertAct
1563    \brief Creates a local PSE.
1564 */
1565 bool createPSE( void );
1566
1567 /*! \ingroup groupCertAct
1568    \brief Parses and adds a certificate returned by a CA upon
1569           request with
1570           \c requestDecentralCertificate() or
1571           \c requestCentralCertificate().
1572
1573    If the certificate was requested with
1574           \c requestCentralCertificate(), the
1575           certificate returned will come complete with a PSE which is
1576           also registered with this method.
1577 */
1578 bool registerCertificate( const char* );
1579
1580 /*! \ingroup groupCertAct
1581    \brief Requests the prolongation of the certificate
1582           \c certificate from the CA
1583           \c ca_address.
1584 */
1585 bool requestCertificateProlongation( const char*
1586           certificate, const char* ca_address );
1587
1588 /*! \ingroup groupCertAct
1589    \brief Returns an HTML 2-formatted string that describes the
1590           certificate chain of the user's certificate.
1591           
1592    Data displayed is at least the issuer of the certificate, the serial number
1593         of the certificate, the owner of the certificate, the checksum
1594         of the certificate, the validity duration of the certificate,
1595           the usage of the certificate, and the contained email
1596           addresses, if any.
1597 */
1598 const char* certificateChain( void );
1599
1600 /*! \ingroup groupCertAct
1601    \brief Deletes the specified user certificate from the current
1602           PSE.
1603 */
1604 bool deleteCertificate( const char* certificate );
1605
1606 /*! \ingroup groupCertAct
1607    \brief Archives the specified user certificate in the current PSE.
1608
1609    The certificate cannot be used any longer after this
1610           operation unless it is unarchived.
1611 */
1612 bool archiveCertificate( const char* certificate );
1613
1614
1615 /*! \ingroup groupCRLAct
1616    \brief Returns a HTML 2-formatted string that describes the
1617           CRL, suitable for display in the MUA.
1618 */
1619 const char* displayCRL( void );
1620
1621 /*! \ingroup groupCRLAct
1622    \brief Manually update the CRL. CRLs will also be automatically
1623         updated on demand by the backend.
1624         
1625    If there is a local version of a CRL saved, it will be overwritten
1626    with the new CRL from the CA.
1627 */
1628 void updateCRL( void );
1629
1630 #ifdef __cplusplus
1631 }
1632 #endif
1633 #endif /*CRYPTPLUG_H*/
1634