certmanager Library API Documentation

cryptplug.h

Go to the documentation of this file.
00001 /* -*- Mode: C++ -*-
00002 
00003   this is a C++-ification of:
00004   CRYPTPLUG - an independent cryptography plug-in API
00005 
00006   Copyright (C) 2001,2004 Klarälvdalens Datakonsult AB
00007 
00008   CRYPTPLUG is free software; you can redistribute it and/or modify
00009   it under the terms of GNU General Public License as published by
00010   the Free Software Foundation; version 2 of the License.
00011 
00012   CRYPTPLUG is distributed in the hope that it will be useful,
00013   but WITHOUT ANY WARRANTY; without even the implied warranty of
00014   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015   GNU General Public License for more details.
00016 
00017   You should have received a copy of the GNU General Public License
00018   along with this program; if not, write to the Free Software
00019   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
00020 */
00021 
00022 #ifndef CRYPTPLUG_H
00023 #define CRYPTPLUG_H
00024 
00025 #include <stdlib.h>
00026 
00027 #include <gpgmepp/context.h>
00028 #include <gpgme.h> // need it for gpgme_protocol_t :(
00029 
00030 namespace GpgME {
00031   class ImportResult;
00032 }
00033 
00161 typedef enum {
00162   Feature_undef             = 0,
00163 
00164   Feature_SignMessages      = 1,
00165   Feature_VerifySignatures  = 2,
00166   Feature_EncryptMessages   = 3,
00167   Feature_DecryptMessages   = 4,
00168   Feature_SendCertificates  = 5,
00169   Feature_WarnSignCertificateExpiry = 6,
00170   Feature_WarnSignEmailNotInCertificate = 7,
00171   Feature_PinEntrySettings  = 8,
00172   Feature_StoreMessagesWithSigs = 9,
00173   Feature_EncryptionCRLs    = 10,
00174   Feature_WarnEncryptCertificateExpiry = 11,
00175   Feature_WarnEncryptEmailNotInCertificate = 12,
00176   Feature_StoreMessagesEncrypted = 13,
00177   Feature_CheckCertificatePath = 14,
00178   Feature_CertificateDirectoryService = 15,
00179   Feature_CRLDirectoryService = 16,
00180   Feature_CertificateInfo     = 17
00181 } Feature;
00182 
00183 /* dummy values */
00184 typedef enum {
00185   PinRequest_undef            = 0,
00186 
00187   PinRequest_Always          = 1,
00188   PinRequest_WhenAddingCerts = 2,
00189   PinRequest_AlwaysWhenSigning = 3,
00190   PinRequest_OncePerSession   = 4,
00191   PinRequest_AfterMinutes     = 5
00192 } PinRequests;
00193 
00194 
00195 typedef enum {
00196   SignatureCompoundMode_undef    = 0,
00197 
00198   SignatureCompoundMode_Opaque   = 1,
00199   SignatureCompoundMode_Detached = 2
00200 } SignatureCompoundMode;
00201 
00202 
00203 typedef enum {
00204   SendCert_undef              = 0,
00205 
00206   SendCert_DontSend           = 1,
00207   SendCert_SendOwn            = 2,
00208   SendCert_SendChainWithoutRoot = 3,
00209   SendCert_SendChainWithRoot  = 4
00210 } SendCertificates;
00211 
00212 
00213 typedef enum {
00214   SignAlg_undef               = 0,
00215 
00216   SignAlg_SHA1                = 1
00217 } SignatureAlgorithm;
00218 
00219 
00220 
00221 typedef enum {
00222   EncryptAlg_undef            = 0,
00223 
00224   EncryptAlg_RSA              = 1,
00225   EncryptAlg_SHA1             = 2,
00226   EncryptAlg_TripleDES        = 3
00227 } EncryptionAlgorithm;
00228 
00229 typedef enum {
00230   SignEmail_undef             = 0,
00231 
00232   SignEmail_SignAll           = 1,
00233   SignEmail_Ask               = 2,
00234   SignEmail_DontSign          = 3
00235 } SignEmail;
00236 
00237 typedef enum {
00238   EncryptEmail_undef          = 0,
00239 
00240   EncryptEmail_EncryptAll     = 1,
00241   EncryptEmail_Ask            = 2,
00242   EncryptEmail_DontEncrypt    = 3
00243 } EncryptEmail;
00244 
00245 typedef enum {
00246   CertSrc_undef               = 0,
00247 
00248   CertSrc_Server              = 1,
00249   CertSrc_Local               = 2,
00250   CertSrc_ServerLocal         = CertSrc_Server | CertSrc_Local
00251 } CertificateSource;
00252 
00253 
00279 enum {
00280     SigStat_VALID       = 0x0001,   /* The signature is fully valid */
00281     SigStat_GREEN       = 0x0002,   /* The signature is good. */
00282     SigStat_RED         = 0x0004,   /* The signature is bad. */
00283     SigStat_KEY_REVOKED = 0x0010,   /* One key has been revoked. */
00284     SigStat_KEY_EXPIRED = 0x0020,   /* One key has expired. */
00285     SigStat_SIG_EXPIRED = 0x0040,   /* The signature has expired. */
00286     SigStat_KEY_MISSING = 0x0080,   /* Can't verify: key missing. */
00287     SigStat_CRL_MISSING = 0x0100,   /* CRL not available. */
00288     SigStat_CRL_TOO_OLD = 0x0200,   /* Available CRL is too old. */
00289     SigStat_BAD_POLICY  = 0x0400,   /* A policy was not met. */
00290     SigStat_SYS_ERROR   = 0x0800,   /* A system error occured. */
00291 
00292     SigStat_NUMERICAL_CODE = 0x8000 /* An other error occured. */
00293 };
00294 typedef unsigned long SigStatusFlags;
00295 
00296 class CryptPlugWrapper;
00297 
00298 class CryptPlug {
00299   friend class CryptPlugWrapper;
00300 protected:
00301   CryptPlug();
00302   virtual ~CryptPlug();
00303 
00304   // these must be set by subclasses:
00305   gpgme_protocol_t GPGMEPLUG_PROTOCOL;
00306   GpgME::Context::Protocol mProtocol;
00307 
00308   /* definitions for signing */
00309   // 1. opaque signatures (only used for S/MIME)
00310   int GPGMEPLUG_OPA_SIGN_INCLUDE_CLEARTEXT;
00311   int GPGMEPLUG_OPA_SIGN_MAKE_MIME_OBJECT;
00312   int GPGMEPLUG_OPA_SIGN_MAKE_MULTI_MIME;
00313   const char * GPGMEPLUG_OPA_SIGN_CTYPE_MAIN;
00314   const char * GPGMEPLUG_OPA_SIGN_CDISP_MAIN;
00315   const char * GPGMEPLUG_OPA_SIGN_CTENC_MAIN;
00316   const char * GPGMEPLUG_OPA_SIGN_CTYPE_VERSION;
00317   const char * GPGMEPLUG_OPA_SIGN_CDISP_VERSION;
00318   const char * GPGMEPLUG_OPA_SIGN_CTENC_VERSION;
00319   const char * GPGMEPLUG_OPA_SIGN_BTEXT_VERSION;
00320   const char * GPGMEPLUG_OPA_SIGN_CTYPE_CODE;
00321   const char * GPGMEPLUG_OPA_SIGN_CDISP_CODE;
00322   const char * GPGMEPLUG_OPA_SIGN_CTENC_CODE;
00323   const char * GPGMEPLUG_OPA_SIGN_FLAT_PREFIX;
00324   const char * GPGMEPLUG_OPA_SIGN_FLAT_SEPARATOR;
00325   const char * GPGMEPLUG_OPA_SIGN_FLAT_POSTFIX;
00326   // 2. detached signatures (used for S/MIME and for OpenPGP)
00327   int GPGMEPLUG_DET_SIGN_INCLUDE_CLEARTEXT;
00328   int GPGMEPLUG_DET_SIGN_MAKE_MIME_OBJECT;
00329   int GPGMEPLUG_DET_SIGN_MAKE_MULTI_MIME;
00330   const char * GPGMEPLUG_DET_SIGN_CTYPE_MAIN;
00331   const char * GPGMEPLUG_DET_SIGN_CDISP_MAIN;
00332   const char * GPGMEPLUG_DET_SIGN_CTENC_MAIN;
00333   const char * GPGMEPLUG_DET_SIGN_CTYPE_VERSION;
00334   const char * GPGMEPLUG_DET_SIGN_CDISP_VERSION;
00335   const char * GPGMEPLUG_DET_SIGN_CTENC_VERSION;
00336   const char * GPGMEPLUG_DET_SIGN_BTEXT_VERSION;
00337   const char * GPGMEPLUG_DET_SIGN_CTYPE_CODE;
00338   const char * GPGMEPLUG_DET_SIGN_CDISP_CODE;
00339   const char * GPGMEPLUG_DET_SIGN_CTENC_CODE;
00340   const char * GPGMEPLUG_DET_SIGN_FLAT_PREFIX;
00341   const char * GPGMEPLUG_DET_SIGN_FLAT_SEPARATOR;
00342   const char * GPGMEPLUG_DET_SIGN_FLAT_POSTFIX;
00343   // 3. common definitions for opaque and detached signing
00344   int __GPGMEPLUG_SIGNATURE_CODE_IS_BINARY;
00345 
00346   /* definitions for encoding */
00347   int GPGMEPLUG_ENC_INCLUDE_CLEARTEXT;
00348   int GPGMEPLUG_ENC_MAKE_MIME_OBJECT;
00349   int GPGMEPLUG_ENC_MAKE_MULTI_MIME;
00350   const char * GPGMEPLUG_ENC_CTYPE_MAIN;
00351   const char * GPGMEPLUG_ENC_CDISP_MAIN;
00352   const char * GPGMEPLUG_ENC_CTENC_MAIN;
00353   const char * GPGMEPLUG_ENC_CTYPE_VERSION;
00354   const char * GPGMEPLUG_ENC_CDISP_VERSION;
00355   const char * GPGMEPLUG_ENC_CTENC_VERSION;
00356   const char * GPGMEPLUG_ENC_BTEXT_VERSION;
00357   const char * GPGMEPLUG_ENC_CTYPE_CODE;
00358   const char * GPGMEPLUG_ENC_CDISP_CODE;
00359   const char * GPGMEPLUG_ENC_CTENC_CODE;
00360   const char * GPGMEPLUG_ENC_FLAT_PREFIX;
00361   const char * GPGMEPLUG_ENC_FLAT_SEPARATOR;
00362   const char * GPGMEPLUG_ENC_FLAT_POSTFIX;
00363   int __GPGMEPLUG_ENCRYPTED_CODE_IS_BINARY;
00364   // end-of(these must be set by subclasses)
00365 
00366 public:
00367 
00368 #define CRYPTPLUG_CERT_DOES_NEVER_EXPIRE 365000
00369 
00370 
00371 
00372 
00384 const char* libVersion( void );
00385 
00397 const char* bugURL( void );
00398 
00399 
00414 int interfaceVersion (int *min_version);
00415 #define CRYPTPLUG_ERR_WRONG_KEY_USAGE 0x7070
00416 
00429 bool initialize( void );
00430 
00442 //void deinitialize( void );
00443 
00456 bool hasFeature( Feature );
00457 
00667 struct StructuringInfo {
00668   bool includeCleartext;     
00678   bool  makeMimeObject;      
00680   /* the following are used for MIME messages only */
00681   bool  makeMultiMime;       
00689   char* contentTypeMain;     
00693   char* contentDispMain;     
00697   char* contentTEncMain;     
00701   char* contentTypeVersion;  
00708   char* contentDispVersion;  
00716   char* contentTEncVersion;  
00724   char* bodyTextVersion;     
00731   char* contentTypeCode;     
00737   char* contentDispCode;     
00742   char* contentTEncCode;     
00747   /* the following are used for flat non-MIME messages only */
00748   char* flatTextPrefix;      
00753   char* flatTextSeparator;   
00759   char* flatTextPostfix;     
00763 };
00764 
00765 
00791   inline void init_StructuringInfo( struct StructuringInfo* s )
00792   {
00793     if( ! s ) return;
00794 
00795     s->includeCleartext = false;
00796 
00797     s->makeMimeObject = false;
00798     s->makeMultiMime = false;
00799 
00800     s->contentTypeMain = 0;
00801     s->contentDispMain = 0;
00802     s->contentTEncMain = 0;
00803 
00804     s->contentTypeVersion = 0;
00805     s->contentDispVersion = 0;
00806     s->contentTEncVersion = 0;
00807     s->bodyTextVersion = 0;
00808 
00809     s->contentTypeCode = 0;
00810     s->contentDispCode = 0;
00811     s->contentTEncCode = 0;
00812 
00813     s->flatTextPrefix = 0;
00814     s->flatTextSeparator = 0;
00815     s->flatTextPostfix = 0;
00816   }
00817 
00832   inline void free_StructuringInfo( struct StructuringInfo* s )
00833   {
00834     if( ! s ) return;
00835     if( s->contentTypeMain )    free( s->contentTypeMain );
00836     if( s->contentDispMain )    free( s->contentDispMain );
00837     if( s->contentTEncMain )    free( s->contentTEncMain );
00838     if( s->contentTypeVersion ) free( s->contentTypeVersion );
00839     if( s->contentDispVersion ) free( s->contentDispVersion );
00840     if( s->contentTEncVersion ) free( s->contentTEncVersion );
00841     if( s->bodyTextVersion )    free( s->bodyTextVersion );
00842     if( s->contentTypeCode )    free( s->contentTypeCode );
00843     if( s->contentDispCode )    free( s->contentDispCode );
00844     if( s->contentTEncCode )    free( s->contentTEncCode );
00845     if( s->flatTextPrefix )     free( s->flatTextPrefix );
00846     if( s->flatTextSeparator )  free( s->flatTextSeparator );
00847     if( s->flatTextPostfix )    free( s->flatTextPostfix );
00848   }
00849 
00850 
00887 bool signMessage( const char*  cleartext,
00888                   char** ciphertext,
00889                   const size_t* cipherLen,
00890                   const char*  certificate,
00891                   struct StructuringInfo* structuring,
00892                   int* errId,
00893                   char** errTxt,
00894           SendCertificates sendCertificates,
00895           SignatureCompoundMode signatureCompoundMode );
00896 
00897 
00900 struct SignatureMetaDataExtendedInfo
00901 {
00902     struct tm* creation_time;
00903     SigStatusFlags sigStatusFlags;
00904     char* status_text;
00905     char* keyid;
00906     char* fingerprint;
00907     char* algo;
00908     char* userid;
00909     char* name;
00910     char* comment;
00911     char** emailList;
00912     int    emailCount;
00913     unsigned long algo_num;
00914     unsigned long validity;
00915     unsigned long userid_num;
00916     unsigned long keylen;
00917     unsigned long key_created;
00918     unsigned long key_expires;
00919 };
00920 
00923 struct SignatureMetaData {
00924     char* status;
00925     struct SignatureMetaDataExtendedInfo* extended_info;
00926     int extended_info_count;
00927     int status_code;
00928 };
00929 
00951 bool checkMessageSignature( char** cleartext,
00952                             const char* signaturetext,
00953                             bool signatureIsBinary,
00954                             int signatureLen,
00955                             struct SignatureMetaData* sigmeta,
00956                             char** attrOrder,
00957                             const char* unknownAttrsHandling );
00958 
00963 bool storeCertificatesFromMessage( const char* ciphertext );
00964 
00965 
00974 bool findCertificates( const char* addressee,
00975                        char** certificates,
00976                        int* newSize,
00977                        bool secretOnly,
00978                        char** attrOrder,
00979                        const char* unknownAttrsHandling );
00980 
01014 bool encryptMessage( const char*  cleartext,
01015                      const char** ciphertext,
01016                      const size_t* cipherLen,
01017                      const char*  addressee,
01018                      struct StructuringInfo* structuring,
01019                      int* errId,
01020                      char** errTxt );
01021 
01022 
01052 bool encryptAndSignMessage( const char* cleartext,
01053                             const char** ciphertext,
01054                             const char* certificate,
01055                             struct StructuringInfo* structuring );
01056 
01067 bool decryptMessage( const char*  ciphertext,
01068                      bool         cipherIsBinary,
01069                      int          cipherLen,
01070                      const char** cleartext,
01071                      const char*  certificate,
01072                      int* errId,
01073                      char** errTxt );
01074 
01086 bool decryptAndCheckMessage( const char*  ciphertext,
01087                              bool         cipherIsBinary,
01088                              int          cipherLen,
01089                              const char** cleartext,
01090                              const char*  certificate,
01091                              bool*        signatureFound,
01092                              struct SignatureMetaData* sigmeta,
01093                              int*   errId,
01094                              char** errTxt,
01095                              char** attrOrder,
01096                              const char* unknownAttrsHandling );
01097 
01098 
01099 struct CertIterator;
01100 
01101 struct DnPair {
01102     char *key;
01103     char *value;
01104 };
01105 
01106 struct CertificateInfo {
01107   char** userid;
01108   char* userid_0_org;
01109   char* serial;
01110   char* fingerprint;
01111 
01112   char* issuer_org;
01113   char* issuer_reord;
01114   char* chainid;
01115 
01116   char* caps;
01117 
01118   unsigned long created;
01119   unsigned long expire;
01120 
01121   int secret   : 1;
01122   int invalid  : 1;
01123   int expired  : 1;
01124   int disabled : 1;
01125 
01126   struct DnPair *dnarray; /* parsed values from userid[0] */
01127 };
01128 
01146 struct CertIterator*
01147 startListCertificates( const char* pattern, int remote );
01148 
01149 int
01150 nextCertificate( struct CertIterator*,
01151                  struct CertificateInfo** result,
01152                  char** attrOrder,
01153                  const char* unknownAttrsHandling );
01154 
01155 int
01156 endListCertificates( struct CertIterator* );
01157 
01161   GpgME::ImportResult importCertificateFromMem( const char* data, size_t length );
01162 }; // class CryptPlug
01163 
01164 class SMIMECryptPlug : public CryptPlug {
01165 public:
01166   SMIMECryptPlug();
01167 };
01168 
01169 class OpenPGPCryptPlug : public CryptPlug {
01170 public:
01171   OpenPGPCryptPlug();
01172 };
01173 
01174 #endif /*CRYPTPLUG_H*/
01175 
KDE Logo
This file is part of the documentation for certmanager Library Version 3.3.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Mar 23 22:39:32 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003