diff options
Diffstat (limited to 'branches/gpgme-0-3-branch/gpgmeplug/cryptplug.h')
| -rw-r--r-- | branches/gpgme-0-3-branch/gpgmeplug/cryptplug.h | 1906 |
1 files changed, 1906 insertions, 0 deletions
diff --git a/branches/gpgme-0-3-branch/gpgmeplug/cryptplug.h b/branches/gpgme-0-3-branch/gpgmeplug/cryptplug.h new file mode 100644 index 00000000..325a62a9 --- /dev/null +++ b/branches/gpgme-0-3-branch/gpgmeplug/cryptplug.h @@ -0,0 +1,1906 @@ +/* -*- Mode: C -*- + + $Id$ + + CRYPTPLUG - an independent cryptography plug-in API + + Copyright (C) 2001 by Klar�lvdalens Datakonsult AB + + CRYPTPLUG is free software; you can redistribute it and/or modify + it under the terms of GNU General Public License as published by + the Free Software Foundation; version 2 of the License. + + CRYPTPLUG is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA +*/ + +#ifndef CRYPTPLUG_H +#define CRYPTPLUG_H + +#include <stdlib.h> + +#ifdef __cplusplus +extern "C" { +#else +typedef char bool; +#define true 1 +#define false 0 +#endif + +/*! \file cryptplug.h + \brief Common API header for CRYPTPLUG. + + CRYPTPLUG is an independent cryptography plug-in API + developed for Sphinx-enabeling KMail and Mutt. + + CRYPTPLUG was designed for the Aegypten project, but it may + be used by 3rd party developers as well to design pluggable + crypto backends for the above mentioned MUAs. + + \note All string parameters appearing in this API are to be + interpreted as UTF-8 encoded. + + \see pgpplugin.c + \see gpgplugin.c +*/ + +/*! \defgroup groupGeneral Loading and Unloading the Plugin, General Functionality + + The functions in this section are used for loading and + unloading plugins. Note that the actual locating of the plugin + and the loading and unloading of the dynamic library is not + covered here; this is MUA-specific code for which support code + might already exist in the programming environments. +*/ + +/*! \defgroup groupDisplay Graphical Display Functionality + + The functions in this section return stationery that the + MUAs can use in order to display security functionality + graphically. This can be toolbar icons, shortcuts, tooltips, + etc. Not all MUAs will use all this functionality. +*/ + +/*! \defgroup groupConfig Configuration Support + + The functions in this section provide the necessary + functionality to configure the security functionality as well + as to query configuration settings. Since all configuration + settings will not be saved with the plugin, but rather with + the MUA, there are also functions to set configuration + settings programmatically; these will be used on startup of + the plugin when the MUA transfers the configuration values it + has read into the plugin. Usually, the functions to query and + set the configuration values are not needed for anything but + saving to and restoring from configuration files. +*/ + + +/*! \defgroup groupConfigSign Signature Configuration + \ingroup groupConfig + + The functions in this section provide the functionality + to configure signature handling and set and query the + signature configuration. +*/ + +/*! \defgroup groupConfigCrypt Encryption Configuration + \ingroup groupConfig + + The functions in this section provide the functionality + to configure encryption handling and set and query the + encryption configuration. + + \note Whenever the term <b> encryption</b> is used here, + it is supposed to mean both encryption and decryption, + unless otherwise specified. +*/ + +/*! \defgroup groupConfigDir Directory Service Configuration + \ingroup groupConfig + + This section contains messages for configuring the + directory service. +*/ + + +/*! \defgroup groupCertHand Certificate Handling + + The following methods are used to maintain and query certificates. +*/ + + +/*! \defgroup groupSignCryptAct Signing and Encrypting Actions + + This section describes methods and structures + used for signing and/or encrypting your mails. +*/ + + +/*! \defgroup groupSignAct Signature Actions + \ingroup groupSignCryptAct + + This section describes methods that are used for working + with signatures. +*/ + +/*! \defgroup groupCryptAct Encryption and Decryption + \ingroup groupSignCryptAct + + The following methods are used to encrypt and decrypt + email messages. +*/ + +/*! \defgroup groupCertAct Certificate Handling Actions + + The functions in this section provide local certificate management. +*/ + +/*! \defgroup groupCRLAct CRL Handling Actions + + This section describes functions for managing CRLs. +*/ + +/*! \defgroup groupAdUsoInterno Important functions to be used by plugin implementors ONLY. + + This section describes functions that have to be used by + plugin implementors but should not be used by plugin users + directly. + + If you are not planning to write your own cryptography + plugin <b>you should ignore this</b> section! +*/ + +/*! \defgroup certList Certificate Info listing functions + */ + + +typedef enum { + Feature_undef = 0, + + Feature_SignMessages = 1, + Feature_VerifySignatures = 2, + Feature_EncryptMessages = 3, + Feature_DecryptMessages = 4, + Feature_SendCertificates = 5, + Feature_WarnSignCertificateExpiry = 6, + Feature_WarnSignEmailNotInCertificate = 7, + Feature_PinEntrySettings = 8, + Feature_StoreMessagesWithSigs = 9, + Feature_EncryptionCRLs = 10, + Feature_WarnEncryptCertificateExpiry = 11, + Feature_WarnEncryptEmailNotInCertificate = 12, + Feature_StoreMessagesEncrypted = 13, + Feature_CheckCertificatePath = 14, + Feature_CertificateDirectoryService = 15, + Feature_CRLDirectoryService = 16, + Feature_CertificateInfo = 17 +} Feature; + +/* dummy values */ +typedef enum { + PinRequest_undef = 0, + + PinRequest_Always = 1, + PinRequest_WhenAddingCerts = 2, + PinRequest_AlwaysWhenSigning = 3, + PinRequest_OncePerSession = 4, + PinRequest_AfterMinutes = 5 +} PinRequests; + + +typedef enum { + SignatureCompoundMode_undef = 0, + + SignatureCompoundMode_Opaque = 1, + SignatureCompoundMode_Detached = 2 +} SignatureCompoundMode; + + +typedef enum { + SendCert_undef = 0, + + SendCert_DontSend = 1, + SendCert_SendOwn = 2, + SendCert_SendChainWithoutRoot = 3, + SendCert_SendChainWithRoot = 4 +} SendCertificates; + + +typedef enum { + SignAlg_undef = 0, + + SignAlg_SHA1 = 1 +} SignatureAlgorithm; + + + +typedef enum { + EncryptAlg_undef = 0, + + EncryptAlg_RSA = 1, + EncryptAlg_SHA1 = 2, + EncryptAlg_TripleDES = 3 +} EncryptionAlgorithm; + +typedef enum { + SignEmail_undef = 0, + + SignEmail_SignAll = 1, + SignEmail_Ask = 2, + SignEmail_DontSign = 3 +} SignEmail; + +typedef enum { + EncryptEmail_undef = 0, + + EncryptEmail_EncryptAll = 1, + EncryptEmail_Ask = 2, + EncryptEmail_DontEncrypt = 3 +} EncryptEmail; + +typedef enum { + CertSrc_undef = 0, + + CertSrc_Server = 1, + CertSrc_Local = 2, + CertSrc_ServerLocal = CertSrc_Server | CertSrc_Local +} CertificateSource; + + +/*! \ingroup groupSignAct + \brief Flags used to compose the SigStatusFlags value. + + This status flags are used to compose the SigStatusFlags value + returned in \c SignatureMetaDataExtendedInfo after trying to + verify a signed message part's signature status. + + The normal flags may <b>not</b> be used together with the + special SigStat_NUMERICAL_CODE flag. When finding the special + SigStat_NUMERICAL_CODE flag in a SigStatusFlags value you + can obtain the respective error code number by substracting + the SigStatusFlags value by SigStat_NUMERICAL_CODE: this is + used to transport special status information NOT matching + any of the normal predefined status codes. + + \note to PlugIn developers: Implementations of the CryptPlug API + should try to express their signature states by bit-wise OR'ing + the normal SigStatusFlags values. Using the SigStat_NUMERICAL_CODE + flag should only be used as for exceptional situations where no + other flag(s) could be used. By using the normal status flags your + PlugIn's users will be told an understandable description of the + status - when using (SigStat_NUMERICAL_CODE + internalCode) they + will only be shown the respective code number and have to look + into your PlugIn's manual to learn about it's meaning... +*/ +enum { + SigStat_VALID = 0x0001, /* The signature is fully valid */ + SigStat_GREEN = 0x0002, /* The signature is good. */ + SigStat_RED = 0x0004, /* The signature is bad. */ + SigStat_KEY_REVOKED = 0x0010, /* One key has been revoked. */ + SigStat_KEY_EXPIRED = 0x0020, /* One key has expired. */ + SigStat_SIG_EXPIRED = 0x0040, /* The signature has expired. */ + SigStat_KEY_MISSING = 0x0080, /* Can't verify: key missing. */ + SigStat_CRL_MISSING = 0x0100, /* CRL not available. */ + SigStat_CRL_TOO_OLD = 0x0200, /* Available CRL is too old. */ + SigStat_BAD_POLICY = 0x0400, /* A policy was not met. */ + SigStat_SYS_ERROR = 0x0800, /* A system error occured. */ + + SigStat_NUMERICAL_CODE = 0x8000 /* An other error occured. */ +}; +typedef unsigned long SigStatusFlags; + + +#define CRYPTPLUG_CERT_DOES_NEVER_EXPIRE 365000 + + + + +/*! \ingroup groupGeneral + \brief This function returns the version string of this cryptography + plug-in. + + If the plugins initialization fails the calling process might want + to display the library version number to the user for checking if + there is an old version of the library installed... + + \note This function <b>must</b> be implemented by each plug-in using + this API specification. +*/ +const char* libVersion( void ); + +/*! \ingroup groupGeneral + \brief This function returns a URL to be used for reporting a bug that + you found (or suspect, resp.) in this cryptography plug-in. + + If the plugins for some reason cannot specify an appropriate URL you + should at least be provided with a text giving you some advise on + how to report a bug. + + \note This function <b>must</b> be implemented by each plug-in using + this API specification. +*/ +const char* bugURL( void ); + +/*! \ingroup groupGeneral + \brief This function sets up all internal structures. + + Plugins that need no initialization should provide an empty + implementation. The method returns \c true if the initialization was + successful and \c false otherwise. Before this function is called, + no other plugin functions should be called; the behavior is + undefined in this case. + + \note This function <b>must</b> be implemented by each plug-in using + this API specification. +*/ +bool initialize( void ); + +/*! \ingroup groupGeneral + \brief This function frees all internal structures. + + Plugins that do not keep any internal structures should provide an + empty implementation. After this function has been called, + no other plugin functions should be called; the behavior is + undefined in this case. + + \note This function <b>must</b> be implemented by each plug-in using + this API specification. +*/ +void deinitialize( void ); + +/*! \ingroup groupGeneral + \brief This function returns \c true if the + specified feature is available in the plugin, and + \c false otherwise. + + Not all plugins will support all features; a complete Sphinx + implementation will support all features contained in the enum, + however. + + \note This function <b>must</b> be implemented by each plug-in using + this API specification. +*/ +bool hasFeature( Feature ); + + +/*! \ingroup groupDisplay + \brief Returns stationery to indicate unsafe emails. +*/ +void unsafeStationery( void** pixmap, const char** menutext, char* accel, + const char** tooltip, const char** statusbartext ); + +/*! \ingroup groupDisplay + \brief Returns stationery to indicate signed emails. +*/ +void signedStationery( void** pixmap, const char** menutext, char* accel, + const char** tooltip, const char** statusbartext ); + +/*! \ingroup groupDisplay + \brief Returns stationery to indicate encrypted emails. +*/ +void encryptedStationery( void** pixmap, const char** + menutext, char* accel, + const char** tooltip, const char** statusbartext ); + +/*! \ingroup groupDisplay + \brief Returns stationery to indicate signed and encrypted emails. +*/ +void signedEncryptedStationery( void** pixmap, const char** + menutext, char* accel, + const char** tooltip, const char** statusbartext ); + +/*! \ingroup groupConfigSign + \brief This function returns an XML representation of a + configuration dialog for configuring signature + handling. + + The syntax is that of <filename>.ui</filename> + files as specified in the <emphasis>Imhotep</emphasis> + documentation. This function does not execute or show the + dialog in any way; this is up to the MUA. Also, what the + MUA makes of the information provided highly depends on + the MUA itself. A GUI-based MUA will probably create a + dialog window (possibly integrated into an existing + configuration dialog in the application), while a + terminal-based MUA might generate a series of questions or + a terminal based menu selection. +*/ +const char* signatureConfigurationDialog( void ); + +/*! \ingroup groupConfigSign + \brief This function returns an XML representation of a + configuration dialog for selecting a signature key. + + This will typically be used when the user wants to select a + signature key for one specific message only; the defaults + are set in the dialog returned by + signatureConfigurationDialog(). +*/ +const char* signatureKeySelectionDialog( void ); + +/*! \ingroup groupConfigSign + \brief This function returns an XML representation of a + configuration dialog for selecting a signature + algorithm. + + This will typically be used when the user wants + to select a signature algorithm for one specific message only; the + defaults are set in the dialog returned by + signatureConfigurationDialog(). +*/ +const char* signatureAlgorithmDialog( void ); + +/*! \ingroup groupConfigSign + \brief This function returns an XML representation of a + configuration dialog for selecting whether an email + message and its attachments should be sent with or + without signatures. + + This will typically be used when the + user wants to select a signature key for one specific + message only; the defaults are set in the dialog returned + by signatureConfigurationDialog(). +*/ +const char* signatureHandlingDialog( void ); + +/*! \ingroup groupConfigSign + \brief Sets the signature key certificate that identifies the + role of the signer. +*/ +void setSignatureKeyCertificate( const char* certificate ); + +/*! \ingroup groupConfigSign + \brief Returns the signature key certificate that identifies + the role of the signer. +*/ +const char* signatureKeyCertificate( void ); + +/*! \ingroup groupConfigSign + \brief Sets the algorithm used for signing. +*/ +void setSignatureAlgorithm( SignatureAlgorithm ); + +/*! \ingroup groupConfigSign + \brief Returns the algorithm used for signing. +*/ +SignatureAlgorithm signatureAlgorithm( void ); + +/*! \ingroup groupConfigSign +\brief Sets whether signatures and signed data should be send + as opaque signed or + as multipart/signed message parts. +*/ +void setSignatureCompoundMode( SignatureCompoundMode ); + +/*! \ingroup groupConfigSign +\brief Returns whether signatures and signed data will be send + as opaque signed or + as multipart/signed message parts. +*/ +SignatureCompoundMode signatureCompoundMode( void ); + +/*! \ingroup groupConfigSign + \brief Sets which certificates should be sent with the + message. +*/ +void setSendCertificates( SendCertificates ); +/*! \ingroup groupConfigSign + \brief Returns which certificates should be sent with the + message. +*/ +SendCertificates sendCertificates( void ); + +/*! \ingroup groupConfigSign + \brief Specifies whether email should be automatically + signed, signed after confirmation, signed after + confirmation for each part or not signed at all. +*/ +void setSignEmail( SignEmail ); + +/*! \ingroup groupConfigSign + \brief Returns whether email should be automatically + signed, signed after confirmation, signed after + confirmation for each part or not signed at all. +*/ +SignEmail signEmail( void ); + + +/*! \ingroup groupConfigSign + \brief Specifies whether a warning should be emitted when the user + tries to send an email message unsigned. +*/ +void setWarnSendUnsigned( bool ); + + +/*! \ingroup groupConfigSign + \brief Returns whether a warning should be emitted when the user + tries to send an email message unsigned. +*/ +bool warnSendUnsigned( void ); + + +/*! \ingroup groupConfigSign + \brief Specifies whether sent email messages should be stored + with or without their signatures. +*/ +void setSaveSentSignatures( bool ); + +/*! \ingroup groupConfigSign + \brief Returns whether sent email messages should be stored + with or without their signatures. +*/ +bool saveSentSignatures( void ); + +/*! \ingroup groupConfigSign + \brief Specifies whether a warning should be emitted if the + email address of the sender is not contained in the + certificate. +*/ +void setWarnNoCertificate( bool ); + +/*! \ingroup groupConfigSign + \brief Returns whether a warning should be emitted if the + email address of the sender is not contained in the + certificate. +*/ +bool warnNoCertificate( void ); + +/*! + \ingroup groupConfigSign + \brief Returns true if the specified email address is contained + in the specified certificate. +*/ +bool isEmailInCertificate( const char* email, const char* certificate ); + +/*! \ingroup groupConfigSign + \brief Specifies how often the PIN is requested when + accessing the secret signature key. +*/ +void setNumPINRequests( PinRequests ); + +/*! \ingroup groupConfigSign + \brief Returns how often the PIN is requested when + accessing the secret signature key. +*/ +PinRequests numPINRequests( void ); + +/*! \ingroup groupConfigSign + \brief Specifies the interval in minutes the PIN must be reentered if + numPINRequests() is PinRequest_AfterMinutes. +*/ +void setNumPINRequestsInterval( int ); + + +/*! \ingroup groupConfigSign + \brief Returns the interval in minutes the PIN must be reentered if + numPINRequests() is PinRequest_AfterMinutes. +*/ +int numPINRequestsInterval( void ); + + +/*! \ingroup groupConfigSign + \brief Specifies whether the certificate path should be + followed to the root certificate or whether locally stored + certificates may be used. +*/ +void setCheckSignatureCertificatePathToRoot( bool ); + +/*! \ingroup groupConfigSign + \brief Returns whether the certificate path should be + followed to the root certificate or whether locally stored + certificates may be used. +*/ +bool checkSignatureCertificatePathToRoot( void ); + +/*! \ingroup groupConfigSign + \brief Specifies whether certificate revocation lists should + be used. +*/ +void setSignatureUseCRLs( bool ); + +/*! \ingroup groupConfigSign + \brief Returns whether certificate revocation lists should + be used. +*/ +bool signatureUseCRLs( void ); + +/*! \ingroup groupConfigSign + \brief Specifies whether a warning should be emitted if the + signature certificate expires in the near future. +*/ +void setSignatureCertificateExpiryNearWarning( bool ); + +/*! \ingroup groupConfigSign + \brief Returns whether a warning should be emitted if + the signature certificate expires in the near future. +*/ +bool signatureCertificateExpiryNearWarning( void ); + +/*! \ingroup groupConfigSign + \brief Returns the number of days that are left until the + specified certificate expires. + + Negative values show how many days ago the certificate DID expire, + a zero value means the certificate expires today, + special value CRYPTPLUG_CERT_DOES_NEVER_EXPIRE means there is + no expire date stored in this certificate. + + \param certificate the certificate to check +*/ +int signatureCertificateDaysLeftToExpiry( const char* certificate ); + +/*! \ingroup groupConfigSign + \brief Specifies the number of days which a signature certificate must + be valid before it is considered to expire in the near + future. +*/ +void setSignatureCertificateExpiryNearInterval( int ); + +/*! \ingroup groupConfigSign + \brief Returns the number of days which a signature certificate must + be valid before it is considered to expire in the near + future. +*/ +int signatureCertificateExpiryNearInterval( void ); + +/*! \ingroup groupConfigSign + \brief Specifies whether a warning should be emitted if the + CA certificate expires in the near future. +*/ +void setCACertificateExpiryNearWarning( bool ); + +/*! \ingroup groupConfigSign + \brief Returns whether a warning should be emitted if + the CA certificate expires in the near future. +*/ +bool caCertificateExpiryNearWarning( void ); + +/*! \ingroup groupConfigSign + \brief Returns the number of days that are left until the + CA certificate of the specified certificate expires. + + Negative values show how many days ago the certificate DID expire, + a zero value means the certificate expires today, + special value CRYPTPLUG_CERT_DOES_NEVER_EXPIRE means there is + no expire date stored in this certificate. + + \param certificate the certificate to check +*/ +int caCertificateDaysLeftToExpiry( const char* certificate ); + +/*! \ingroup groupConfigSign + \brief Specifies the number of days which a CA certificate must + be valid before it is considered to expire in the near + future. +*/ +void setCACertificateExpiryNearInterval( int ); + +/*! \ingroup groupConfigSign + \brief Returns the number of days which a CA certificate must + be valid before it is considered to expire in the near + future. +*/ +int caCertificateExpiryNearInterval( void ); + +/*! \ingroup groupConfigSign + \brief Specifies whether a warning should be emitted if the + root certificate expires in the near future. +*/ +void setRootCertificateExpiryNearWarning( bool ); + +/*! \ingroup groupConfigSign + \brief Returns whether a warning should be emitted if + the root certificate expires in the near future. +*/ +bool rootCertificateExpiryNearWarning( void ); + +/*! \ingroup groupConfigSign + \brief Returns the number of days that are left until the + root certificate of the specified certificate expires. + + Negative values show how many days ago the certificate DID expire, + a zero value means the certificate expires today, + special value CRYPTPLUG_CERT_DOES_NEVER_EXPIRE means there is + no expire date stored in this certificate. + + \param certificate the certificate to check +*/ +int rootCertificateDaysLeftToExpiry( const char* certificate ); + +/*! \ingroup groupConfigSign + \brief Specifies the number of days which a root certificate must + be valid before it is considered to expire in the near + future. +*/ +void setRootCertificateExpiryNearInterval( int ); + +/*! \ingroup groupConfigSign + \brief Returns the number of days which a signature certificate must + be valid before it is considered to expire in the near + future. +*/ +int rootCertificateExpiryNearInterval( void ); + + + + +/*! \ingroup groupConfigCrypt + \brief This function returns an XML representation of a + configuration dialog for configuring encryption + handling. + + The syntax is that of <filename>.ui</filename> + files as specified in the <emphasis>Imhotep</emphasis> + documentation. This function does not execute or show the + dialog in any way; this is up to the MUA. Also, what the + MUA makes of the information provided highly depends on + the MUA itself. A GUI-based MUA will probably create a + dialog window (possibly integrated into an existing + configuration dialog in the application), while a + terminal-based MUA might generate a series of questions or + a terminal based menu selection. +*/ +const char* encryptionConfigurationDialog( void ); + +/*! \ingroup groupConfigCrypt + \brief This function returns an XML representation of a + configuration dialog for selecting an encryption + algorithm. + + This will typically be used when the user wants + to select an encryption algorithm for one specific message only; the + defaults are set in the dialog returned by + encryptionConfigurationDialog(). +*/ +const char* encryptionAlgorithmDialog( void ); + +/*! \ingroup groupConfigCrypt + \brief This function returns an XML representation of a + configuration dialog for selecting whether an email + message and its attachments should be encrypted. + + This will typically be used when the + user wants to select an encryption key for one specific + message only; the defaults are set in the dialog returned + by encryptionConfigurationDialog(). +*/ +const char* encryptionHandlingDialog( void ); + +/*! \ingroup groupConfigCrypt + \brief This function returns an XML representation of a + dialog that lets the user select the certificate to use + for encrypting. + + If it was not possible to determine the + correct certificate from the information in the email + message, the user is presented with a list of possible + certificates to choose from. If a unique certificate was + found, this is presented to the user, who needs to confirm + the selection of the certificate. This procedure is repeated + for each recipient of the email message. +*/ +const char* encryptionReceiverDialog( void ); + +/*! \ingroup groupConfigCrypt + \brief Sets the algorithm used for encrypting. +*/ +void setEncryptionAlgorithm( EncryptionAlgorithm ); + +/*! \ingroup groupConfigCrypt + \brief Returns the algorithm used for encrypting. +*/ +EncryptionAlgorithm encryptionAlgorithm( void ); + +/*! \ingroup groupConfigCrypt + \brief Specifies whether email should be automatically + encrypted, encrypted after confirmation, encrypted after + confirmation for each part or not encrypted at all. +*/ +void setEncryptEmail( EncryptEmail ); + +/*! \ingroup groupConfigCrypt + \brief Returns whether email should be automatically + encrypted, encrypted after confirmation, encrypted after + confirmation for each part or not encrypted at all. +*/ +EncryptEmail encryptEmail( void ); + +/*! \ingroup groupConfigSign + \brief Specifies whether a warning should be emitted when the user + tries to send an email message unencrypted. +*/ +void setWarnSendUnencrypted( bool ); + + +/*! \ingroup groupConfigSign + \brief Returns whether a warning should be emitted when the user + tries to send an email message unencrypted. +*/ +bool warnSendUnencrypted( void ); + + +/*! \ingroup groupConfigCrypt + \brief Specifies whether encrypted email messages should be + stored encrypted or decrypted. +*/ +void setSaveMessagesEncrypted( bool ); + +/*! \ingroup groupConfigCrypt + \brief Returns whether encrypted email messages should be stored + encrypted or decrypted. +*/ +bool saveMessagesEncrypted( void ); + + +/*! \ingroup groupConfigCrypt + \brief Specifies whether the certificate path should be checked + during encryption. +*/ +void setCheckCertificatePath( bool ); + +/*! \ingroup groupConfigCrypt + \brief Returns whether the certificate path should be checked + during encryption. +*/ +bool checkCertificatePath( void ); + + +/*! \ingroup groupConfigCrypt + \brief Specifies whether the certificate path should be + followed to the root certificate or whether locally stored + certificates may be used. +*/ +void setCheckEncryptionCertificatePathToRoot( bool ); + +/*! \ingroup groupConfigCrypt + \brief Returns whether the certificate path should be + followed to the root certificate or whether locally stored + certificates may be used. +*/ +bool checkEncryptionCertificatePathToRoot( void ); + + +/*! \ingroup groupConfigCrypt + \brief Specifies whether a warning should be emitted if the + certificate of the receiver expires in the near future. +*/ +void setReceiverCertificateExpiryNearWarning( bool ); + +/*! \ingroup groupConfigCrypt + \brief Returns whether a warning should be emitted if the + certificate of the receiver expires in the near future. +*/ +bool receiverCertificateExpiryNearWarning( void ); + + +/*! \ingroup groupConfigCrypt + \brief Returns the number of days until the specified receiver + certificate expires. + + Negative values show how many days ago the certificate DID expire, + a zero value means the certificate expires today, + special value CRYPTPLUG_CERT_DOES_NEVER_EXPIRE means there is + no expire date stored in this certificate. +*/ +int receiverCertificateDaysLeftToExpiry( const char* certificate ); + + + +/*! \ingroup groupConfigCrypt + \brief Specifies the number of days which a receiver certificate + must be valid before it is considered to expire in the near future. +*/ +void setReceiverCertificateExpiryNearWarningInterval( int ); + +/*! \ingroup groupConfigCrypt + \brief Returns the number of days which a receiver certificate + must be valid before it is considered to expire in the near future. +*/ +int receiverCertificateExpiryNearWarningInterval( void ); + +/*! \ingroup groupConfigCrypt + \brief Specifies whether a warning should be emitted if + a certificate in the chain expires in the near future. +*/ +void setCertificateInChainExpiryNearWarning( bool ); + + +/*! \ingroup groupConfigCrypt + \brief Returns whether a warning should be emitted if a + certificate in the chain expires in the near future. +*/ +bool certificateInChainExpiryNearWarning( void ); + + + +/*! \ingroup groupConfigCrypt + \brief Specifies the number of days which a certificate in the chain + must be valid before it is considered to expire in the near future. +*/ +void setCertificateInChainExpiryNearWarningInterval( int ); + +/*! \ingroup groupConfigCrypt + \brief Returns the number of days which a certificate in the chain + must be valid before it is considered to expire in the near future. +*/ +int certificateInChainExpiryNearWarningInterval( void ); + + +/*! \ingroup groupConfigCrypt + \brief Returns the number of days until the first certificate in + the chain of the receiver certificate expires. + + Negative values show how many days ago the certificate DID expire, + a zero value means the certificate expires today, + special value CRYPTPLUG_CERT_DOES_NEVER_EXPIRE means there is + no expire date stored in this certificate. +*/ +int certificateInChainDaysLeftToExpiry( const char* certificate ); + + +/*! \ingroup groupConfigCrypt + \brief Specifies whether a warning is emitted if the email address + of the receiver does not appear in the certificate. +*/ +void setReceiverEmailAddressNotInCertificateWarning( bool ); + +/*! \ingroup groupConfigCrypt + \brief Returns whether a warning is emitted if the email address + of the receiver does not appear in the certificate. +*/ +bool receiverEmailAddressNotInCertificateWarning( void ); + + +/*! \ingroup groupConfigCrypt + \brief Specifies whether certificate revocation lists should + be used. +*/ +void setEncryptionUseCRLs( bool ); + +/*! \ingroup groupConfigCrypt + \brief Returns whether certificate revocation lists should + be used. +*/ +bool encryptionUseCRLs( void ); + +/*! \ingroup groupConfigCrypt + \brief Specifies whether a warning should be emitted if any + of the certificates involved in the signing process + expires in the near future. +*/ +void setEncryptionCRLExpiryNearWarning( bool ); + +/*! \ingroup groupConfigCrypt + \brief Returns whether a warning should be emitted if any + of the certificates involved in the signing process + expires in the near future. +*/ +bool encryptionCRLExpiryNearWarning( void ); + +/*! \ingroup groupConfigCrypt + \brief Specifies the number of days which a certificate must + be valid before it is considered to expire in the near + future. +*/ +void setEncryptionCRLNearExpiryInterval( int ); + +/*! \ingroup groupConfigCrypt + \brief Returns the number of days which a certificate must + be valid before it is considered to expire in the near + future. +*/ +int encryptionCRLNearExpiryInterval( void ); + + +/*! \ingroup groupConfigCrypt + \brief Returns the number of days the currently active certification + list is still valid. +*/ +int encryptionCRLsDaysLeftToExpiry( void ); + + + +/*! \ingroup groupConfigDir + \brief This function returns an XML representation of a + configuration dialog for selecting a directory + server. +*/ +const char* directoryServiceConfigurationDialog( void ); + +/*! \ingroup groupConfigDir + \brief Lets you configure how certificates and certificate + revocation lists are retrieved (both locally and from directory + services). + + Will mainly be used for restoring + configuration data; interactive configuration will be done + via the configuration dialog returned by + \c directoryServiceConfigurationDialog(). +*/ +void appendDirectoryServer( const char* servername, int port, + const char* description ); + + + + +/*! \ingroup groupConfigDir +*/ +struct DirectoryServer { + char* servername; + int port; + char* description; +}; + + +/*! \ingroup groupConfigDir + \brief Specifies a list of directory servers. + + Will mainly be used for restoring + configuration data; interactive configuration will be done + via the configuration dialog returned by + \c directoryServiceConfigurationDialog(). +*/ +void setDirectoryServers( struct DirectoryServer[], unsigned int size ); + +/*! \ingroup groupConfigDir + \brief Returns the list of directory servers. + + Will mainly be used for saving configuration data; interactive + configuration will be done via the configuration dialog + returned by + \c directoryServiceConfigurationDialog(). +*/ +struct DirectoryServer* directoryServers( int* numServers ); + +/*! \ingroup groupConfigDir + \brief Specifies whether certificates should be retrieved + from a directory server, only locally, or both. +*/ +void setCertificateSource( CertificateSource ); + +/*! \ingroup groupConfigDir + \brief Returns whether certificates should be retrieved + from a directory server, only locally, or both. +*/ +CertificateSource certificateSource( void ); + +/*! \ingroup groupConfigDir + \brief Specifies whether certificates should be retrieved + from a directory server, only locally, or both. +*/ +void setCRLSource( CertificateSource ); + +/*! \ingroup groupConfigDir + \brief Returns whether certificates should be retrieved + from a directory server, only locally, or both. +*/ +CertificateSource crlSource( void ); + + +/*! \ingroup groupCertHand + \brief Returns \c true if and only if the + certificates in the certificate chain starting at + \c certificate are valid. + + If \c level is non-null, the parameter contains + the degree of trust on a backend-specific scale. In an X.509 + implementation, this will either be \c 1 + (valid up to the root certificate) or \c 0 + (not valid up to the root certificate). +*/ +bool certificateValidity( const char* certificate, int* level ); + + +/*! \ingroup groupSignCryptAct + \brief Information record returned by signing and by encrypting + functions - this record should be used together with a + corresponding \c free_StructuringInfo() function call. + + Use this information to compose a MIME object containing signed + and/or encrypted content (or to build a text frame around your + flat non-MIME message body, resp.) + + <b>If</b> value returned in \c makeMimeObject is <b>TRUE</b> the + text strings returned in \c contentTypeMain and \c contentDispMain + and \c contentTEncMain (and, if required, \c content[..]Version and + \c bodyTextVersion and \c content[..]Sig) should be used to compose + a respective MIME object.<br> + If <b>FALSE</b> the texts returned in \c flatTextPrefix and + \c flatTextSeparator and \c flatTextPostfix are to be used instead.<br> + Allways <b>either</b> the \c content[..] and \c bodyTextVersion + parameters <b>or</b> the \c flatText[..] parameters are holding + valid data - never both of them may be used simultaneously + as plugins will just ignore the parameters not matching their + \c makeMimeObject setting. + + When creating your MIME object please observe these common rules: + \li Parameters named \c contentType[..] and \c contentDisp[..] and + \c contentTEnc[..] will return the values for the respective MIME + headers 'Content-Type' and 'Content-Disposition' and + 'Content-Transfer-Encoding'. The following applies to these parameters: + \li The relevant MIME part may <b>only</b> be created if the respective + \c contentType[..] parameter is holding a non-zero-length string. If the + \c contentType[..] parameter value is invalid or holding an empty string + the respective \c contentDisp[..] and \c contentTEnc[..] parameters + should be ignored. + \li If the respective \c contentDisp[..] or \c contentTEnc[..] parameter + is NULL or holding a zero-length string it is up to you whether you want + to add the relevant MIME header yourself, but since it in in the + responsibility of the plugin implementors to provide you with all + neccessary 'Content-[..]' header information you should <b>not need</b> + to define them if they are not returned by the signing or encrypting + function - otherwise this may be considered as a bug in the plugin and + you could report the missing MIME header information to the address + returned by the \c bugURL() function. + + If \c makeMultiMime returns FALSE the \c contentTypeMain returned must + not be altered but used to specify a single part mime object holding the + code bloc, e.g. this is used for 'enveloped-data' single part MIME + objects. In this case you should ignore both the \c content[..]Version + and \c content[..]Code parameters. + + If \c makeMultiMime returns TRUE also the following rules apply: + \li If \c includeCleartext is TRUE you should include the cleartext + as first part of our multipart MIME object, typically this is TRUE + when signing mails but FALSE when encrypting. + \li The \c contentTypeMain returned typically starts with + "multipart/" while providing a "protocol" and a "micalg" parameter: just + add an appropriate \c "; boundary=[your \c boundary \c string]" to get + the complete Content-Type value to be used for the MIME object embedding + both the signed part and the signature part (or - in case of + encrypting - the version part and the code part, resp.). + \li If \c contentTypeVersion is holding a non-zero-length string an + additional MIME part must added immediately before the code part, this + version part's MIME headers must have the unaltered values of + \c contentTypeVersion and (if they are holding non-zero-length strings) + \c contentDispVersion and \c contentTEncVersion, the unaltered contents + of \c bodyTextVersion must be it's body. + \li The value returned in \c contentTypeCode is specifying the complete + Content-Type to be used for this multipart MIME object's signature part + (or - in case of encrypting - for the code part following after the + version part, resp.), you should not add/change/remove anything here + but just use it's unaltered value for specifying the Content-Type header + of the respective MIME part. + \li The same applies to the \c contentDispCode value: just use it's + unaltered value to specify the Content-Disposition header entry of + the respective MIME part. + \li The same applies to the \c contentTEncCode value: just use it's + unaltered value to specify the Content-Transfer-Encoding header of + the respective MIME part. + + <b>If</b> value returned in \c makeMimeObject is <b>FALSE</b> the + text strings returned in \c flatTextPrefix and \c flatTextPostfix + should be used to build a frame around the cleartext and the code + bloc holding the signature (or - in case of encrypting - the encoded + data bloc, resp.).<br> + If \c includeCleartext is TRUE this frame should also include the + cleartext as first bloc, this bloc should be divided from the code bloc + by the contents of \c flatTextSeparator - typically this is used for + signing but not when encrypting.<br> + If \c includeCleartext is FALSE you should ignore both the cleartext + and the \c flatTextSeparator parameter. + + <b>How to use StructuringInfo data in your program:</b> + \li To compose a signed message please act as described below. + \li For constructing an encrypted message just replace the + \c signMessage() call by the respective \c encryptMessage() call + and then proceed exactly the same way. + \li In any case make <b>sure</b> to free your \c ciphertext <b>and</b> + to call \c free_StructuringInfo() when you are done with processing + the data returned by the signing (or encrypting, resp.) function. + +\verbatim + + char* ciphertext; + StructuringInfo structInf; + + if( ! signMessage( cleartext, &ciphertext, certificate, + &structuring ) ) { + + myErrorDialog( "Error: could not sign the message!" ); + + } else { + if( structInf.makeMimeObject ) { + + // Build the main MIME object. + // This is done by + // using the header values returned in + // structInf.contentTypeMain and in + // structInf.contentDispMain and in + // structInf.contentTEncMain. + .. + + if( ! structInf.makeMultiMime ) { + + // Build the main MIME object's body. + // This is done by + // using the code bloc returned in + // ciphertext. + .. + + } else { + + // Build the encapsulated MIME parts. + if( structInf.includeCleartext ) { + + // Build a MIME part holding the cleartext. + // This is done by + // using the original cleartext's headers and by + // taking it's original body text. + .. + + } + if( structInf.contentTypeVersion + && 0 < strlen( structInf.contentTypeVersion ) ) { + + // Build a MIME part holding the version information. + // This is done by + // using the header values returned in + // structInf.contentTypeVersion and + // structInf.contentDispVersion and + // structInf.contentTEncVersion and by + // taking the body contents returned in + // structInf.bodyTextVersion. + .. + + } + if( structInf.contentTypeCode + && 0 < strlen( structInf.contentTypeCode ) ) { + + // Build a MIME part holding the code information. + // This is done by + // using the header values returned in + // structInf.contentTypeCode and + // structInf.contentDispCode and + // structInf.contentTEncCode and by + // taking the body contents returned in + // ciphertext. + .. + + } else { + + // Plugin error! + myErrorDialog( "Error: Cryptography plugin returned a main" + "Content-Type=Multipart/.. but did not " + "specify the code bloc's Content-Type header." + "\nYou may report this bug:" + "\n" + cryptplug.bugURL() ); + } + } + } else { + + // Build a plain message body + // based on the values returned in structInf. + // Note: We do _not_ insert line breaks between the parts since + // it is the plugin job to provide us with ready-to-use + // texts containing all neccessary line breaks. + strcpy( myMessageBody, structInf.plainTextPrefix ); + if( structInf.includeCleartext ) { + strcat( myMessageBody, cleartext ); + strcat( myMessageBody, structInf.plainTextSeparator ); + } + strcat( myMessageBody, *ciphertext ); + strcat( myMessageBody, structInf.plainTextPostfix ); + } + + // free the memory that was allocated + // for the ciphertext + free( ciphertext ); + + // free the memory that was allocated + // for our StructuringInfo's char* members + free_StructuringInfo( &structuring ); + } + +\endverbatim + + \note Make sure to call \c free_StructuringInfo() when you are done + with processing the StructuringInfo data! + + \see free_StructuringInfo + \see signMessage, encryptMessage, encryptAndSignMessage +*/ +struct StructuringInfo { + bool includeCleartext; /*!< specifies whether we should include the + cleartext as first part of our multipart + MIME object (or - for non-MIME + messages - as flat text to be set before + the ciphertext, resp.), typically this + is TRUE when signing mails but FALSE + when encrypting<br> + (this parameter is relevant no matter + whether \c makeMimeObject is TRUE or + FALSE) */ + bool makeMimeObject; /*!< specifies whether we should create a MIME + object or a flat text message body */ + /* the following are used for MIME messages only */ + bool makeMultiMime; /*!< specifies whether we should create a + 'Multipart' MIME object or a single part + object, if FALSE only \c contentTypeMain, + \c contentDispMain and \c contentTEncMain + may be used and all other parameters have + to be ignored<br> + (ignore this parameter if \c makeMimeObject + is FALSE) */ + char* contentTypeMain; /*!< value of the main 'Content-Type' + header<br> + (ignore this parameter if \c makeMimeObject + is FALSE) */ + char* contentDispMain; /*!< value of the main 'Content-Disposition' + header<br> + (ignore this parameter if \c makeMimeObject + is FALSE) */ + char* contentTEncMain; /*!< value of the main + 'Content-TransferEncoding' header<br> + (ignore this parameter if \c makeMimeObject + is FALSE) */ + char* contentTypeVersion; /*!< 'Content-Type' of the additional version + part that might preceed the code part - + if NULL or zero length no version part + must be created<br> + (ignore this parameter if either + \c makeMimeObject or \c makeMultiMime + is FALSE) */ + char* contentDispVersion; /*!< 'Content-Disposition' of the additional + preceeding the code part (only valid if + \c contentTypeVersion holds a + non-zero-length string)<br> + (ignore this parameter if either + \c makeMimeObject or \c makeMultiMime + is FALSE or if \c contentTypeVersion does + not return a non-zero-length string) */ + char* contentTEncVersion; /*!< 'Content-Transfer-Encoding' of the + additional version part (only valid if + \c contentTypeVersion holds a + non-zero-length string)<br> + (ignore this parameter if either + \c makeMimeObject or \c makeMultiMime + is FALSE or if \c contentTypeVersion does + not return a non-zero-length string) */ + char* bodyTextVersion; /*!< body text of the additional version part + (only valid if \c contentTypeVersion + holds a non-zero-length string)<br> + (ignore this parameter if either + \c makeMimeObject or \c makeMultiMime + is FALSE or if \c contentTypeVersion does + not return a non-zero-length string) */ + char* contentTypeCode; /*!< 'Content-Type' of the code part holding + the signature code (or the encrypted + data, resp.)<br> + (ignore this parameter if either + \c makeMimeObject or \c makeMultiMime + is FALSE) */ + char* contentDispCode; /*!< 'Content-Disposition' of the code part<br> + (ignore this parameter if either + \c makeMimeObject or \c makeMultiMime + is FALSE or if \c contentTypeCode does + not return a non-zero-length string) */ + char* contentTEncCode; /*!< 'Content-Type' of the code part<br> + (ignore this parameter if either + \c makeMimeObject or \c makeMultiMime + is FALSE or if \c contentTypeCode does + not return a non-zero-length string) */ + /* the following are used for flat non-MIME messages only */ + char* flatTextPrefix; /*!< text to preceed the main text (or the + code bloc containing the encrypted main + text, resp.)<br> + (ignore this parameter if + \c makeMimeObject is TRUE) */ + char* flatTextSeparator; /*!< text to be put between the main text and + the signature code bloc (not used when + encrypting)<br> + (ignore this parameter if + \c makeMimeObject is TRUE or if + \c includeCleartext is FALSE) */ + char* flatTextPostfix; /*!< text to follow the signature code bloc + (or the encrypted data bloc, resp.)<br> + (ignore this parameter if + \c makeMimeObject is TRUE) */ +}; + + +/*! \ingroup groupAdUsoInterno + \brief If you are not planning to write your own cryptography + plugin <b>you should ignore this</b> function! + + Usage of this function is depreciated for plugin users but highly + recommended for plugin implementors since this is an internal + function for initializing all char* members of a \c StructuringInfo + struct.<br> + This function <b>must</b> be called in <b>any</b> plugin's + implementations of the following functions: + + \c signMessage() <br> + \c encryptMessage() <br> + \c encryptAndSignMessage() + + Calling this function makes sure the corresponding + \c free_StructuringInfo() calls which will be embedded by + your plugin's users into their code will be able to + determine which of the char* members belonging to the + respective's StructuringInfo had been allocated memory + for during previous signing or encrypting actions. + + \see free_StructuringInfo, StructuringInfo + \see signMessage, encryptMessage, encryptAndSignMessage +*/ + inline void init_StructuringInfo( struct StructuringInfo* s ) + { + if( ! s ) return; + + s->includeCleartext = false; + + s->makeMimeObject = false; + s->makeMultiMime = false; + + s->contentTypeMain = 0; + s->contentDispMain = 0; + s->contentTEncMain = 0; + + s->contentTypeVersion = 0; + s->contentDispVersion = 0; + s->contentTEncVersion = 0; + s->bodyTextVersion = 0; + + s->contentTypeCode = 0; + s->contentDispCode = 0; + s->contentTEncCode = 0; + + s->flatTextPrefix = 0; + s->flatTextSeparator = 0; + s->flatTextPostfix = 0; + } + +/*! \ingroup groupSignCryptAct + \brief Important method for freeing all memory that was allocated + for the char* members of a \c StructuringInfo struct - use + this function after <b>each</b> signing or encrypting function + call. + + \note Even when intending to call \c encryptMessage() immediately + after having called \c signMessage() you first <b>must</b> call + the \c free_StructuringInfo() function to make sure all memory is + set free that was allocated for your StructuringInfo's char* members + by the \c signMessage() function! + + \see StructuringInfo +*/ + inline void free_StructuringInfo( struct StructuringInfo* s ) + { + if( ! s ) return; + if( s->contentTypeMain ) free( s->contentTypeMain ); + if( s->contentDispMain ) free( s->contentDispMain ); + if( s->contentTEncMain ) free( s->contentTEncMain ); + if( s->contentTypeVersion ) free( s->contentTypeVersion ); + if( s->contentDispVersion ) free( s->contentDispVersion ); + if( s->contentTEncVersion ) free( s->contentTEncVersion ); + if( s->bodyTextVersion ) free( s->bodyTextVersion ); + if( s->contentTypeCode ) free( s->contentTypeCode ); + if( s->contentDispCode ) free( s->contentDispCode ); + if( s->contentTEncCode ) free( s->contentTEncCode ); + if( s->flatTextPrefix ) free( s->flatTextPrefix ); + if( s->flatTextSeparator ) free( s->flatTextSeparator ); + if( s->flatTextPostfix ) free( s->flatTextPostfix ); + } + + +/*! \ingroup groupSignAct + \brief Signs a message \c cleartext and returns + in \c *ciphertext the signature data bloc that + is to be added to the message. The length returned + in \c *cipherLen tells you the size (==amount of bytes) + of the ciphertext, if the structuring information + would return with contentTEncCode set to "base64" + the ciphertext might contain a char 0x00 + and has to be converted into base64 before sending. + + The signature role is specified by \c certificate. + If \c certificate is \c NULL, the default certificate is used. + + If the message could be signed, the function returns + \c true, otherwise + \c false. + + Use the StructuringInfo data returned in parameter \c structuring + to find out how to build the respective MIME object (or the plain + text message body, resp.). + + \note The function allocates memory for the \c *ciphertext, so + make sure you set free that memory when no longer needing + it (as shown in example code provided with documentation + of the struct \c StructuringInfo). + + \note The function also allocates memory for some char* members + of the StructuringInfo* parameter that you are providing, + therefore you <b>must</b> call the \c free_StructuringInfo() function + to make sure all memory is set free that was allocated. This must be + done <b>before</b> calling the next cryptography function - even if + you intend to call \c encryptMessage() immediately after + \c signMessage(). + + \see StructuringInfo, free_StructuringInfo +*/ +bool signMessage( const char* cleartext, + char** ciphertext, + const size_t* cipherLen, + const char* certificate, + struct StructuringInfo* structuring, + int* errId, + char** errTxt ); + + +/*! \ingroup groupSignAct + */ +struct SignatureMetaDataExtendedInfo +{ + struct tm* creation_time; + SigStatusFlags sigStatusFlags; + char* status_text; + char* keyid; + char* fingerprint; + char* algo; + char* userid; + char* name; + char* comment; + char** emailList; + int emailCount; + unsigned long algo_num; + unsigned long validity; + unsigned long userid_num; + unsigned long keylen; + unsigned long key_created; + unsigned long key_expires; +}; + +/*! \ingroup groupSignAct +*/ +struct SignatureMetaData { + char* status; + struct SignatureMetaDataExtendedInfo* extended_info; + int extended_info_count; + char* nota_xml; + int status_code; +}; + +/*! \ingroup groupSignAct + \brief Checks whether the signature of a message is + valid. + + \c cleartext must never be 0 but be a valid pointer. + + If \c *cleartext > 0 then **cleartext specifies the message text + that was signed and \c signaturetext is the signature itself. + + If \c *cleartext == 0 is an empty string then \c signaturetext is + supposed to contain an opaque signed message part. After checking the + data and verifying the signature the cleartext of the message will be + returned in \c cleartext. The user must free the respective memory + ocupied by *cleartext. + + Depending on the configuration, MUAs might not need to use this. + If \c sigmeta is non-null, the + \c SignatureMetaData object pointed to will + contain meta information about the signature after the + function call. +*/ +bool checkMessageSignature( char** cleartext, + const char* signaturetext, + bool signatureIsBinary, + int signatureLen, + struct SignatureMetaData* sigmeta ); + +/*! \ingroup groupSignAct + \brief Stores the certificates that follow with the message + \c ciphertext locally. +*/ +bool storeCertificatesFromMessage( const char* ciphertext ); + + +/*! \ingroup groupCryptAct + \brief Find all certificate for a given addressee. + + NOTE: The certificate parameter must point to a not-yet allocated + char*. The function will allocate the memory needed and + return the size in newSize. + If secretOnly is true, only secret keys are returned. +*/ +bool findCertificates( const char* addressee, + char** certificates, + int* newSize, + bool secretOnly ); + +/*! \ingroup groupCryptAct + \brief Encrypts an email message in + \c cleartext according to the \c addressee and + the current settings (algorithm, etc.) and + returns the encoded data bloc in \c *ciphertext. + The length returned in \c *cipherLen tells you the + size (==amount of bytes) of the ciphertext, if the + structuring information would return with + contentTEncCode set to "base64" the ciphertext + might contain a char 0x00 and has to be converted + into base64 before sending. + + If the message could be encrypted, the function returns + \c true, otherwise + \c false. + + Use the StructuringInfo data returned in parameter \c structuring + to find out how to build the respective MIME object (or the plain + text message body, resp.). + + \note The function allocates memory for the \c *ciphertext, so + make sure you set free that memory when no longer needing + it (as shown in example code provided with documentation + of the struct \c StructuringInfo). + + \note The function also allocates memory for some char* members + of the StructuringInfo* parameter that you are providing, + therefore you <b>must</b> call the \c free_StructuringInfo() function + to make sure all memory is set free that was allocated. This must be + done <b>before</b> calling the next cryptography function! + + \see StructuringInfo, free_StructuringInfo +*/ +bool encryptMessage( const char* cleartext, + const char** ciphertext, + const size_t* cipherLen, + const char* addressee, + struct StructuringInfo* structuring, + int* errId, + char** errTxt ); + + +/*! \ingroup groupCryptAct + \brief Combines the functionality of + \c encryptMessage() and + \c signMessage(). + + If \c certificate is \c NULL, + the default certificate will be used. + + If the message could be signed and encrypted, the function returns + \c true, otherwise + \c false. + + Use the StructuringInfo data returned in parameter \c structuring + to find out how to build the respective MIME object (or the plain + text message body, resp.). + + \note The function allocates memory for the \c *ciphertext, so + make sure you set free that memory when no longer needing + it (as shown in example code provided with documentation + of the struct \c StructuringInfo). + + \note The function also allocates memory for some char* members + of the StructuringInfo* parameter that you are providing, + therefore you <b>must</b> call the \c free_StructuringInfo() function + to make sure all memory is set free that was allocated. This must be + done <b>before</b> calling the next cryptography function! + + \see StructuringInfo, free_StructuringInfo +*/ +bool encryptAndSignMessage( const char* cleartext, + const char** ciphertext, + const char* certificate, + struct StructuringInfo* structuring ); + +/*! \ingroup groupCryptAct + \brief Tries to decrypt an email message + \c ciphertext and returns the decrypted + message in \c cleartext. + + The \c certificate is used for decryption. If + the message could be decrypted, the function returns + \c true, otherwise + \c false. +*/ +bool decryptMessage( const char* ciphertext, + bool cipherIsBinary, + int cipherLen, + const char** cleartext, + const char* certificate, + int* errId, + char** errTxt ); + +/*! \ingroup groupCryptAct + \brief Combines the functionality of + \c checkMessageSignature() and + \c decryptMessage(). + + If \c certificate is \c NULL, + the default certificate will be used. + If \c sigmeta is non-null, the \c SignatureMetaData + object pointed to will contain meta information about + the signature after the function call. +*/ +bool decryptAndCheckMessage( const char* ciphertext, + bool cipherIsBinary, + int cipherLen, + const char** cleartext, + const char* certificate, + bool* signatureFound, + struct SignatureMetaData* sigmeta, + int* errId, + char** errTxt ); + + +/*! \ingroup groupCertAct + \brief This function returns an XML representation of a dialog + that can be used to fill in the data for requesting a + certificate (which in turn is done with the function + \c requestCertificate() described + next. +*/ +const char* requestCertificateDialog( void ); + +/*! \ingroup groupCertAct + \brief Generates a prototype certificate with the data provided + in the four parameter. The memory returned in \a generatedKey + must be freed with free() by the caller. +*/ +bool requestDecentralCertificate( const char* certparms, + char** generatedKey, int* keyLength ); + +/*! \ingroup groupCertAct + \brief Requests a certificate in a PSE from the CA + specified in \c ca_address. +*/ +bool requestCentralCertificateAndPSE( const char* name, + const char* email, const char* organization, const char* department, + const char* ca_address ); + +/*! \ingroup groupCertAct + \brief Creates a local PSE. +*/ +bool createPSE( void ); + +/*! \ingroup groupCertAct + \brief Parses and adds a certificate returned by a CA upon + request with + \c requestDecentralCertificate() or + \c requestCentralCertificate(). + + If the certificate was requested with + \c requestCentralCertificate(), the + certificate returned will come complete with a PSE which is + also registered with this method. +*/ +bool registerCertificate( const char* ); + +/*! \ingroup groupCertAct + \brief Requests the prolongation of the certificate + \c certificate from the CA + \c ca_address. +*/ +bool requestCertificateProlongation( const char* + certificate, const char* ca_address ); + +/*! \ingroup groupCertAct + \brief Returns an HTML 2-formatted string that describes the + certificate chain of the user's certificate. + + Data displayed is at least the issuer of the certificate, the serial number + of the certificate, the owner of the certificate, the checksum + of the certificate, the validity duration of the certificate, + the usage of the certificate, and the contained email + addresses, if any. +*/ +const char* certificateChain( void ); + +/*! \ingroup groupCertAct + \brief Deletes the specified user certificate from the current + PSE. +*/ +bool deleteCertificate( const char* certificate ); + +/*! \ingroup groupCertAct + \brief Archives the specified user certificate in the current PSE. + + The certificate cannot be used any longer after this + operation unless it is unarchived. +*/ +bool archiveCertificate( const char* certificate ); + + +/*! \ingroup groupCRLAct + \brief Returns a HTML 2-formatted string that describes the + CRL, suitable for display in the MUA. +*/ +const char* displayCRL( void ); + +/*! \ingroup groupCRLAct + \brief Manually update the CRL. CRLs will also be automatically + updated on demand by the backend. + + If there is a local version of a CRL saved, it will be overwritten + with the new CRL from the CA. +*/ +void updateCRL( void ); + +struct CertIterator; + +struct DnPair { + char *key; + char *value; +}; + +struct CertificateInfo { + char** userid; + char* serial; + char* fingerprint; + + char* issuer; + char* chainid; + + char* caps; + + unsigned long created; + unsigned long expire; + + int secret : 1; + int invalid : 1; + int expired : 1; + int disabled : 1; + + + struct DnPair *dnarray; /* parsed values from userid[0] */ +}; + +/*! \function struct CertIterator* startListCertificates( const char* pattern ); + \function struct CertificateInfo* nextCertificate( struct CertIterator* ); + \function void endListCertificates( struct CertIterator* ); + + \ingroup certList + Example that runs through certs matching "Steffen": +\verbatim + struct CertificateInfo* info; + struct CertIterator* it = startListCertificates("Steffen", 0 ); + while( nextCertificate( it, &info ) == GPGME_No_Error && info ) { + do something with info. + dont free() it, the struct will be reused + by the next call to nextCertificate() + } + int truncated = endListCertificates( it ); +\endverbatim +*/ +struct CertIterator* +startListCertificates( const char* pattern, int remote ); + +int +nextCertificate( struct CertIterator*, struct CertificateInfo** result ); + +int +endListCertificates( struct CertIterator* ); + +/*! + Import a certificate that was a result from a search-operation using the startListCertificates(), nextCertificate() funtions. + + The fingerprint must be passed to identify the key. + + Additional info about the import operation is available in the additional_info parameter. The string must be free'd by the user with free(). + */ + +int +importCertificateWithFPR( const char* fingerprint, char** additional_info ); + +/*! + Import a certificate from memory. + + Additional info about the import operation is available in the additional_info parameter. The string must be free'd by the user with free(). +*/ +int +importCertificateFromMem( const char* data, size_t length, char** additional_info ); + +#ifdef __cplusplus +} +#endif +#endif /*CRYPTPLUG_H*/ + |