bec4e39a80fd93f6a6f2feedab9388cea93550e2
[gpgme.git] / lang / cpp / src / context.h
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     enum DecryptionFlags {
266         // Keep in line with core's flags
267         DecryptNone = 0,
268         DecryptVerify = 1,
269         DecryptUnwrap = 128,
270         DecryptMaxValue = 0x80000000
271     };
272
273     //
274     // Decryption
275     //
276
277     // Alternative way to set decryption flags as they were added only in
278     // 1.9.0 and so other API can still be used but with 1.9.0 additionally
279     // flags can be set.
280     void setDecryptionFlags (const DecryptionFlags flags);
281
282     DecryptionResult decrypt(const Data &cipherText, Data &plainText);
283     GpgME::Error startDecryption(const Data &cipherText, Data &plainText);
284     DecryptionResult decrypt(const Data &cipherText, Data &plainText, const DecryptionFlags flags);
285     GpgME::Error startDecryption(const Data &cipherText, Data &plainText, const DecryptionFlags flags);
286     DecryptionResult decryptionResult() const;
287
288     //
289     // Signature Verification
290     //
291
292     VerificationResult verifyDetachedSignature(const Data &signature, const Data &signedText);
293     VerificationResult verifyOpaqueSignature(const Data &signedData, Data &plainText);
294     GpgME::Error startDetachedSignatureVerification(const Data &signature, const Data &signedText);
295     GpgME::Error startOpaqueSignatureVerification(const Data &signedData, Data &plainText);
296     VerificationResult verificationResult() const;
297
298     //
299     // Combined Decryption and Signature Verification
300     //
301
302     std::pair<DecryptionResult, VerificationResult> decryptAndVerify(const Data &cipherText, Data &plainText);
303     std::pair<DecryptionResult, VerificationResult> decryptAndVerify(const Data &cipherText, Data &plainText, const DecryptionFlags flags);
304     GpgME::Error startCombinedDecryptionAndVerification(const Data &cipherText, Data &plainText);
305     GpgME::Error startCombinedDecryptionAndVerification(const Data &cipherText, Data &plainText, const DecryptionFlags flags);
306     // use verificationResult() and decryptionResult() to retrieve the result objects...
307
308     //
309     // Signing
310     //
311
312     void clearSigningKeys();
313     GpgME::Error addSigningKey(const Key &signer);
314     Key signingKey(unsigned int index) const;
315     std::vector<Key> signingKeys() const;
316
317     void clearSignatureNotations();
318     GpgME::Error addSignatureNotation(const char *name, const char *value, unsigned int flags = 0);
319     GpgME::Error addSignaturePolicyURL(const char *url, bool critical = false);
320     const char *signaturePolicyURL() const;
321     Notation signatureNotation(unsigned int index) const;
322     std::vector<Notation> signatureNotations() const;
323
324     //using GpgME::SignatureMode;
325     SigningResult sign(const Data &plainText, Data &signature, SignatureMode mode);
326     GpgME::Error startSigning(const Data &plainText, Data &signature, SignatureMode mode);
327     SigningResult signingResult() const;
328
329     // wrapper for gpgme_set_sender
330     const char *getSender();
331     GpgME::Error setSender(const char *sender);
332
333     //
334     // Encryption
335     //
336
337     enum EncryptionFlags {
338         None = 0,
339         AlwaysTrust = 1,
340         NoEncryptTo = 2,
341         Prepare = 4,
342         ExpectSign = 8,
343         NoCompress = 16,
344         Symmetric = 32,
345         ThrowKeyIds = 64,
346         EncryptWrap = 128
347     };
348     EncryptionResult encrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
349     GpgME::Error encryptSymmetrically(const Data &plainText, Data &cipherText);
350     GpgME::Error startEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
351     EncryptionResult encryptionResult() const;
352
353     //
354     // Combined Signing and Encryption
355     //
356
357     std::pair<SigningResult, EncryptionResult> signAndEncrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
358     GpgME::Error startCombinedSigningAndEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
359     // use encryptionResult() and signingResult() to retrieve the result objects...
360
361     //
362     //
363     // Audit Log
364     //
365     //
366     enum AuditLogFlags {
367         HtmlAuditLog = 1,
368         AuditLogWithHelp = 128
369     };
370     GpgME::Error startGetAuditLog(Data &output, unsigned int flags = 0);
371     GpgME::Error getAuditLog(Data &output, unsigned int flags = 0);
372
373     //
374     //
375     // G13 crypto container operations
376     //
377     //
378     GpgME::Error createVFS(const char *containerFile, const std::vector<Key> &recipients);
379     VfsMountResult mountVFS(const char *containerFile, const char *mountDir);
380
381     // Spawn Engine
382     enum SpawnFlags {
383         SpawnNone = 0,
384         SpawnDetached = 1,
385         SpawnAllowSetFg = 2
386     };
387     /** Spwan the process \a file with arguments \a argv.
388      *
389      *  If a data parameter is null the /dev/null will be
390      *  used. (Or other platform stuff).
391      *
392      * @param file The executable to start.
393      * @param argv list of arguments file should be argv[0].
394      * @param input The data to be sent through stdin.
395      * @param output The data to be receive the stdout.
396      * @param err The data to receive stderr.
397      * @param flags Additional flags.
398      *
399      * @returns An error or empty error.
400      */
401     GpgME::Error spawn(const char *file, const char *argv[],
402                        Data &input, Data &output, Data &err,
403                        SpawnFlags flags);
404     /** Async variant of spawn. Immediately returns after starting the
405      * process. */
406     GpgME::Error spawnAsync(const char *file, const char *argv[],
407                             Data &input, Data &output,
408                             Data &err, SpawnFlags flags);
409     //
410     //
411     // Run Control
412     //
413     //
414
415     bool poll();
416     GpgME::Error wait();
417     GpgME::Error lastError() const;
418     GpgME::Error cancelPendingOperation();
419
420     class Private;
421     const Private *impl() const
422     {
423         return d;
424     }
425     Private *impl()
426     {
427         return d;
428     }
429 private:
430     // Helper functions that need to be context because they rely
431     // on the "Friendlyness" of context to access the gpgme types.
432     gpgme_key_t *getKeysFromRecipients(const std::vector<Key> &recipients);
433
434 private:
435     Private *const d;
436
437 private: // disable...
438     Context(const Context &);
439     const Context &operator=(const Context &);
440 };
441
442 GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::CertificateInclusion incl);
443 GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::EncryptionFlags flags);
444 GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::AuditLogFlags flags);
445
446 } // namespace GpgME
447
448 #endif // __GPGMEPP_CONTEXT_H__