Line data Source code
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 "global.h"
28 :
29 : #include "error.h"
30 : #include "verificationresult.h" // for Signature::Notation
31 :
32 : #include <memory>
33 : #include <vector>
34 : #include <utility>
35 : #include <iosfwd>
36 :
37 : namespace GpgME
38 : {
39 :
40 : class Key;
41 : class Data;
42 : class TrustItem;
43 : class ProgressProvider;
44 : class PassphraseProvider;
45 : class EventLoopInteractor;
46 : class EditInteractor;
47 : class AssuanTransaction;
48 :
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 : {
62 : explicit Context(gpgme_ctx_t);
63 : public:
64 : //using GpgME::Protocol;
65 :
66 : //
67 : // Creation and destruction:
68 : //
69 :
70 : static Context *createForProtocol(Protocol proto);
71 : static std::unique_ptr<Context> createForEngine(Engine engine, Error *err = 0);
72 : virtual ~Context();
73 :
74 : //
75 : // Context Attributes
76 : //
77 :
78 : Protocol protocol() const;
79 :
80 : void setArmor(bool useArmor);
81 : bool armor() const;
82 :
83 : void setTextMode(bool useTextMode);
84 : bool textMode() const;
85 :
86 : void setOffline(bool useOfflineMode);
87 : bool offline() const;
88 :
89 : enum CertificateInclusion {
90 : DefaultCertificates = -256,
91 : AllCertificatesExceptRoot = -2,
92 : AllCertificates = -1,
93 : NoCertificates = 0,
94 : OnlySenderCertificate = 1
95 : };
96 : void setIncludeCertificates(int which);
97 : int includeCertificates() const;
98 :
99 : //using GpgME::KeyListMode;
100 : void setKeyListMode(unsigned int keyListMode);
101 : void addKeyListMode(unsigned int keyListMode);
102 : unsigned int keyListMode() const;
103 :
104 : /** Set the passphrase provider
105 : *
106 : * To avoid problems where a class using a context registers
107 : * itself as the provider the Context does not take ownership
108 : * of the provider and the caller must ensure that the provider
109 : * is deleted if it is no longer needed.
110 : */
111 : void setPassphraseProvider(PassphraseProvider *provider);
112 : PassphraseProvider *passphraseProvider() const;
113 :
114 : /** Set the progress provider
115 : *
116 : * To avoid problems where a class using a context registers
117 : * itself as the provider the Context does not take ownership
118 : * of the provider and the caller must ensure that the provider
119 : * is deleted if it is no longer needed.
120 : */
121 : void setProgressProvider(ProgressProvider *provider);
122 : ProgressProvider *progressProvider() const;
123 :
124 : void setManagedByEventLoopInteractor(bool managed);
125 : bool managedByEventLoopInteractor() const;
126 :
127 : GpgME::Error setLocale(int category, const char *value);
128 :
129 : EngineInfo engineInfo() const;
130 : GpgME::Error setEngineFileName(const char *filename);
131 : GpgME::Error setEngineHomeDirectory(const char *filename);
132 :
133 : enum PinentryMode{
134 : PinentryDefault = 0,
135 : PinentryAsk = 1,
136 : PinentryCancel = 2,
137 : PinentryError = 3,
138 : PinentryLoopback = 4
139 : };
140 : GpgME::Error setPinentryMode(PinentryMode which);
141 : PinentryMode pinentryMode() const;
142 :
143 : private:
144 : friend class ::GpgME::EventLoopInteractor;
145 : void installIOCallbacks(gpgme_io_cbs *iocbs);
146 : void uninstallIOCallbacks();
147 :
148 : public:
149 : //
150 : //
151 : // Key Management
152 : //
153 : //
154 :
155 : //
156 : // Key Listing
157 : //
158 :
159 : GpgME::Error startKeyListing(const char *pattern = 0, bool secretOnly = false);
160 : GpgME::Error startKeyListing(const char *patterns[], bool secretOnly = false);
161 :
162 : Key nextKey(GpgME::Error &e);
163 :
164 : KeyListResult endKeyListing();
165 : KeyListResult keyListResult() const;
166 :
167 : Key key(const char *fingerprint, GpgME::Error &e, bool secret = false);
168 :
169 : //
170 : // Key Generation
171 : //
172 :
173 : KeyGenerationResult generateKey(const char *parameters, Data &pubKey);
174 : GpgME::Error startKeyGeneration(const char *parameters, Data &pubkey);
175 : KeyGenerationResult keyGenerationResult() const;
176 :
177 : //
178 : // Key Export
179 : //
180 :
181 : GpgME::Error exportPublicKeys(const char *pattern, Data &keyData);
182 : GpgME::Error exportPublicKeys(const char *pattern[], Data &keyData);
183 : GpgME::Error startPublicKeyExport(const char *pattern, Data &keyData);
184 : GpgME::Error startPublicKeyExport(const char *pattern[], Data &keyData);
185 :
186 : //
187 : // Key Import
188 : //
189 :
190 : ImportResult importKeys(const Data &data);
191 : ImportResult importKeys(const std::vector<Key> &keys);
192 : GpgME::Error startKeyImport(const Data &data);
193 : GpgME::Error startKeyImport(const std::vector<Key> &keys);
194 : ImportResult importResult() const;
195 :
196 : //
197 : // Key Deletion
198 : //
199 :
200 : GpgME::Error deleteKey(const Key &key, bool allowSecretKeyDeletion = false);
201 : GpgME::Error startKeyDeletion(const Key &key, bool allowSecretKeyDeletion = false);
202 :
203 : //
204 : // Passphrase changing
205 : //
206 :
207 : GpgME::Error passwd(const Key &key);
208 : GpgME::Error startPasswd(const Key &key);
209 :
210 : //
211 : // Key Editing
212 : //
213 :
214 : GpgME::Error edit(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
215 : GpgME::Error startEditing(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
216 :
217 : EditInteractor *lastEditInteractor() const;
218 : std::unique_ptr<EditInteractor> takeLastEditInteractor();
219 :
220 : //
221 : // SmartCard Editing
222 : //
223 :
224 : GpgME::Error cardEdit(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
225 : GpgME::Error startCardEditing(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
226 :
227 : EditInteractor *lastCardEditInteractor() const;
228 : std::unique_ptr<EditInteractor> takeLastCardEditInteractor();
229 :
230 : //
231 : // Trust Item Management
232 : //
233 :
234 : GpgME::Error startTrustItemListing(const char *pattern, int maxLevel);
235 : TrustItem nextTrustItem(GpgME::Error &e);
236 : GpgME::Error endTrustItemListing();
237 :
238 : //
239 : // Assuan Transactions
240 : //
241 :
242 : GpgME::Error assuanTransact(const char *command, std::unique_ptr<AssuanTransaction> transaction);
243 : GpgME::Error assuanTransact(const char *command);
244 : GpgME::Error startAssuanTransaction(const char *command, std::unique_ptr<AssuanTransaction> transaction);
245 : GpgME::Error startAssuanTransaction(const char *command);
246 :
247 : AssuanTransaction *lastAssuanTransaction() const;
248 : std::unique_ptr<AssuanTransaction> takeLastAssuanTransaction();
249 :
250 : //
251 : //
252 : // Crypto Operations
253 : //
254 : //
255 :
256 : //
257 : // Decryption
258 : //
259 :
260 : DecryptionResult decrypt(const Data &cipherText, Data &plainText);
261 : GpgME::Error startDecryption(const Data &cipherText, Data &plainText);
262 : DecryptionResult decryptionResult() const;
263 :
264 : //
265 : // Signature Verification
266 : //
267 :
268 : VerificationResult verifyDetachedSignature(const Data &signature, const Data &signedText);
269 : VerificationResult verifyOpaqueSignature(const Data &signedData, Data &plainText);
270 : GpgME::Error startDetachedSignatureVerification(const Data &signature, const Data &signedText);
271 : GpgME::Error startOpaqueSignatureVerification(const Data &signedData, Data &plainText);
272 : VerificationResult verificationResult() const;
273 :
274 : //
275 : // Combined Decryption and Signature Verification
276 : //
277 :
278 : std::pair<DecryptionResult, VerificationResult> decryptAndVerify(const Data &cipherText, Data &plainText);
279 : GpgME::Error startCombinedDecryptionAndVerification(const Data &cipherText, Data &plainText);
280 : // use verificationResult() and decryptionResult() to retrieve the result objects...
281 :
282 : //
283 : // Signing
284 : //
285 :
286 : void clearSigningKeys();
287 : GpgME::Error addSigningKey(const Key &signer);
288 : Key signingKey(unsigned int index) const;
289 : std::vector<Key> signingKeys() const;
290 :
291 : void clearSignatureNotations();
292 : GpgME::Error addSignatureNotation(const char *name, const char *value, unsigned int flags = 0);
293 : GpgME::Error addSignaturePolicyURL(const char *url, bool critical = false);
294 : const char *signaturePolicyURL() const;
295 : Notation signatureNotation(unsigned int index) const;
296 : std::vector<Notation> signatureNotations() const;
297 :
298 : //using GpgME::SignatureMode;
299 : SigningResult sign(const Data &plainText, Data &signature, SignatureMode mode);
300 : GpgME::Error startSigning(const Data &plainText, Data &signature, SignatureMode mode);
301 : SigningResult signingResult() const;
302 :
303 : //
304 : // Encryption
305 : //
306 :
307 : enum EncryptionFlags {
308 : None = 0,
309 : AlwaysTrust = 1,
310 : NoEncryptTo = 2,
311 : Prepare = 4,
312 : ExpectSign = 8,
313 : NoCompress = 16,
314 : Symmetric = 32
315 : };
316 : EncryptionResult encrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
317 : GpgME::Error encryptSymmetrically(const Data &plainText, Data &cipherText);
318 : GpgME::Error startEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
319 : EncryptionResult encryptionResult() const;
320 :
321 : //
322 : // Combined Signing and Encryption
323 : //
324 :
325 : std::pair<SigningResult, EncryptionResult> signAndEncrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
326 : GpgME::Error startCombinedSigningAndEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
327 : // use encryptionResult() and signingResult() to retrieve the result objects...
328 :
329 : //
330 : //
331 : // Audit Log
332 : //
333 : //
334 : enum AuditLogFlags {
335 : HtmlAuditLog = 1,
336 : AuditLogWithHelp = 128
337 : };
338 : GpgME::Error startGetAuditLog(Data &output, unsigned int flags = 0);
339 : GpgME::Error getAuditLog(Data &output, unsigned int flags = 0);
340 :
341 : //
342 : //
343 : // G13 crypto container operations
344 : //
345 : //
346 : GpgME::Error createVFS(const char *containerFile, const std::vector<Key> &recipients);
347 : VfsMountResult mountVFS(const char *containerFile, const char *mountDir);
348 :
349 : // Spawn Engine
350 : enum SpawnFlags {
351 : SpawnNone = 0,
352 : SpawnDetached = 1,
353 : SpawnAllowSetFg = 2
354 : };
355 : /** Spwan the process \a file with arguments \a argv.
356 : *
357 : * If a data parameter is null the /dev/null will be
358 : * used. (Or other platform stuff).
359 : *
360 : * @param file The executable to start.
361 : * @param argv list of arguments file should be argv[0].
362 : * @param input The data to be sent through stdin.
363 : * @param output The data to be recieve the stdout.
364 : * @param err The data to recieve stderr.
365 : * @param flags Additional flags.
366 : *
367 : * @returns An error or empty error.
368 : */
369 : GpgME::Error spawn(const char *file, const char *argv[],
370 : Data &input, Data &output, Data &err,
371 : SpawnFlags flags);
372 : /** Async variant of spawn. Immediately returns after starting the
373 : * process. */
374 : GpgME::Error spawnAsync(const char *file, const char *argv[],
375 : Data &input, Data &output,
376 : Data &err, SpawnFlags flags);
377 : //
378 : //
379 : // Run Control
380 : //
381 : //
382 :
383 : bool poll();
384 : GpgME::Error wait();
385 : GpgME::Error lastError() const;
386 : GpgME::Error cancelPendingOperation();
387 :
388 : class Private;
389 : const Private *impl() const
390 : {
391 : return d;
392 : }
393 0 : Private *impl()
394 : {
395 0 : return d;
396 : }
397 : private:
398 : // Helper functions that need to be context because they rely
399 : // on the "Friendlyness" of context to access the gpgme types.
400 : gpgme_key_t *getKeysFromRecipients(const std::vector<Key> &recipients);
401 :
402 : private:
403 : Private *const d;
404 :
405 : private: // disable...
406 : Context(const Context &);
407 : const Context &operator=(const Context &);
408 : };
409 :
410 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::CertificateInclusion incl);
411 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::EncryptionFlags flags);
412 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::AuditLogFlags flags);
413 :
414 : } // namespace GpgME
415 :
416 : #endif // __GPGMEPP_CONTEXT_H__
|
