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 : /** Same as above but returning a unique ptr. */
72 : static std::unique_ptr<Context> create(Protocol proto);
73 : static std::unique_ptr<Context> createForEngine(Engine engine, Error *err = 0);
74 : virtual ~Context();
75 :
76 : //
77 : // Context Attributes
78 : //
79 :
80 : Protocol protocol() const;
81 :
82 : void setArmor(bool useArmor);
83 : bool armor() const;
84 :
85 : void setTextMode(bool useTextMode);
86 : bool textMode() const;
87 :
88 : void setOffline(bool useOfflineMode);
89 : bool offline() const;
90 :
91 : const char *getFlag(const char *name) const;
92 : Error setFlag(const char *name, const char *value);
93 :
94 : enum CertificateInclusion {
95 : DefaultCertificates = -256,
96 : AllCertificatesExceptRoot = -2,
97 : AllCertificates = -1,
98 : NoCertificates = 0,
99 : OnlySenderCertificate = 1
100 : };
101 : void setIncludeCertificates(int which);
102 : int includeCertificates() const;
103 :
104 : //using GpgME::KeyListMode;
105 : void setKeyListMode(unsigned int keyListMode);
106 : void addKeyListMode(unsigned int keyListMode);
107 : unsigned int keyListMode() const;
108 :
109 : /** Set the passphrase provider
110 : *
111 : * To avoid problems where a class using a context registers
112 : * itself as the provider the Context does not take ownership
113 : * of the provider and the caller must ensure that the provider
114 : * is deleted if it is no longer needed.
115 : */
116 : void setPassphraseProvider(PassphraseProvider *provider);
117 : PassphraseProvider *passphraseProvider() const;
118 :
119 : /** Set the progress provider
120 : *
121 : * To avoid problems where a class using a context registers
122 : * itself as the provider the Context does not take ownership
123 : * of the provider and the caller must ensure that the provider
124 : * is deleted if it is no longer needed.
125 : */
126 : void setProgressProvider(ProgressProvider *provider);
127 : ProgressProvider *progressProvider() const;
128 :
129 : void setManagedByEventLoopInteractor(bool managed);
130 : bool managedByEventLoopInteractor() const;
131 :
132 : GpgME::Error setLocale(int category, const char *value);
133 :
134 : EngineInfo engineInfo() const;
135 : GpgME::Error setEngineFileName(const char *filename);
136 : GpgME::Error setEngineHomeDirectory(const char *filename);
137 :
138 : enum PinentryMode{
139 : PinentryDefault = 0,
140 : PinentryAsk = 1,
141 : PinentryCancel = 2,
142 : PinentryError = 3,
143 : PinentryLoopback = 4
144 : };
145 : GpgME::Error setPinentryMode(PinentryMode which);
146 : PinentryMode pinentryMode() const;
147 :
148 : private:
149 : friend class ::GpgME::EventLoopInteractor;
150 : void installIOCallbacks(gpgme_io_cbs *iocbs);
151 : void uninstallIOCallbacks();
152 :
153 : public:
154 : //
155 : //
156 : // Key Management
157 : //
158 : //
159 :
160 : //
161 : // Key Listing
162 : //
163 :
164 : GpgME::Error startKeyListing(const char *pattern = 0, bool secretOnly = false);
165 : GpgME::Error startKeyListing(const char *patterns[], bool secretOnly = false);
166 :
167 : Key nextKey(GpgME::Error &e);
168 :
169 : KeyListResult endKeyListing();
170 : KeyListResult keyListResult() const;
171 :
172 : Key key(const char *fingerprint, GpgME::Error &e, bool secret = false);
173 :
174 : //
175 : // Key Generation
176 : //
177 :
178 : KeyGenerationResult generateKey(const char *parameters, Data &pubKey);
179 : GpgME::Error startKeyGeneration(const char *parameters, Data &pubkey);
180 : KeyGenerationResult keyGenerationResult() const;
181 :
182 : //
183 : // Key Export
184 : //
185 :
186 : GpgME::Error exportPublicKeys(const char *pattern, Data &keyData);
187 : GpgME::Error exportPublicKeys(const char *pattern[], Data &keyData);
188 : GpgME::Error startPublicKeyExport(const char *pattern, Data &keyData);
189 : GpgME::Error startPublicKeyExport(const char *pattern[], Data &keyData);
190 :
191 : //
192 : // Key Import
193 : //
194 :
195 : ImportResult importKeys(const Data &data);
196 : ImportResult importKeys(const std::vector<Key> &keys);
197 : GpgME::Error startKeyImport(const Data &data);
198 : GpgME::Error startKeyImport(const std::vector<Key> &keys);
199 : ImportResult importResult() const;
200 :
201 : //
202 : // Key Deletion
203 : //
204 :
205 : GpgME::Error deleteKey(const Key &key, bool allowSecretKeyDeletion = false);
206 : GpgME::Error startKeyDeletion(const Key &key, bool allowSecretKeyDeletion = false);
207 :
208 : //
209 : // Passphrase changing
210 : //
211 :
212 : GpgME::Error passwd(const Key &key);
213 : GpgME::Error startPasswd(const Key &key);
214 :
215 : //
216 : // Key Editing
217 : //
218 :
219 : GpgME::Error edit(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
220 : GpgME::Error startEditing(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
221 :
222 :
223 : //
224 : // Modern Interface actions. Require 2.1.x
225 : //
226 : Error startCreateKey (const char *userid,
227 : const char *algo,
228 : unsigned long reserved,
229 : unsigned long expires,
230 : const Key &certkey,
231 : unsigned int flags);
232 : Error createKey (const char *userid,
233 : const char *algo,
234 : unsigned long reserved,
235 : unsigned long expires,
236 : const Key &certkey,
237 : unsigned int flags);
238 :
239 : // Same as create key but returning a result
240 : GpgME::KeyGenerationResult createKeyEx (const char *userid,
241 : const char *algo,
242 : unsigned long reserved,
243 : unsigned long expires,
244 : const Key &certkey,
245 : unsigned int flags);
246 :
247 : Error addUid(const Key &key, const char *userid);
248 : Error startAddUid(const Key &key, const char *userid);
249 :
250 : Error revUid(const Key &key, const char *userid);
251 : Error startRevUid(const Key &key, const char *userid);
252 :
253 : Error createSubkey(const Key &key, const char *algo,
254 : unsigned long reserved = 0,
255 : unsigned long expires = 0,
256 : unsigned int flags = 0);
257 : Error startCreateSubkey(const Key &key, const char *algo,
258 : unsigned long reserved = 0,
259 : unsigned long expires = 0,
260 : unsigned int flags = 0);
261 :
262 : // using TofuInfo::Policy
263 : Error setTofuPolicy(const Key &k, unsigned int policy);
264 : Error setTofuPolicyStart(const Key &k, unsigned int policy);
265 :
266 : EditInteractor *lastEditInteractor() const;
267 : std::unique_ptr<EditInteractor> takeLastEditInteractor();
268 :
269 : //
270 : // SmartCard Editing
271 : //
272 :
273 : GpgME::Error cardEdit(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
274 : GpgME::Error startCardEditing(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
275 :
276 : EditInteractor *lastCardEditInteractor() const;
277 : std::unique_ptr<EditInteractor> takeLastCardEditInteractor();
278 :
279 : //
280 : // Trust Item Management
281 : //
282 :
283 : GpgME::Error startTrustItemListing(const char *pattern, int maxLevel);
284 : TrustItem nextTrustItem(GpgME::Error &e);
285 : GpgME::Error endTrustItemListing();
286 :
287 : //
288 : // Assuan Transactions
289 : //
290 :
291 : GpgME::Error assuanTransact(const char *command, std::unique_ptr<AssuanTransaction> transaction);
292 : GpgME::Error assuanTransact(const char *command);
293 : GpgME::Error startAssuanTransaction(const char *command, std::unique_ptr<AssuanTransaction> transaction);
294 : GpgME::Error startAssuanTransaction(const char *command);
295 :
296 : AssuanTransaction *lastAssuanTransaction() const;
297 : std::unique_ptr<AssuanTransaction> takeLastAssuanTransaction();
298 :
299 : //
300 : //
301 : // Crypto Operations
302 : //
303 :
304 : enum DecryptionFlags {
305 : // Keep in line with core's flags
306 : DecryptNone = 0,
307 : DecryptVerify = 1,
308 : DecryptUnwrap = 128,
309 : DecryptMaxValue = 0x80000000
310 : };
311 :
312 : //
313 : // Decryption
314 : //
315 :
316 : // Alternative way to set decryption flags as they were added only in
317 : // 1.9.0 and so other API can still be used but with 1.9.0 additionally
318 : // flags can be set.
319 : void setDecryptionFlags (const DecryptionFlags flags);
320 :
321 : DecryptionResult decrypt(const Data &cipherText, Data &plainText);
322 : GpgME::Error startDecryption(const Data &cipherText, Data &plainText);
323 : DecryptionResult decrypt(const Data &cipherText, Data &plainText, const DecryptionFlags flags);
324 : GpgME::Error startDecryption(const Data &cipherText, Data &plainText, const DecryptionFlags flags);
325 : DecryptionResult decryptionResult() const;
326 :
327 : //
328 : // Signature Verification
329 : //
330 :
331 : VerificationResult verifyDetachedSignature(const Data &signature, const Data &signedText);
332 : VerificationResult verifyOpaqueSignature(const Data &signedData, Data &plainText);
333 : GpgME::Error startDetachedSignatureVerification(const Data &signature, const Data &signedText);
334 : GpgME::Error startOpaqueSignatureVerification(const Data &signedData, Data &plainText);
335 : VerificationResult verificationResult() const;
336 :
337 : //
338 : // Combined Decryption and Signature Verification
339 : //
340 :
341 : std::pair<DecryptionResult, VerificationResult> decryptAndVerify(const Data &cipherText, Data &plainText);
342 : std::pair<DecryptionResult, VerificationResult> decryptAndVerify(const Data &cipherText, Data &plainText, const DecryptionFlags flags);
343 : GpgME::Error startCombinedDecryptionAndVerification(const Data &cipherText, Data &plainText);
344 : GpgME::Error startCombinedDecryptionAndVerification(const Data &cipherText, Data &plainText, const DecryptionFlags flags);
345 : // use verificationResult() and decryptionResult() to retrieve the result objects...
346 :
347 : //
348 : // Signing
349 : //
350 :
351 : void clearSigningKeys();
352 : GpgME::Error addSigningKey(const Key &signer);
353 : Key signingKey(unsigned int index) const;
354 : std::vector<Key> signingKeys() const;
355 :
356 : void clearSignatureNotations();
357 : GpgME::Error addSignatureNotation(const char *name, const char *value, unsigned int flags = 0);
358 : GpgME::Error addSignaturePolicyURL(const char *url, bool critical = false);
359 : const char *signaturePolicyURL() const;
360 : Notation signatureNotation(unsigned int index) const;
361 : std::vector<Notation> signatureNotations() const;
362 :
363 : //using GpgME::SignatureMode;
364 : SigningResult sign(const Data &plainText, Data &signature, SignatureMode mode);
365 : GpgME::Error startSigning(const Data &plainText, Data &signature, SignatureMode mode);
366 : SigningResult signingResult() const;
367 :
368 : // wrapper for gpgme_set_sender
369 : const char *getSender();
370 : GpgME::Error setSender(const char *sender);
371 :
372 : //
373 : // Encryption
374 : //
375 :
376 : enum EncryptionFlags {
377 : None = 0,
378 : AlwaysTrust = 1,
379 : NoEncryptTo = 2,
380 : Prepare = 4,
381 : ExpectSign = 8,
382 : NoCompress = 16,
383 : Symmetric = 32,
384 : ThrowKeyIds = 64,
385 : EncryptWrap = 128
386 : };
387 : EncryptionResult encrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
388 : GpgME::Error encryptSymmetrically(const Data &plainText, Data &cipherText);
389 : GpgME::Error startEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
390 : EncryptionResult encryptionResult() const;
391 :
392 : //
393 : // Combined Signing and Encryption
394 : //
395 :
396 : std::pair<SigningResult, EncryptionResult> signAndEncrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
397 : GpgME::Error startCombinedSigningAndEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
398 : // use encryptionResult() and signingResult() to retrieve the result objects...
399 :
400 : //
401 : //
402 : // Audit Log
403 : //
404 : //
405 : enum AuditLogFlags {
406 : DefaultAuditLog = 0,
407 : HtmlAuditLog = 1,
408 : DiagnosticAuditLog = 2,
409 : AuditLogWithHelp = 128
410 : };
411 : GpgME::Error startGetAuditLog(Data &output, unsigned int flags = 0);
412 : GpgME::Error getAuditLog(Data &output, unsigned int flags = 0);
413 :
414 : //
415 : //
416 : // G13 crypto container operations
417 : //
418 : //
419 : GpgME::Error createVFS(const char *containerFile, const std::vector<Key> &recipients);
420 : VfsMountResult mountVFS(const char *containerFile, const char *mountDir);
421 :
422 : // Spawn Engine
423 : enum SpawnFlags {
424 : SpawnNone = 0,
425 : SpawnDetached = 1,
426 : SpawnAllowSetFg = 2,
427 : SpawnShowWindow = 4
428 : };
429 : /** Spwan the process \a file with arguments \a argv.
430 : *
431 : * If a data parameter is null the /dev/null will be
432 : * used. (Or other platform stuff).
433 : *
434 : * @param file The executable to start.
435 : * @param argv list of arguments file should be argv[0].
436 : * @param input The data to be sent through stdin.
437 : * @param output The data to be receive the stdout.
438 : * @param err The data to receive stderr.
439 : * @param flags Additional flags.
440 : *
441 : * @returns An error or empty error.
442 : */
443 : GpgME::Error spawn(const char *file, const char *argv[],
444 : Data &input, Data &output, Data &err,
445 : SpawnFlags flags);
446 : /** Async variant of spawn. Immediately returns after starting the
447 : * process. */
448 : GpgME::Error spawnAsync(const char *file, const char *argv[],
449 : Data &input, Data &output,
450 : Data &err, SpawnFlags flags);
451 : //
452 : //
453 : // Run Control
454 : //
455 : //
456 :
457 : bool poll();
458 : GpgME::Error wait();
459 : GpgME::Error lastError() const;
460 : GpgME::Error cancelPendingOperation();
461 :
462 : class Private;
463 : const Private *impl() const
464 : {
465 : return d;
466 : }
467 8 : Private *impl()
468 : {
469 8 : return d;
470 : }
471 :
472 : private:
473 : // Helper functions that need to be context because they rely
474 : // on the "Friendlyness" of context to access the gpgme types.
475 : gpgme_key_t *getKeysFromRecipients(const std::vector<Key> &recipients);
476 :
477 : private:
478 : Private *const d;
479 :
480 : private: // disable...
481 : Context(const Context &);
482 : const Context &operator=(const Context &);
483 : };
484 :
485 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::CertificateInclusion incl);
486 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::EncryptionFlags flags);
487 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::AuditLogFlags flags);
488 :
489 : } // namespace GpgME
490 :
491 : #endif // __GPGMEPP_CONTEXT_H__
|
