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__