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* fingerprint;
1439 };
1440
1441 /*! \ingroup groupSignAct
1442 */
1443 struct SignatureMetaData {
1444     char* status;
1445     struct SignatureMetaDataExtendedInfo* extended_info;
1446     int extended_info_count;
1447     char* nota_xml;
1448     int status_code;
1449 };
1450
1451 /*! \ingroup groupSignAct
1452    \brief Checks whether the signature of a message is
1453           valid.
1454
1455    \c cleartext must never be 0 but be a valid pointer.
1456
1457    If \c *cleartext > 0 then **cleartext specifies the message text
1458    that was signed and \c signaturetext is the signature itself.
1459
1460    If \c *cleartext == 0 is an empty string then \c signaturetext is
1461    supposed to contain an opaque signed message part. After checking the
1462    data and verifying the signature the cleartext of the message will be
1463    returned in \c cleartext.  The user must free the respective memory
1464    ocupied by *cleartext.
1465
1466    Depending on the configuration, MUAs might not need to use this.
1467    If \c sigmeta is non-null, the
1468           \c SignatureMetaData object pointed to will
1469           contain meta information about the signature after the
1470           function call.
1471 */
1472 bool checkMessageSignature( char** cleartext,
1473                             const char* signaturetext,
1474                             bool signatureIsBinary,
1475                             int signatureLen,
1476                             struct SignatureMetaData* sigmeta );
1477
1478 /*! \ingroup groupSignAct
1479    \brief Stores the certificates that follow with the message
1480           \c ciphertext locally.
1481 */
1482 bool storeCertificatesFromMessage( const char* ciphertext );
1483
1484
1485 /*! \ingroup groupCryptAct
1486    \brief Find all certificate for a given addressee.
1487
1488    NOTE: The \c certificate parameter must point to an allready allocated
1489    block of memory which is large enough to hold the complete list.
1490 */
1491 bool findCertificates( const char* addressee, char** certificates );
1492
1493 /*! \ingroup groupCryptAct
1494    \brief Encrypts an email message in
1495           \c cleartext according to the \c addressee and
1496           the current settings (algorithm, etc.) and
1497           returns the encoded data bloc in \c *ciphertext.
1498           The length returned in \c *cipherLen tells you the
1499           size (==amount of bytes) of the ciphertext, if the
1500           structuring information would return with
1501           contentTEncCode set to "base64" the ciphertext
1502           might contain a char 0x00 and has to be converted
1503           into base64 before sending.
1504
1505    If the message could be encrypted, the function returns
1506           \c true, otherwise
1507           \c false.
1508
1509    Use the StructuringInfo data returned in parameter \c structuring
1510    to find out how to build the respective MIME object (or the plain
1511    text message body, resp.).
1512
1513    \note The function allocates memory for the \c *ciphertext, so
1514          make sure you set free that memory when no longer needing
1515          it (as shown in example code provided with documentation
1516          of the struct \c StructuringInfo).
1517
1518    \note The function also allocates memory for some char* members
1519     of the StructuringInfo* parameter that you are providing,
1520     therefore you <b>must</b> call the \c free_StructuringInfo() function
1521     to make sure all memory is set free that was allocated. This must be
1522     done <b>before</b> calling the next cryptography function!
1523
1524    \see StructuringInfo, free_StructuringInfo
1525 */
1526 bool encryptMessage( const char*  cleartext,
1527                      const char** ciphertext,
1528                      const size_t* cipherLen,
1529                      const char*  addressee,
1530                      struct StructuringInfo* structuring,
1531                      int* errId,
1532                      char** errTxt );
1533
1534
1535 /*! \ingroup groupCryptAct
1536    \brief Combines the functionality of
1537           \c encryptMessage() and
1538           \c signMessage().
1539
1540    If \c certificate is \c NULL,
1541    the default certificate will be used.
1542
1543    If the message could be signed and encrypted, the function returns
1544           \c true, otherwise
1545           \c false.
1546
1547    Use the StructuringInfo data returned in parameter \c structuring
1548    to find out how to build the respective MIME object (or the plain
1549    text message body, resp.).
1550
1551    \note The function allocates memory for the \c *ciphertext, so
1552          make sure you set free that memory when no longer needing
1553          it (as shown in example code provided with documentation
1554          of the struct \c StructuringInfo).
1555
1556    \note The function also allocates memory for some char* members
1557     of the StructuringInfo* parameter that you are providing,
1558     therefore you <b>must</b> call the \c free_StructuringInfo() function
1559     to make sure all memory is set free that was allocated. This must be
1560     done <b>before</b> calling the next cryptography function!
1561
1562    \see StructuringInfo, free_StructuringInfo
1563 */
1564 bool encryptAndSignMessage( const char* cleartext,
1565                             const char** ciphertext,
1566                             const char* certificate,
1567                             struct StructuringInfo* structuring );
1568
1569 /*! \ingroup groupCryptAct
1570    \brief Tries to decrypt an email message
1571           \c ciphertext and returns the decrypted
1572           message in \c cleartext.
1573
1574    The \c certificate is used for decryption. If
1575           the message could be decrypted, the function returns
1576           \c true, otherwise
1577           \c false.
1578 */
1579 bool decryptMessage( const char* ciphertext,
1580                      bool        cipherIsBinary,
1581                      int         cipherLen,
1582                      const char** cleartext,
1583                      const char* certificate );
1584
1585 /*! \ingroup groupCryptAct
1586    \brief Combines the functionality of
1587           \c checkMessageSignature() and
1588           \c decryptMessage().
1589
1590    If \c certificate is \c NULL,
1591    the default certificate will be used.
1592    If \c sigmeta is non-null, the \c SignatureMetaData
1593    object pointed to will contain meta information about
1594    the signature after the function call.
1595 */
1596 bool decryptAndCheckMessage( const char* ciphertext,
1597                              const char** cleartext,
1598                              const char* certificate,
1599                              struct SignatureMetaData* sigmeta );
1600
1601
1602 /*! \ingroup groupCertAct
1603    \brief This function returns an XML representation of a dialog
1604           that can be used to fill in the data for requesting a
1605           certificate (which in turn is done with the function
1606           \c requestCertificate() described
1607           next.
1608 */
1609 const char* requestCertificateDialog( void );
1610
1611 /*! \ingroup groupCertAct
1612    \brief Generates a prototype certificate with the data provided
1613         in the four parameter. The memory returned in \a generatedKey
1614         must be freed with free() by the caller.
1615 */
1616 bool requestDecentralCertificate( const char* certparms,
1617                                   char** generatedKey, int* keyLength );
1618
1619 /*! \ingroup groupCertAct
1620    \brief Requests a certificate in a PSE from the CA
1621           specified in \c ca_address.
1622 */
1623 bool requestCentralCertificateAndPSE( const char* name,
1624           const char* email, const char* organization, const char* department,
1625           const char* ca_address );
1626
1627 /*! \ingroup groupCertAct
1628    \brief Creates a local PSE.
1629 */
1630 bool createPSE( void );
1631
1632 /*! \ingroup groupCertAct
1633    \brief Parses and adds a certificate returned by a CA upon
1634           request with
1635           \c requestDecentralCertificate() or
1636           \c requestCentralCertificate().
1637
1638    If the certificate was requested with
1639           \c requestCentralCertificate(), the
1640           certificate returned will come complete with a PSE which is
1641           also registered with this method.
1642 */
1643 bool registerCertificate( const char* );
1644
1645 /*! \ingroup groupCertAct
1646    \brief Requests the prolongation of the certificate
1647           \c certificate from the CA
1648           \c ca_address.
1649 */
1650 bool requestCertificateProlongation( const char*
1651           certificate, const char* ca_address );
1652
1653 /*! \ingroup groupCertAct
1654    \brief Returns an HTML 2-formatted string that describes the
1655           certificate chain of the user's certificate.
1656
1657    Data displayed is at least the issuer of the certificate, the serial number
1658         of the certificate, the owner of the certificate, the checksum
1659         of the certificate, the validity duration of the certificate,
1660           the usage of the certificate, and the contained email
1661           addresses, if any.
1662 */
1663 const char* certificateChain( void );
1664
1665 /*! \ingroup groupCertAct
1666    \brief Deletes the specified user certificate from the current
1667           PSE.
1668 */
1669 bool deleteCertificate( const char* certificate );
1670
1671 /*! \ingroup groupCertAct
1672    \brief Archives the specified user certificate in the current PSE.
1673
1674    The certificate cannot be used any longer after this
1675           operation unless it is unarchived.
1676 */
1677 bool archiveCertificate( const char* certificate );
1678
1679
1680 /*! \ingroup groupCRLAct
1681    \brief Returns a HTML 2-formatted string that describes the
1682           CRL, suitable for display in the MUA.
1683 */
1684 const char* displayCRL( void );
1685
1686 /*! \ingroup groupCRLAct
1687    \brief Manually update the CRL. CRLs will also be automatically
1688         updated on demand by the backend.
1689
1690    If there is a local version of a CRL saved, it will be overwritten
1691    with the new CRL from the CA.
1692 */
1693 void updateCRL( void );
1694
1695 struct CertIterator;
1696
1697 struct DnPair {
1698     char *key;
1699     char *value;
1700 };
1701
1702 struct CertificateInfo {
1703   char** userid;
1704   char* issuer;
1705   struct DnPair *dnarray; /* parsed values from userid[0] */
1706 };
1707
1708 /*! \function struct CertIterator*  startListCertificates( void );
1709     \function struct CertificateInfo*  nextCertificate( struct CertIterator* );
1710     \function void endListCertificates( struct CertIterator* );
1711
1712     \ingroup certList
1713   Example:
1714 \verbatim
1715   struct CertificateInfo* info;
1716   struct CertIterator* it = startListCertificates();
1717   while( info = nextCertificate( it ) ) {
1718     do something with info.
1719     dont free() it, the struct will be reused
1720     by the next call to nextCertificate()
1721   }
1722   endListCertificates( it );
1723 \endverbatim
1724 */
1725 struct CertIterator*  startListCertificates( void );
1726 struct CertificateInfo*  nextCertificate( struct CertIterator* );
1727 void endListCertificates( struct CertIterator* );
1728
1729
1730 #ifdef __cplusplus
1731 }
1732 #endif
1733 #endif /*CRYPTPLUG_H*/
1734