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