libkdenetwork Library API Documentation

gpgmepp/context.h

00001 /* context.h - wraps a gpgme key context
00002    Copyright (C) 2003 Klarälvdalens Datakonsult AB
00003 
00004    This file is part of GPGME++.
00005  
00006    GPGME++ is free software; you can redistribute it and/or modify it
00007    under the terms of the GNU General Public License as published by
00008    the Free Software Foundation; either version 2 of the License, or
00009    (at your option) any later version.
00010  
00011    GPGME++ is distributed in the hope that it will be useful, but
00012    WITHOUT ANY WARRANTY; without even the implied warranty of
00013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014    General Public License for more details.
00015 
00016    You should have received a copy of the GNU General Public License
00017    along with GPGME++; if not, write to the Free Software Foundation,
00018    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.  */
00019 
00020 // -*- c++ -*-
00021 #ifndef __GPGMEPP_CONTEXT_H__
00022 #define __GPGMEPP_CONTEXT_H__
00023 
00024 #include <gpgmepp/gpgmefw.h>
00025 
00026 #include <vector>
00027 #include <utility>
00028 
00029 namespace GpgME {
00030 
00031   class Key;
00032   class Data;
00033   class TrustItem;
00034   class ProgressProvider;
00035   class PassphraseProvider;
00036   class EventLoopInteractor;
00037 
00038   class KeyListResult;
00039   class KeyGenerationResult;
00040   class ImportResult;
00041   class DecryptionResult;
00042   class VerificationResult;
00043   class SigningResult;
00044   class EncryptionResult;
00045 
00046   class EngineInfo;
00047 
00048   class Error {
00049   public:
00050     Error( int e=0 ) : mErr( e ) {}
00051 
00052     const char * source() const;
00053     const char * asString() const;
00054 
00055     int code() const;
00056     int sourceID() const;
00057 
00058     bool isCanceled() const;
00059 
00060     operator int() const { return mErr; }
00061     operator bool() const { return mErr && !isCanceled(); }
00062   private:
00063     int mErr;
00064   };
00065 
00066   class Context {
00067     Context( gpgme_ctx_t );
00068   public:
00069     enum Protocol { OpenPGP, CMS, Unknown };
00070 
00071     //
00072     // Creation and destruction:
00073     //
00074 
00075     static Context * createForProtocol( Protocol proto );
00076     virtual ~Context();
00077 
00078     //
00079     // Context Attributes
00080     //
00081 
00082     Protocol protocol() const;
00083 
00084     void setArmor( bool useArmor );
00085     bool armor() const;
00086 
00087     void setTextMode( bool useTextMode );
00088     bool textMode() const;
00089 
00090     enum CertificateInclusion {
00091       AllCertificatesExceptRoot = -2,
00092       AllCertificates = -1,
00093       NoCertificates = 0,
00094       OnlySenderCertificate = 1
00095     };
00096     void setIncludeCertificates( int which );
00097     int includeCertificates() const;
00098 
00099     enum KeyListMode {
00100       Local = 0x1,
00101       Extern = 0x2,
00102       Signatures = 0x4,
00103       Validate = 0x10
00104     };
00105     void setKeyListMode( unsigned int keyListMode );
00106     void addKeyListMode( unsigned int keyListMode );
00107     unsigned int keyListMode() const;
00108 
00109     void setPassphraseProvider( PassphraseProvider * provider );
00110     PassphraseProvider * passphraseProvider() const;
00111 
00112     void setProgressProvider( ProgressProvider * provider );
00113     ProgressProvider * progressProvider() const;
00114 
00115     void setManagedByEventLoopInteractor( bool managed );
00116     bool managedByEventLoopInteractor() const;
00117 
00118     GpgME::Error setLocale( int category, const char * value );
00119 
00120   private:
00121     friend class EventLoopInteractor;
00122     void installIOCallbacks( gpgme_io_cbs * iocbs );
00123     void uninstallIOCallbacks();
00124 
00125   public:
00126     //
00127     //
00128     // Key Management
00129     //
00130     //
00131 
00132     //
00133     // Key Listing
00134     //
00135 
00136     GpgME::Error startKeyListing( const char * pattern=0, bool secretOnly=false );
00137     GpgME::Error startKeyListing( const char * patterns[], bool secretOnly=false );
00138 
00139     Key nextKey( GpgME::Error & e );
00140     
00141     KeyListResult endKeyListing();
00142     KeyListResult keyListResult() const;
00143 
00144     Key key( const char * fingerprint, GpgME::Error & e, bool secret=false );
00145 
00146     //
00147     // Key Generation
00148     //
00149 
00150     KeyGenerationResult generateKey( const char * parameters, Data & pubKey );
00151     GpgME::Error startKeyGeneration( const char * parameters, Data & pubkey );
00152     KeyGenerationResult keyGenerationResult() const;
00153 
00154     //
00155     // Key Export
00156     //
00157 
00158     GpgME::Error exportPublicKeys( const char * pattern, Data & keyData );
00159     GpgME::Error exportPublicKeys( const char * pattern[], Data & keyData );
00160     GpgME::Error startPublicKeyExport( const char * pattern, Data & keyData );
00161     GpgME::Error startPublicKeyExport( const char * pattern[], Data & keyData );
00162 
00163     //
00164     // Key Import
00165     //
00166 
00167     ImportResult importKeys( const Data & data );
00168     GpgME::Error startKeyImport( const Data & data );
00169     ImportResult importResult() const;
00170 
00171     //
00172     // Key Deletion
00173     //
00174 
00175     GpgME::Error deleteKey( const Key & key, bool allowSecretKeyDeletion=false );
00176     GpgME::Error startKeyDeletion( const Key & key, bool allowSecretKeyDeletion=false );
00177 
00178     //
00179     // Trust Item Management
00180     //    
00181 
00182     GpgME::Error startTrustItemListing( const char * pattern, int maxLevel );
00183     TrustItem nextTrustItem( GpgME::Error & e );
00184     GpgME::Error endTrustItemListing();
00185 
00186     //
00187     //
00188     // Crypto Operations
00189     //
00190     //
00191 
00192     //
00193     // Decryption
00194     //
00195 
00196     DecryptionResult decrypt( const Data & cipherText, Data & plainText );
00197     GpgME::Error startDecryption( const Data & cipherText, Data & plainText );
00198     DecryptionResult decryptionResult() const;
00199 
00200     //
00201     // Signature Verification
00202     //
00203 
00204     VerificationResult verifyDetachedSignature( const Data & signature, const Data & signedText );
00205     VerificationResult verifyOpaqueSignature( const Data & signedData, Data & plainText );
00206     GpgME::Error startDetachedSignatureVerification( const Data & signature, const Data & signedText );
00207     GpgME::Error startOpaqueSignatureVerification( const Data & signedData, Data & plainText );
00208     VerificationResult verificationResult() const;
00209 
00210     //
00211     // Combined Decryption and Signature Verification
00212     //
00213 
00214     std::pair<DecryptionResult,VerificationResult> decryptAndVerify( const Data & cipherText, Data & plainText );
00215     GpgME::Error startCombinedDecryptionAndVerification( const Data & cipherText, Data & plainText );
00216     // use verificationResult() and decryptionResult() to retrieve the result objects...
00217 
00218     //
00219     // Signing
00220     //
00221 
00222     void clearSigningKeys();
00223     GpgME::Error addSigningKey( const Key & signer );
00224     Key signingKey( unsigned int index ) const;
00225 
00226     enum SignatureMode { Normal, Detached, Clearsigned };
00227     SigningResult sign( const Data & plainText, Data & signature, SignatureMode mode );
00228     GpgME::Error startSigning( const Data & plainText, Data & signature, SignatureMode mode );
00229     SigningResult signingResult() const;
00230 
00231     //
00232     // Encryption
00233     //
00234 
00235     enum EncryptionFlags { None=0, AlwaysTrust=1 };
00236     EncryptionResult encrypt( const std::vector<Key> & recipients, const Data & plainText, Data & cipherText, EncryptionFlags flags );
00237     GpgME::Error encryptSymmetrically( const Data & plainText, Data & cipherText );
00238     GpgME::Error startEncryption( const std::vector<Key> & recipients, const Data & plainText, Data & cipherText, EncryptionFlags flags );
00239     EncryptionResult encryptionResult() const;
00240 
00241     //
00242     // Combined Signing and Encryption
00243     //
00244 
00245     std::pair<SigningResult,EncryptionResult> signAndEncrypt( const std::vector<Key> & recipients, const Data & plainText, Data & cipherText, EncryptionFlags flags );
00246     GpgME::Error startCombinedSigningAndEncryption( const std::vector<Key> & recipients, const Data & plainText, Data & cipherText, EncryptionFlags flags );
00247     // use encryptionResult() and signingResult() to retrieve the result objects...
00248 
00249     //
00250     //
00251     // Run Control
00252     //
00253     //
00254 
00255     bool poll();
00256     GpgME::Error wait();
00257     GpgME::Error lastError() const;
00258     GpgME::Error cancelPendingOperation();
00259 
00260     class Private;
00261     Private * impl() const { return d; }
00262   private:
00263     Private * d;
00264 
00265   private: // disable...
00266     Context( const Context & );
00267     const Context & operator=( const Context & );
00268   };
00269 
00270   //
00271   //
00272   // Globals
00273   //
00274   //
00275 
00276   GpgME::Error setDefaultLocale( int category, const char * value );
00277 
00278   Context * wait( GpgME::Error & e, bool hang=true );
00279   typedef void (*IdleFunction)(void);
00280   IdleFunction registerIdleFunction( IdleFunction idleFunction );
00281 
00282   typedef void (*IOCallback)( void * data, int fd );
00283 
00284   EngineInfo engineInfo( Context::Protocol proto );
00285 
00286   GpgME::Error checkEngine( Context::Protocol proto );
00287 
00288 } // namespace GpgME
00289 
00290 #endif // __GPGMEPP_CONTEXT_H__
KDE Logo
This file is part of the documentation for libkdenetwork Library Version 3.3.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Mon Apr 4 04:44:05 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003