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__