Corrected code status error from previous wrong CVS comits
[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 /*! \defgroup groupSignAct Signature Actions
122
123     This section describes methods that are used for working
124     with signatures.
125 */
126
127 /*! \defgroup groupCryptAct Encryption and Decryption
128
129     The following methods are used to encrypt and decrypt
130     email messages.
131 */
132
133 /*! \defgroup groupCertAct Certificate Handling Actions
134
135     The functions in this section provide local certificate management.
136 */
137
138 /*! \defgroup groupCRLAct CRL Handling Actions
139
140     This section describes functions for managing CRLs.
141 */
142
143
144
145
146
147 // dummy values:
148 typedef enum {
149   CryptPlugFeat_undef             = 0,
150
151   CryptPlugFeat_SignMessages      = 1,
152   CryptPlugFeat_VerifySignatures  = 2,
153   CryptPlugFeat_EncryptMessages   = 3,
154   CryptPlugFeat_DecryptMessages   = 4   // more to follow ...
155 } Feature;
156
157 // dummy values
158 typedef enum {
159   PinRequest_undef            = 0,
160
161   PinRequest_Always          = 1,
162   PinRequest_WhenAddingCerts = 2,
163   PinRequest_AlwaysWhenSigning = 3,
164   PinRequest_OncePerSession   = 4,
165   PinRequest_AfterMinutes     = 5
166 } PinRequests;
167
168 // dummy values:
169 typedef enum {
170   SendCert_undef              = 0,
171
172   SendCert_DontSend           = 1,
173   SendCert_SendOwn            = 2,
174   SendCert_SendChainWithoutRoot = 3,
175   SendCert_SendChainWithRoot  = 4
176 } SendCertificates;
177
178 // dummy values:
179 typedef enum {
180   SignAlg_undef               = 0,
181
182   SignAlg_SHA1                = 1
183 } SignatureAlgorithm;
184
185
186
187 typedef enum {
188   EncryptAlg_undef            = 0,
189
190   EncryptAlg_RSA              = 1,
191   EncryptAlg_SHA1             = 2,
192   EncryptAlg_TripleDES        = 3
193 } EncryptionAlgorithm;
194
195 typedef enum {
196   SignEmail_undef             = 0,
197
198   SignEmail_SignAll           = 1,
199   SignEmail_Ask               = 2,
200   SignEmail_DontSign          = 3
201 } SignEmail;
202
203 typedef enum {
204   EncryptEmail_undef          = 0,
205
206   EncryptEmail_EncryptAll     = 1,
207   EncryptEmail_Ask            = 2,
208   EncryptEmail_DontEncrypt    = 3
209 } EncryptEmail;
210
211 typedef enum {
212   CertSrc_undef               = 0,
213
214   CertSrc_Server              = 1,
215   CertSrc_Local               = 2,
216   CertSrc_ServerLocal         = CertSrc_Server | CertSrc_Local
217 } CertificateSource;
218
219
220
221
222
223
224 /*! \ingroup groupGeneral
225     \brief This function sets up all internal structures.
226
227    Plugins that need no initialization should provide an empty
228    implementation. The method returns \c true if the initialization was
229    successful and \c false otherwise. Before this function is called,
230    no other plugin functions should be called; the behavior is
231    undefined in this case.
232
233    \note This function <b>must</b> be implemented by each plug-in using
234    this API specification.
235 */
236 bool initialize( void );
237
238 /*! \ingroup groupGeneral
239     \brief This function frees all internal structures.
240
241     Plugins that do not keep any internal structures should provide an
242     empty implementation. After this function has been called,
243     no other plugin functions should be called; the behavior is
244     undefined in this case.
245
246    \note This function <b>must</b> be implemented by each plug-in using
247    this API specification.
248 */
249 void deinitialize( void );
250
251 /*! \ingroup groupGeneral
252    \brief This function returns \c true if the
253           specified feature is available in the plugin, and
254           \c false otherwise.
255
256    Not all plugins will support all features; a complete Sphinx
257    implementation will support all features contained in the enum,
258    however.
259
260    \note This function <b>must</b> be implemented by each plug-in using
261    this API specification.
262 */
263 bool hasFeature( Feature );
264
265
266 /*! \ingroup groupDisplay
267    \brief Returns stationery to indicate unsafe emails.
268 */
269 void unsafeStationery( void** pixmap, const char** menutext, char* accel,
270           const char** tooltip, const char** statusbartext );
271
272 /*! \ingroup groupDisplay
273    \brief Returns stationery to indicate signed emails.
274 */
275 void signedStationery( void** pixmap, const char** menutext, char* accel,
276           const char** tooltip, const char** statusbartext );
277
278 /*! \ingroup groupDisplay
279    \brief Returns stationery to indicate encrypted emails.
280 */
281 void encryptedStationery( void** pixmap, const char**
282           menutext, char* accel,
283           const char** tooltip, const char** statusbartext );
284
285 /*! \ingroup groupDisplay
286    \brief Returns stationery to indicate signed and encrypted emails.
287 */
288 void signedEncryptedStationery( void** pixmap, const char**
289           menutext, char* accel,
290           const char** tooltip, const char** statusbartext );
291
292 /*! \ingroup groupConfigSign
293    \brief This function returns an XML representation of a
294             configuration dialog for configuring signature
295             handling.
296             
297    The syntax is that of <filename>.ui</filename>
298             files as specified in the <emphasis>Imhotep</emphasis>
299             documentation. This function does not execute or show the
300             dialog in any way; this is up to the MUA. Also, what the
301             MUA makes of the information provided highly depends on
302             the MUA itself. A GUI-based MUA will probably create a
303             dialog window (possibly integrated into an existing
304             configuration dialog in the application), while a
305             terminal-based MUA might generate a series of questions or
306             a terminal based menu selection.
307 */
308 const char* signatureConfigurationDialog( void );
309
310 /*! \ingroup groupConfigSign
311    \brief This function returns an XML representation of a
312             configuration dialog for selecting a signature key.
313             
314    This will typically be used when the user wants to select a
315             signature key for one specific message only; the defaults
316             are set in the dialog returned by
317             signatureConfigurationDialog().
318 */
319 const char* signatureKeySelectionDialog( void );
320
321 /*! \ingroup groupConfigSign
322    \brief This function returns an XML representation of a
323             configuration dialog for selecting a signature
324             algorithm.
325
326    This will typically be used when the user wants
327           to select a signature algorithm for one specific message only; the
328           defaults are set in the dialog returned by
329             signatureConfigurationDialog().
330 */
331 const char* signatureAlgorithmDialog( void );
332
333 /*! \ingroup groupConfigSign
334    \brief This function returns an XML representation of a
335             configuration dialog for selecting whether an email
336             message and its attachments should be sent with or
337             without signatures.
338
339    This will typically be used when the
340             user wants to select a signature key for one specific
341             message only; the defaults are set in the dialog returned
342             by signatureConfigurationDialog().
343 */
344 const char* signatureHandlingDialog( void );
345
346 /*! \ingroup groupConfigSign
347    \brief Sets the signature key certificate that identifies the
348           role of the signer.
349 */
350 void setSignatureKeyCertificate( const char* certificate );
351
352 /*! \ingroup groupConfigSign
353    \brief Returns the signature key certificate that identifies
354             the role of the signer.
355 */
356 const char* signatureKeyCertificate( void );
357
358 /*! \ingroup groupConfigSign
359    \brief Sets the algorithm used for signing.
360 */
361 void setSignatureAlgorithm( SignatureAlgorithm );
362
363 /*! \ingroup groupConfigSign
364    \brief Returns the algorithm used for signing.
365 */
366 SignatureAlgorithm signatureAlgorithm( void );
367
368 /*! \ingroup groupConfigSign
369    \brief Sets which certificates should be sent with the
370             message.
371 */
372 void setSendCertificates( SendCertificates );
373 /*! \ingroup groupConfigSign
374    \brief Returns which certificates should be sent with the
375             message.
376 */
377 SendCertificates sendCertificates( void );
378
379 /*! \ingroup groupConfigSign
380    \brief Specifies whether email should be automatically
381             signed, signed after confirmation, signed after
382             confirmation for each part or not signed at all.
383 */
384 void setSignEmail( SignEmail );
385
386 /*! \ingroup groupConfigSign
387    \brief Returns whether email should be automatically
388             signed, signed after confirmation, signed after
389             confirmation for each part or not signed at all.
390 */
391 SignEmail signEmail( void );
392
393     
394 /*! \ingroup groupConfigSign
395   \brief Specifies whether a warning should be emitted when the user
396   tries to send an email message unsigned.
397 */
398 void setWarnSendUnsigned( bool );    
399
400     
401 /*! \ingroup groupConfigSign
402   \brief Returns whether a warning should be emitted when the user
403   tries to send an email message unsigned.
404 */
405 bool warnSendUnsigned( void );    
406     
407     
408 /*! \ingroup groupConfigSign
409    \brief Specifies whether sent email messages should be stored
410           with or without their signatures.
411 */
412 void setSaveSentSignatures( bool );
413
414 /*! \ingroup groupConfigSign
415    \brief Returns whether sent email messages should be stored
416             with or without their signatures.
417 */
418 bool saveSentSignatures( void );
419
420 /*! \ingroup groupConfigSign
421    \brief Specifies whether a warning should be emitted if the
422             email address of the sender is not contained in the
423             certificate.
424 */
425 void setWarnNoCertificate( bool );
426
427 /*! \ingroup groupConfigSign
428    \brief Returns whether a warning should be emitted if the
429             email address of the sender is not contained in the
430             certificate.
431 */
432 bool warnNoCertificate( void );
433
434 /*! \ingroup groupConfigSign
435    \brief Specifies how often the PIN is requested when
436             accessing the secret signature key.
437 */
438 void setNumPINRequests( PinRequests );
439
440 /*! \ingroup groupConfigSign
441    \brief Returns how often the PIN is requested when
442             accessing the secret signature key.
443 */
444 PinRequests numPINRequests( void );
445
446 /*! \ingroup groupConfigSign
447   \brief Specifies the interval in minutes the PIN must be reentered if
448   numPINRequests() is PinRequest_AfterMinutes.
449 */
450 void setNumPINRequestsInterval( int );
451
452     
453 /*! \ingroup groupConfigSign
454   \brief Returns the interval in minutes the PIN must be reentered if
455   numPINRequests() is PinRequest_AfterMinutes.
456 */
457 int numPINRequestsInterval( void );
458
459
460 /*! \ingroup groupConfigSign
461    \brief Specifies whether the certificate path should be
462             followed to the root certificate or whether locally stored
463             certificates may be used.
464 */
465 void setCheckSignatureCertificatePathToRoot( bool );
466
467 /*! \ingroup groupConfigSign
468    \brief Returns whether the certificate path should be
469             followed to the root certificate or whether locally stored
470             certificates may be used.
471 */
472 bool checkSignatureCertificatePathToRoot( void );
473
474 /*! \ingroup groupConfigSign
475    \brief Specifies whether certificate revocation lists should
476             be used.
477 */
478 void setSignatureUseCRLs( bool );
479
480 /*! \ingroup groupConfigSign
481    \brief Returns whether certificate revocation lists should
482             be used.
483 */
484 bool signatureUseCRLs( void );
485
486 /*! \ingroup groupConfigSign
487    \brief Specifies whether a warning should be emitted if the
488    signature certificate expires in the near future.
489 */
490 void setSignatureCertificateExpiryNearWarning( bool );
491
492 /*! \ingroup groupConfigSign
493    \brief Returns whether a warning should be emitted if
494    the signature certificate expires in the near future.
495 */
496 bool signatureCertificateExpiryNearWarning( void );
497
498 /*! \ingroup groupConfigSign
499    \brief Specifies the number of days which a signature certificate must
500    be valid before it is considered to expire in the near
501    future.
502 */
503 void setSignatureCertificateExpiryNearInterval( int );
504
505 /*! \ingroup groupConfigSign
506    \brief Returns the number of days which a signature certificate must
507             be valid before it is considered to expire in the near
508             future.
509 */
510 int signatureCertificateExpiryNearInterval( void );
511
512 /*! \ingroup groupConfigSign
513    \brief Specifies whether a warning should be emitted if the
514    CA certificate expires in the near future.
515 */
516 void setCACertificateExpiryNearWarning( bool );
517
518 /*! \ingroup groupConfigSign
519    \brief Returns whether a warning should be emitted if
520    the CA certificate expires in the near future.
521 */
522 bool caCertificateExpiryNearWarning( void );
523
524 /*! \ingroup groupConfigSign
525    \brief Specifies the number of days which a CA certificate must
526    be valid before it is considered to expire in the near
527    future.
528 */
529 void setCACertificateExpiryNearInterval( int );
530
531 /*! \ingroup groupConfigSign
532    \brief Returns the number of days which a CA certificate must
533             be valid before it is considered to expire in the near
534             future.
535 */
536 int caCertificateExpiryNearInterval( void );
537
538 /*! \ingroup groupConfigSign
539    \brief Specifies whether a warning should be emitted if the
540    root certificate expires in the near future.
541 */
542 void setRootCertificateExpiryNearWarning( bool );
543
544 /*! \ingroup groupConfigSign
545    \brief Returns whether a warning should be emitted if
546    the root certificate expires in the near future.
547 */
548 bool rootCertificateExpiryNearWarning( void );
549
550 /*! \ingroup groupConfigSign
551    \brief Specifies the number of days which a root certificate must
552    be valid before it is considered to expire in the near
553    future.
554 */
555 void setRootCertificateExpiryNearInterval( int );
556
557 /*! \ingroup groupConfigSign
558    \brief Returns the number of days which a signature certificate must
559             be valid before it is considered to expire in the near
560             future.
561 */
562 int rootCertificateExpiryNearInterval( void );
563
564     
565     
566
567 /*! \ingroup groupConfigCrypt
568    \brief This function returns an XML representation of a
569             configuration dialog for configuring encryption
570             handling.
571             
572    The syntax is that of <filename>.ui</filename>
573             files as specified in the <emphasis>Imhotep</emphasis>
574             documentation. This function does not execute or show the
575             dialog in any way; this is up to the MUA. Also, what the
576             MUA makes of the information provided highly depends on
577             the MUA itself. A GUI-based MUA will probably create a
578             dialog window (possibly integrated into an existing
579             configuration dialog in the application), while a
580             terminal-based MUA might generate a series of questions or
581             a terminal based menu selection.
582 */
583 const char* encryptionConfigurationDialog( void );
584
585 /*! \ingroup groupConfigCrypt
586    \brief This function returns an XML representation of a
587             configuration dialog for selecting an encryption
588             algorithm.
589             
590    This will typically be used when the user wants
591           to select an encryption algorithm for one specific message only; the
592           defaults are set in the dialog returned by
593             encryptionConfigurationDialog().
594 */
595 const char* encryptionAlgorithmDialog( void );
596
597 /*! \ingroup groupConfigCrypt
598    \brief This function returns an XML representation of a
599             configuration dialog for selecting whether an email
600             message and its attachments should be encrypted.
601
602    This will typically be used when the
603             user wants to select an encryption key for one specific
604             message only; the defaults are set in the dialog returned
605             by encryptionConfigurationDialog().
606 */
607 const char* encryptionHandlingDialog( void );
608
609 /*! \ingroup groupConfigCrypt
610    \brief This function returns an XML representation of a
611             dialog that lets the user select the certificate to use
612             for encrypting.
613             
614    If it was not possible to determine the
615             correct certificate from the information in the email
616             message, the user is presented with a list of possible
617             certificates to choose from. If a unique certificate was
618             found, this is presented to the user, who needs to confirm
619           the selection of the certificate. This procedure is repeated
620           for each recipient of the email message.
621 */
622 const char* encryptionReceiverDialog( void );
623
624 /*! \ingroup groupConfigCrypt
625    \brief Sets the algorithm used for encrypting.
626 */
627 void setEncryptionAlgorithm( EncryptionAlgorithm );
628
629 /*! \ingroup groupConfigCrypt
630    \brief Returns the algorithm used for encrypting.
631 */
632 EncryptionAlgorithm encryptionAlgorithm( void );
633
634 /*! \ingroup groupConfigCrypt
635    \brief Specifies whether email should be automatically
636             encrypted, encrypted after confirmation, encrypted after
637             confirmation for each part or not encrypted at all.
638 */
639 void setEncryptEmail( EncryptEmail );
640
641 /*! \ingroup groupConfigCrypt
642    \brief Returns whether email should be automatically
643             encrypted, encrypted after confirmation, encrypted after
644             confirmation for each part or not encrypted at all.
645 */
646 EncryptEmail encryptEmail( void );
647
648 /*! \ingroup groupConfigSign
649   \brief Specifies whether a warning should be emitted when the user
650   tries to send an email message unencrypted.
651 */
652 void setWarnSendUnencrypted( bool );    
653
654     
655 /*! \ingroup groupConfigSign
656   \brief Returns whether a warning should be emitted when the user
657   tries to send an email message unencrypted.
658 */
659 bool warnSendUnencrypted( void );    
660     
661     
662 /*! \ingroup groupConfigCrypt
663    \brief Specifies whether encrypted email messages should be
664             stored encrypted or decrypted.
665 */
666 void setSaveMessagesEncrypted( bool );
667
668 /*! \ingroup groupConfigCrypt
669    \brief Returns whether encrypted email messages should be stored
670             encrypted or decrypted.
671 */
672 bool saveMessagesEncrypted( void );
673
674
675 /*! \ingroup groupConfigCrypt
676   \brief Specifies whether the certificate path should be checked
677   during encryption.
678 */
679 void setCheckCertificatePath( bool );
680
681 /*! \ingroup groupConfigCrypt
682   \brief Returns whether the certificate path should be checked
683   during encryption.
684 */
685 bool checkCertificatePath( void );
686
687     
688 /*! \ingroup groupConfigCrypt
689    \brief Specifies whether the certificate path should be
690             followed to the root certificate or whether locally stored
691             certificates may be used.
692 */
693 void setCheckEncryptionCertificatePathToRoot( bool );
694
695 /*! \ingroup groupConfigCrypt
696    \brief Returns whether the certificate path should be
697             followed to the root certificate or whether locally stored
698             certificates may be used.
699 */
700 bool checkEncryptionCertificatePathToRoot( void );
701
702     
703 /*! \ingroup groupConfigCrypt
704   \brief Specifies whether a warning should be emitted if the
705   certificate of the receiver expires in the near future.
706 */
707 void setReceiverCertificateExpiryNearWarning( bool );
708
709 /*! \ingroup groupConfigCrypt
710   \brief Returns whether a warning should be emitted if the
711   certificate of the receiver expires in the near future.
712 */
713 bool receiverCertificateExpiryNearWarning( void );
714     
715     
716 /*! \ingroup groupConfigCrypt
717   \brief Specifies the number of days which a receiver certificate
718   must be valid before it is considered to expire in the near future.
719 */
720 void setReceiverCertificateExpiryNearWarningInterval( int );
721     
722 /*! \ingroup groupConfigCrypt
723   \brief Returns the number of days which a receiver certificate
724   must be valid before it is considered to expire in the near future.
725 */
726 int receiverCertificateExpiryNearWarningInterval( void );
727     
728 /*! \ingroup groupConfigCrypt
729   \brief Specifies whether a warning should be emitted if 
730   a certificate in the chain expires in the near future.
731 */
732 void setCertificateInChainExpiryNearWarning( bool );
733
734     
735 /*! \ingroup groupConfigCrypt
736   \brief Returns whether a warning should be emitted if a
737   certificate in the chain expires in the near future.
738 */
739 bool certificateInChainExpiryNearWarning( void );
740
741     
742     
743 /*! \ingroup groupConfigCrypt
744   \brief Specifies the number of days which a certificate in the chain
745   must be valid before it is considered to expire in the near future.
746 */
747 void setCertificateInChainExpiryNearWarningInterval( int );
748     
749 /*! \ingroup groupConfigCrypt
750   \brief Returns the number of days which a certificate in the chain
751   must be valid before it is considered to expire in the near future.
752 */
753 int certificateInChainExpiryNearWarningInterval( void );
754     
755     
756 /*! \ingroup groupConfigCrypt
757   \brief Specifies whether a warning is emitted if the email address
758   of the receiver does not appear in the certificate.
759 */
760 void setReceiverEmailAddressNotInCertificateWarning( bool );    
761
762 /*! \ingroup groupConfigCrypt
763   \brief Returns whether a warning is emitted if the email address
764   of the receiver does not appear in the certificate.
765 */
766 bool receiverEmailAddressNotInCertificateWarning( void );    
767
768     
769 /*! \ingroup groupConfigCrypt
770    \brief Specifies whether certificate revocation lists should
771             be used.
772 */
773 void setEncryptionUseCRLs( bool );
774
775 /*! \ingroup groupConfigCrypt
776    \brief Returns whether certificate revocation lists should
777             be used.
778 */
779 bool encryptionUseCRLs( void );
780
781 /*! \ingroup groupConfigCrypt
782    \brief Specifies whether a warning should be emitted if any
783             of the certificates involved in the signing process
784             expires in the near future.
785 */
786 void setEncryptionCRLExpiryNearWarning( bool );
787
788 /*! \ingroup groupConfigCrypt
789    \brief Returns whether a warning should be emitted if any
790             of the certificates involved in the signing process
791             expires in the near future.
792 */
793 bool encryptionCRLExpiryNearWarning( void );
794
795 /*! \ingroup groupConfigCrypt
796    \brief Specifies the number of days which a certificate must
797             be valid before it is considered to expire in the near
798             future.
799 */
800 void setEncryptionCRLNearExpiryInterval( int );
801
802 /*! \ingroup groupConfigCrypt
803    \brief Returns the number of days which a certificate must
804             be valid before it is considered to expire in the near
805             future.
806 */
807 int encryptionCRLNearExpiryInterval( void );
808
809
810 /*! \ingroup groupConfigDir
811    \brief This function returns an XML representation of a
812             configuration dialog for selecting a directory
813             server.
814 */
815 const char* directoryServiceConfigurationDialog( void );
816
817 /*! \ingroup groupConfigDir
818    \brief Lets you configure how certificates and certificate
819    revocation lists are retrieved (both locally and from directory
820    services).
821
822    Will mainly be used for restoring
823             configuration data; interactive configuration will be done
824             via the configuration dialog returned by
825             \c directoryServiceConfigurationDialog().
826 */
827 void appendDirectoryServer( const char* servername, int port,
828                             const char* description );
829
830
831
832
833 /*! \ingroup groupConfigDir
834 */
835 struct DirectoryServer {
836     char* servername;
837     int port;
838     char* description;
839 };
840
841
842 /*! \ingroup groupConfigDir
843    \brief Specifies a list of directory servers.
844
845    Will mainly be used for restoring
846             configuration data; interactive configuration will be done
847             via the configuration dialog returned by
848             \c directoryServiceConfigurationDialog().
849 */
850 void setDirectoryServers( struct DirectoryServer[], unsigned int size );
851
852 /*! \ingroup groupConfigDir
853    \brief Returns the list of directory servers.
854
855    Will mainly be used for saving configuration data; interactive
856             configuration will be done via the configuration dialog
857             returned by
858             \c directoryServiceConfigurationDialog().
859 */
860 struct DirectoryServer* directoryServers( int* numServers );
861
862 /*! \ingroup groupConfigDir
863    \brief Specifies whether certificates should be retrieved
864             from a directory server, only locally, or both.
865 */
866 void setCertificateSource( CertificateSource );
867
868 /*! \ingroup groupConfigDir
869    \brief Returns whether certificates should be retrieved
870             from a directory server, only locally, or both.
871 */
872 CertificateSource certificateSource( void );
873
874 /*! \ingroup groupConfigDir
875    \brief Specifies whether certificates should be retrieved
876             from a directory server, only locally, or both.
877 */
878 void setCRLSource( CertificateSource );
879
880 /*! \ingroup groupConfigDir
881    \brief Returns whether certificates should be retrieved
882             from a directory server, only locally, or both.
883 */
884 CertificateSource crlSource( void );
885
886
887 /*! \ingroup groupCertHand
888    \brief Returns \c true if and only if the
889           certificates in the certificate chain starting at
890           \c certificate are valid.
891           
892    If \c level is non-null, the parameter contains
893           the degree of trust on a backend-specific scale. In an X.509
894           implementation, this will either be \c 1
895           (valid up to the root certificate) or \c 0
896           (not valid up to the root certificate).
897 */
898 bool certificateValidity( const char* certificate, int* level );
899
900
901 /*! \ingroup groupSignAct
902    \brief Signs a message \c cleartext and returns
903           in \c ciphertext the message including
904           signature.
905
906    The signature role is specified by
907           \c certificate. If \c certificate is \c NULL,
908           the default certificate is used.
909 */
910 bool signMessage( const char* cleartext,
911                   const char** ciphertext,
912                   const char* certificate );
913
914
915 /*! \ingroup groupSignAct
916  */
917 struct SignatureMetaDataExtendedInfo
918 {
919     struct tm* creation_time;
920     char* status_text;
921     char* fingerprint;
922 };
923
924 /*! \ingroup groupSignAct
925 */
926 struct SignatureMetaData {
927     char* status;
928     struct SignatureMetaDataExtendedInfo* extended_info;
929     int extended_info_count;
930     char* nota_xml;
931     int status_code;
932 };
933
934 /*! \ingroup groupSignAct
935    \brief Checks whether the signature of a message is
936           valid. \c ciphertext specifies the signed message
937           as it was received by the MUA, \c signaturetext is the
938           signature itself.
939
940    Depending on the configuration, MUAs might not need to use this.
941    If \c sigmeta is non-null, the
942           \c SignatureMetaData object pointed to will
943           contain meta information about the signature after the
944           function call.
945 */
946 bool checkMessageSignature( const char* ciphertext,
947                             const char* signaturetext,
948                             struct SignatureMetaData* sigmeta );
949
950 /*! \ingroup groupSignAct
951    \brief Stores the certificates that follow with the message
952           \c ciphertext locally.
953 */
954 bool storeCertificatesFromMessage( const char* ciphertext );
955
956
957 /*! \ingroup groupCryptAct
958    \brief Encrypts an email message in
959           \c cleartext according to the current
960           settings (algorithm, etc.) and returns it in
961           \c ciphertext.
962
963    If the message could be encrypted, the function returns
964           \c true, otherwise
965           \c false.
966 */
967 bool encryptMessage( const char*  cleartext,
968                      const char** ciphertext,
969                      const char*  addressee );
970
971 /*! \ingroup groupCryptAct
972    \brief Combines the functionality of
973           \c encryptMessage() and
974           \c signMessage().
975
976    If \c certificate is \c NULL,
977           the default certificate will be used.  If
978           \c sigmeta is non-null, the
979           \c SignatureMetaData object pointed to will
980           contain meta information about the signature after the
981           function call.
982 */
983 bool encryptAndSignMessage( const char* cleartext,
984                             const char** ciphertext,
985                             const char* certificate,
986                             struct SignatureMetaData* sigmeta );
987
988 /*! \ingroup groupCryptAct
989    \brief Tries to decrypt an email message
990           \c ciphertext and returns the decrypted
991           message in \c cleartext.
992
993    The \c certificate is used for decryption. If
994           the message could be decrypted, the function returns
995           \c true, otherwise
996           \c false.
997 */
998 bool decryptMessage( const char* ciphertext, const
999           char** cleartext, const char* certificate );
1000
1001 /*! \ingroup groupCryptAct
1002    \brief Combines the functionality of
1003           \c checkMessageSignature() and
1004           \c decryptMessage().
1005
1006    If \c certificate is \c NULL,
1007           the default certificate will be used.  If
1008           \c sigmeta is non-null, the
1009           \c SignatureMetaData object pointed to will
1010           contain meta information about the signature after the
1011           function call.
1012 */
1013 bool decryptAndCheckMessage( const char* ciphertext,
1014                              const char** cleartext,
1015                              const char* certificate,
1016                              struct SignatureMetaData* sigmeta );
1017
1018
1019 /*! \ingroup groupCertAct
1020    \brief This function returns an XML representation of a dialog
1021           that can be used to fill in the data for requesting a
1022           certificate (which in turn is done with the function
1023           \c requestCertificate() described
1024           next.
1025 */
1026 const char* requestCertificateDialog( void );
1027
1028 /*! \ingroup groupCertAct
1029    \brief Generates a prototype certificate with the data provided
1030         in the first four parameters and sends it via email to the CA
1031           specified in \c ca_address.
1032 */
1033 bool requestDecentralCertificate( const char* name, const char*
1034           email, const char* organization, const char* department,
1035           const char* ca_address );
1036
1037 /*! \ingroup groupCertAct
1038    \brief Requests a certificate in a PSE from the CA
1039           specified in \c ca_address.
1040 */
1041 bool requestCentralCertificateAndPSE( const char* name,
1042           const char* email, const char* organization, const char* department,
1043           const char* ca_address );
1044
1045 /*! \ingroup groupCertAct
1046    \brief Creates a local PSE.
1047 */
1048 bool createPSE( void );
1049
1050 /*! \ingroup groupCertAct
1051    \brief Parses and adds a certificate returned by a CA upon
1052           request with
1053           \c requestDecentralCertificate() or
1054           \c requestCentralCertificate().
1055
1056    If the certificate was requested with
1057           \c requestCentralCertificate(), the
1058           certificate returned will come complete with a PSE which is
1059           also registered with this method.
1060 */
1061 bool registerCertificate( const char* );
1062
1063 /*! \ingroup groupCertAct
1064    \brief Requests the prolongation of the certificate
1065           \c certificate from the CA
1066           \c ca_address.
1067 */
1068 bool requestCertificateProlongation( const char*
1069           certificate, const char* ca_address );
1070
1071 /*! \ingroup groupCertAct
1072    \brief Returns an HTML 2-formatted string that describes the
1073           certificate chain of the user's certificate.
1074           
1075    Data displayed is at least the issuer of the certificate, the serial number
1076         of the certificate, the owner of the certificate, the checksum
1077         of the certificate, the validity duration of the certificate,
1078           the usage of the certificate, and the contained email
1079           addresses, if any.
1080 */
1081 const char* certificateChain( void );
1082
1083 /*! \ingroup groupCertAct
1084    \brief Deletes the specified user certificate from the current
1085           PSE.
1086 */
1087 bool deleteCertificate( const char* certificate );
1088
1089 /*! \ingroup groupCertAct
1090    \brief Archives the specified user certificate in the current PSE.
1091
1092    The certificate cannot be used any longer after this
1093           operation unless it is unarchived.
1094 */
1095 bool archiveCertificate( const char* certificate );
1096
1097
1098 /*! \ingroup groupCRLAct
1099    \brief Returns a HTML 2-formatted string that describes the
1100           CRL, suitable for display in the MUA.
1101 */
1102 const char* displayCRL( void );
1103
1104 /*! \ingroup groupCRLAct
1105    \brief Manually update the CRL. CRLs will also be automatically
1106         updated on demand by the backend.
1107         
1108    If there is a local version of a CRL saved, it will be overwritten
1109    with the new CRL from the CA.
1110 */
1111 void updateCRL( void );
1112
1113 #ifdef __cplusplus
1114 }
1115 #endif
1116 #endif /*CRYPTPLUG_H*/
1117