1/*
2 context.h - wraps a gpgme key context
3 Copyright (C) 2003, 2007 Klarälvdalens Datakonsult AB
4
5 This file is part of GPGME++.
6
7 GPGME++ is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 GPGME++ is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with GPGME++; see the file COPYING.LIB. If not, write to the
19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA.
21*/
22
23// -*- c++ -*-
24#ifndef __GPGMEPP_CONTEXT_H__
25#define __GPGMEPP_CONTEXT_H__
26
27#include <gpgme++/global.h>
28
29#include <gpgme++/error.h>
30#include <gpgme++/verificationresult.h> // for Signature::Notation
31
32#include <memory>
33#include <vector>
34#include <utility>
35#include <iosfwd>
36
37namespace GpgME {
38
39 class Key;
40 class Data;
41 class TrustItem;
42 class ProgressProvider;
43 class PassphraseProvider;
44 class EventLoopInteractor;
45 class EditInteractor;
46 class AssuanTransaction;
47
48 class AssuanResult;
49 class KeyListResult;
50 class KeyGenerationResult;
51 class ImportResult;
52 class DecryptionResult;
53 class VerificationResult;
54 class SigningResult;
55 class EncryptionResult;
56 class VfsMountResult;
57
58 class EngineInfo;
59
60 class GPGMEPP_EXPORT Context {
61 explicit Context( gpgme_ctx_t );
62 public:
63 //using GpgME::Protocol;
64
65 //
66 // Creation and destruction:
67 //
68
69 static Context * createForProtocol( Protocol proto );
70 static std::auto_ptr<Context> createForEngine( Engine engine, Error * err=0 );
71 virtual ~Context();
72
73 //
74 // Context Attributes
75 //
76
77 Protocol protocol() const;
78
79 void setArmor( bool useArmor );
80 bool armor() const;
81
82 void setTextMode( bool useTextMode );
83 bool textMode() const;
84
85 enum CertificateInclusion {
86 DefaultCertificates = -256,
87 AllCertificatesExceptRoot = -2,
88 AllCertificates = -1,
89 NoCertificates = 0,
90 OnlySenderCertificate = 1
91 };
92 void setIncludeCertificates( int which );
93 int includeCertificates() const;
94
95 //using GpgME::KeyListMode;
96 void setKeyListMode( unsigned int keyListMode );
97 void addKeyListMode( unsigned int keyListMode );
98 unsigned int keyListMode() const;
99
100 void setPassphraseProvider( PassphraseProvider * provider );
101 PassphraseProvider * passphraseProvider() const;
102
103 void setProgressProvider( ProgressProvider * provider );
104 ProgressProvider * progressProvider() const;
105
106 void setManagedByEventLoopInteractor( bool managed );
107 bool managedByEventLoopInteractor() const;
108
109 GpgME::Error setLocale( int category, const char * value );
110
111 EngineInfo engineInfo() const;
112 GpgME::Error setEngineFileName( const char * filename );
113 GpgME::Error setEngineHomeDirectory( const char * filename );
114
115 private:
116 friend class ::GpgME::EventLoopInteractor;
117 void installIOCallbacks( gpgme_io_cbs * iocbs );
118 void uninstallIOCallbacks();
119
120 public:
121 //
122 //
123 // Key Management
124 //
125 //
126
127 //
128 // Key Listing
129 //
130
131 GpgME::Error startKeyListing( const char * pattern=0, bool secretOnly=false );
132 GpgME::Error startKeyListing( const char * patterns[], bool secretOnly=false );
133
134 Key nextKey( GpgME::Error & e );
135
136 KeyListResult endKeyListing();
137 KeyListResult keyListResult() const;
138
139 Key key( const char * fingerprint, GpgME::Error & e, bool secret=false );
140
141 //
142 // Key Generation
143 //
144
145 KeyGenerationResult generateKey( const char * parameters, Data & pubKey );
146 GpgME::Error startKeyGeneration( const char * parameters, Data & pubkey );
147 KeyGenerationResult keyGenerationResult() const;
148
149 //
150 // Key Export
151 //
152
153 GpgME::Error exportPublicKeys( const char * pattern, Data & keyData );
154 GpgME::Error exportPublicKeys( const char * pattern[], Data & keyData );
155 GpgME::Error startPublicKeyExport( const char * pattern, Data & keyData );
156 GpgME::Error startPublicKeyExport( const char * pattern[], Data & keyData );
157
158 //
159 // Key Import
160 //
161
162 ImportResult importKeys( const Data & data );
163 ImportResult importKeys( const std::vector<Key> & keys );
164 GpgME::Error startKeyImport( const Data & data );
165 GpgME::Error startKeyImport( const std::vector<Key> & keys );
166 ImportResult importResult() const;
167
168 //
169 // Key Deletion
170 //
171
172 GpgME::Error deleteKey( const Key & key, bool allowSecretKeyDeletion=false );
173 GpgME::Error startKeyDeletion( const Key & key, bool allowSecretKeyDeletion=false );
174
175 //
176 // Passphrase changing
177 //
178
179 GpgME::Error passwd( const Key & key );
180 GpgME::Error startPasswd( const Key & key );
181
182 //
183 // Key Editing
184 //
185
186 GpgME::Error edit( const Key & key, std::auto_ptr<EditInteractor> function, Data & out );
187 GpgME::Error startEditing( const Key & key, std::auto_ptr<EditInteractor> function, Data & out );
188
189 EditInteractor * lastEditInteractor() const;
190 std::auto_ptr<EditInteractor> takeLastEditInteractor();
191
192 //
193 // SmartCard Editing
194 //
195
196 GpgME::Error cardEdit( const Key & key, std::auto_ptr<EditInteractor> function, Data & out );
197 GpgME::Error startCardEditing( const Key & key, std::auto_ptr<EditInteractor> function, Data & out );
198
199 EditInteractor * lastCardEditInteractor() const;
200 std::auto_ptr<EditInteractor> takeLastCardEditInteractor();
201
202 //
203 // Trust Item Management
204 //
205
206 GpgME::Error startTrustItemListing( const char * pattern, int maxLevel );
207 TrustItem nextTrustItem( GpgME::Error & e );
208 GpgME::Error endTrustItemListing();
209
210 //
211 // Assuan Transactions
212 //
213
214 AssuanResult assuanTransact( const char * command, std::auto_ptr<AssuanTransaction> transaction );
215 AssuanResult assuanTransact( const char * command );
216 GpgME::Error startAssuanTransaction( const char * command, std::auto_ptr<AssuanTransaction> transaction );
217 GpgME::Error startAssuanTransaction( const char * command );
218 AssuanResult assuanResult() const;
219
220 AssuanTransaction * lastAssuanTransaction() const;
221 std::auto_ptr<AssuanTransaction> takeLastAssuanTransaction();
222
223 //
224 //
225 // Crypto Operations
226 //
227 //
228
229 //
230 // Decryption
231 //
232
233 DecryptionResult decrypt( const Data & cipherText, Data & plainText );
234 GpgME::Error startDecryption( const Data & cipherText, Data & plainText );
235 DecryptionResult decryptionResult() const;
236
237 //
238 // Signature Verification
239 //
240
241 VerificationResult verifyDetachedSignature( const Data & signature, const Data & signedText );
242 VerificationResult verifyOpaqueSignature( const Data & signedData, Data & plainText );
243 GpgME::Error startDetachedSignatureVerification( const Data & signature, const Data & signedText );
244 GpgME::Error startOpaqueSignatureVerification( const Data & signedData, Data & plainText );
245 VerificationResult verificationResult() const;
246
247 //
248 // Combined Decryption and Signature Verification
249 //
250
251 std::pair<DecryptionResult,VerificationResult> decryptAndVerify( const Data & cipherText, Data & plainText );
252 GpgME::Error startCombinedDecryptionAndVerification( const Data & cipherText, Data & plainText );
253 // use verificationResult() and decryptionResult() to retrieve the result objects...
254
255 //
256 // Signing
257 //
258
259 void clearSigningKeys();
260 GpgME::Error addSigningKey( const Key & signer );
261 Key signingKey( unsigned int index ) const;
262 std::vector<Key> signingKeys() const;
263
264 void clearSignatureNotations();
265 GpgME::Error addSignatureNotation( const char * name, const char * value, unsigned int flags=0 );
266 GpgME::Error addSignaturePolicyURL( const char * url, bool critical=false );
267 const char * signaturePolicyURL() const;
268 Notation signatureNotation( unsigned int index ) const;
269 std::vector<Notation> signatureNotations() const;
270
271 //using GpgME::SignatureMode;
272 SigningResult sign( const Data & plainText, Data & signature, SignatureMode mode );
273 GpgME::Error startSigning( const Data & plainText, Data & signature, SignatureMode mode );
274 SigningResult signingResult() const;
275
276 //
277 // Encryption
278 //
279
280 enum EncryptionFlags { None=0, AlwaysTrust=1, NoEncryptTo=2 };
281 EncryptionResult encrypt( const std::vector<Key> & recipients, const Data & plainText, Data & cipherText, EncryptionFlags flags );
282 GpgME::Error encryptSymmetrically( const Data & plainText, Data & cipherText );
283 GpgME::Error startEncryption( const std::vector<Key> & recipients, const Data & plainText, Data & cipherText, EncryptionFlags flags );
284 EncryptionResult encryptionResult() const;
285
286 //
287 // Combined Signing and Encryption
288 //
289
290 std::pair<SigningResult,EncryptionResult> signAndEncrypt( const std::vector<Key> & recipients, const Data & plainText, Data & cipherText, EncryptionFlags flags );
291 GpgME::Error startCombinedSigningAndEncryption( const std::vector<Key> & recipients, const Data & plainText, Data & cipherText, EncryptionFlags flags );
292 // use encryptionResult() and signingResult() to retrieve the result objects...
293
294 //
295 //
296 // Audit Log
297 //
298 //
299 enum AuditLogFlags {
300 HtmlAuditLog = 1,
301 AuditLogWithHelp = 128
302 };
303 GpgME::Error startGetAuditLog( Data & output, unsigned int flags=0 );
304 GpgME::Error getAuditLog( Data & output, unsigned int flags=0 );
305
306 //
307 //
308 // G13 crypto container operations
309 //
310 //
311 GpgME::Error createVFS( const char *containerFile, const std::vector<Key> &recipients );
312 VfsMountResult mountVFS( const char *containerFile, const char *mountDir );
313
314 //
315 //
316 // Run Control
317 //
318 //
319
320 bool poll();
321 GpgME::Error wait();
322 GpgME::Error lastError() const;
323 GpgME::Error cancelPendingOperation();
324
325 class Private;
326 const Private * impl() const { return d; }
327 Private * impl() { return d; }
328 private:
329 Private * const d;
330
331 private: // disable...
332 Context( const Context & );
333 const Context & operator=( const Context & );
334 };
335
336 GPGMEPP_EXPORT std::ostream & operator<<( std::ostream & os, Context::CertificateInclusion incl );
337 GPGMEPP_EXPORT std::ostream & operator<<( std::ostream & os, Context::EncryptionFlags flags );
338 GPGMEPP_EXPORT std::ostream & operator<<( std::ostream & os, Context::AuditLogFlags flags );
339
340} // namespace GpgME
341
342#endif // __GPGMEPP_CONTEXT_H__
343