cpp: Add get / set Sender API
[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     // wrapper for gpgme_set_sender
308     const char *getSender();
309     GpgME::Error setSender(const char *sender);
310
311     //
312     // Encryption
313     //
314
315     enum EncryptionFlags {
316         None = 0,
317         AlwaysTrust = 1,
318         NoEncryptTo = 2,
319         Prepare = 4,
320         ExpectSign = 8,
321         NoCompress = 16,
322         Symmetric = 32
323     };
324     EncryptionResult encrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
325     GpgME::Error encryptSymmetrically(const Data &plainText, Data &cipherText);
326     GpgME::Error startEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
327     EncryptionResult encryptionResult() const;
328
329     //
330     // Combined Signing and Encryption
331     //
332
333     std::pair<SigningResult, EncryptionResult> signAndEncrypt(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
334     GpgME::Error startCombinedSigningAndEncryption(const std::vector<Key> &recipients, const Data &plainText, Data &cipherText, EncryptionFlags flags);
335     // use encryptionResult() and signingResult() to retrieve the result objects...
336
337     //
338     //
339     // Audit Log
340     //
341     //
342     enum AuditLogFlags {
343         HtmlAuditLog = 1,
344         AuditLogWithHelp = 128
345     };
346     GpgME::Error startGetAuditLog(Data &output, unsigned int flags = 0);
347     GpgME::Error getAuditLog(Data &output, unsigned int flags = 0);
348
349     //
350     //
351     // G13 crypto container operations
352     //
353     //
354     GpgME::Error createVFS(const char *containerFile, const std::vector<Key> &recipients);
355     VfsMountResult mountVFS(const char *containerFile, const char *mountDir);
356
357     // Spawn Engine
358     enum SpawnFlags {
359         SpawnNone = 0,
360         SpawnDetached = 1,
361         SpawnAllowSetFg = 2
362     };
363     /** Spwan the process \a file with arguments \a argv.
364      *
365      *  If a data parameter is null the /dev/null will be
366      *  used. (Or other platform stuff).
367      *
368      * @param file The executable to start.
369      * @param argv list of arguments file should be argv[0].
370      * @param input The data to be sent through stdin.
371      * @param output The data to be receive the stdout.
372      * @param err The data to receive stderr.
373      * @param flags Additional flags.
374      *
375      * @returns An error or empty error.
376      */
377     GpgME::Error spawn(const char *file, const char *argv[],
378                        Data &input, Data &output, Data &err,
379                        SpawnFlags flags);
380     /** Async variant of spawn. Immediately returns after starting the
381      * process. */
382     GpgME::Error spawnAsync(const char *file, const char *argv[],
383                             Data &input, Data &output,
384                             Data &err, SpawnFlags flags);
385     //
386     //
387     // Run Control
388     //
389     //
390
391     bool poll();
392     GpgME::Error wait();
393     GpgME::Error lastError() const;
394     GpgME::Error cancelPendingOperation();
395
396     class Private;
397     const Private *impl() const
398     {
399         return d;
400     }
401     Private *impl()
402     {
403         return d;
404     }
405 private:
406     // Helper functions that need to be context because they rely
407     // on the "Friendlyness" of context to access the gpgme types.
408     gpgme_key_t *getKeysFromRecipients(const std::vector<Key> &recipients);
409
410 private:
411     Private *const d;
412
413 private: // disable...
414     Context(const Context &);
415     const Context &operator=(const Context &);
416 };
417
418 GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::CertificateInclusion incl);
419 GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::EncryptionFlags flags);
420 GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, Context::AuditLogFlags flags);
421
422 } // namespace GpgME
423
424 #endif // __GPGMEPP_CONTEXT_H__