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