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 : Error addUid(const Key &key, const char *userid);
218 : Error startAddUid(const Key &key, const char *userid);
219 :
220 : Error revUid(const Key &key, const char *userid);
221 : Error startRevUid(const Key &key, const char *userid);
222 :
223 : // using TofuInfo::Policy
224 : Error setTofuPolicy(const Key &k, unsigned int policy);
225 : Error setTofuPolicyStart(const Key &k, unsigned int policy);
226 :
227 : EditInteractor *lastEditInteractor() const;
228 : std::unique_ptr<EditInteractor> takeLastEditInteractor();
229 :
230 : //
231 : // SmartCard Editing
232 : //
233 :
234 : GpgME::Error cardEdit(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
235 : GpgME::Error startCardEditing(const Key &key, std::unique_ptr<EditInteractor> function, Data &out);
236 :
237 : EditInteractor *lastCardEditInteractor() const;
238 : std::unique_ptr<EditInteractor> takeLastCardEditInteractor();
239 :
240 : //
241 : // Trust Item Management
242 : //
243 :
244 : GpgME::Error startTrustItemListing(const char *pattern, int maxLevel);
245 : TrustItem nextTrustItem(GpgME::Error &e);
246 : GpgME::Error endTrustItemListing();
247 :
248 : //
249 : // Assuan Transactions
250 : //
251 :
252 : GpgME::Error assuanTransact(const char *command, std::unique_ptr<AssuanTransaction> transaction);
253 : GpgME::Error assuanTransact(const char *command);
254 : GpgME::Error startAssuanTransaction(const char *command, std::unique_ptr<AssuanTransaction> transaction);
255 : GpgME::Error startAssuanTransaction(const char *command);
256 :
257 : AssuanTransaction *lastAssuanTransaction() const;
258 : std::unique_ptr<AssuanTransaction> takeLastAssuanTransaction();
259 :
260 : //
261 : //
262 : // Crypto Operations
263 : //
264 : //
265 :
266 : //
267 : // Decryption
268 : //
269 :
270 : DecryptionResult decrypt(const Data &cipherText, Data &plainText);
271 : GpgME::Error startDecryption(const Data &cipherText, Data &plainText);
272 : DecryptionResult decryptionResult() const;
273 :
274 : //
275 : // Signature Verification
276 : //
277 :
278 : VerificationResult verifyDetachedSignature(const Data &signature, const Data &signedText);
279 : VerificationResult verifyOpaqueSignature(const Data &signedData, Data &plainText);
280 : GpgME::Error startDetachedSignatureVerification(const Data &signature, const Data &signedText);
281 : GpgME::Error startOpaqueSignatureVerification(const Data &signedData, Data &plainText);
282 : VerificationResult verificationResult() const;
283 :
284 : //
285 : // Combined Decryption and Signature Verification
286 : //
287 :
288 : std::pair<DecryptionResult, VerificationResult> decryptAndVerify(const Data &cipherText, Data &plainText);
289 : GpgME::Error startCombinedDecryptionAndVerification(const Data &cipherText, Data &plainText);
290 : // use verificationResult() and decryptionResult() to retrieve the result objects...
291 :
292 : //
293 : // Signing
294 : //
295 :
296 : void clearSigningKeys();
297 : GpgME::Error addSigningKey(const Key &signer);
298 : Key signingKey(unsigned int index) const;
299 : std::vector<Key> signingKeys() const;
300 :
301 : void clearSignatureNotations();
302 : GpgME::Error addSignatureNotation(const char *name, const char *value, unsigned int flags = 0);
303 : GpgME::Error addSignaturePolicyURL(const char *url, bool critical = false);
304 : const char *signaturePolicyURL() const;
305 : Notation signatureNotation(unsigned int index) const;
306 : std::vector<Notation> signatureNotations() const;
307 :
308 : //using GpgME::SignatureMode;
309 : SigningResult sign(const Data &plainText, Data &signature, SignatureMode mode);
310 : GpgME::Error startSigning(const Data &plainText, Data &signature, SignatureMode mode);
311 : SigningResult signingResult() const;
312 :
313 : // wrapper for gpgme_set_sender
314 : const char *getSender();
315 : GpgME::Error setSender(const char *sender);
316 :
317 : //
318 : // Encryption
319 : //
320 :
321 : enum EncryptionFlags {
322 : None = 0,
323 : AlwaysTrust = 1,
324 : NoEncryptTo = 2,
325 : Prepare = 4,
326 : ExpectSign = 8,
327 : NoCompress = 16,
328 : Symmetric = 32
329 : };
330 : EncryptionResult encrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
331 : GpgME::Error encryptSymmetrically(const Data &plainText, Data &cipherText);
332 : GpgME::Error startEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
333 : EncryptionResult encryptionResult() const;
334 :
335 : //
336 : // Combined Signing and Encryption
337 : //
338 :
339 : std::pair<SigningResult, EncryptionResult> signAndEncrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
340 : GpgME::Error startCombinedSigningAndEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
341 : // use encryptionResult() and signingResult() to retrieve the result objects...
342 :
343 : //
344 : //
345 : // Audit Log
346 : //
347 : //
348 : enum AuditLogFlags {
349 : HtmlAuditLog = 1,
350 : AuditLogWithHelp = 128
351 : };
352 : GpgME::Error startGetAuditLog(Data &output, unsigned int flags = 0);
353 : GpgME::Error getAuditLog(Data &output, unsigned int flags = 0);
354 :
355 : //
356 : //
357 : // G13 crypto container operations
358 : //
359 : //
360 : GpgME::Error createVFS(const char *containerFile, const std::vector<Key> &recipients);
361 : VfsMountResult mountVFS(const char *containerFile, const char *mountDir);
362 :
363 : // Spawn Engine
364 : enum SpawnFlags {
365 : SpawnNone = 0,
366 : SpawnDetached = 1,
367 : SpawnAllowSetFg = 2
368 : };
369 : /** Spwan the process \a file with arguments \a argv.
370 : *
371 : * If a data parameter is null the /dev/null will be
372 : * used. (Or other platform stuff).
373 : *
374 : * @param file The executable to start.
375 : * @param argv list of arguments file should be argv[0].
376 : * @param input The data to be sent through stdin.
377 : * @param output The data to be receive the stdout.
378 : * @param err The data to receive stderr.
379 : * @param flags Additional flags.
380 : *
381 : * @returns An error or empty error.
382 : */
383 : GpgME::Error spawn(const char *file, const char *argv[],
384 : Data &input, Data &output, Data &err,
385 : SpawnFlags flags);
386 : /** Async variant of spawn. Immediately returns after starting the
387 : * process. */
388 : GpgME::Error spawnAsync(const char *file, const char *argv[],
389 : Data &input, Data &output,
390 : Data &err, SpawnFlags flags);
391 : //
392 : //
393 : // Run Control
394 : //
395 : //
396 :
397 : bool poll();
398 : GpgME::Error wait();
399 : GpgME::Error lastError() const;
400 : GpgME::Error cancelPendingOperation();
401 :
402 : class Private;
403 : const Private *impl() const
404 : {
405 : return d;
406 : }
407 0 : Private *impl()
408 : {
409 0 : return d;
410 : }
411 : private:
412 : // Helper functions that need to be context because they rely
413 : // on the "Friendlyness" of context to access the gpgme types.
414 : gpgme_key_t *getKeysFromRecipients(const std::vector<Key> &recipients);
415 :
416 : private:
417 : Private *const d;
418 :
419 : private: // disable...
420 : Context(const Context &);
421 : const Context &operator=(const Context &);
422 : };
423 :
424 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::CertificateInclusion incl);
425 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::EncryptionFlags flags);
426 : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::AuditLogFlags flags);
427 :
428 : } // namespace GpgME
429 :
430 : #endif // __GPGMEPP_CONTEXT_H__
|
