libkpgp/kpgp.h

   1 /*
   2     kpgp.h
   3
   4     Copyright (C) 2001,2002 the KPGP authors
   5     See file AUTHORS.kpgp for details
   6
   7     This file is part of KPGP, the KDE PGP/GnuPG support library.
   8
   9     KPGP is free software; you can redistribute it and/or modify
  10     it under the terms of the GNU General Public License as published by
  11     the Free Software Foundation; either version 2 of the License, or
  12     (at your option) any later version.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this program; if not, write to the Free Software Foundation,
  16     Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  17  */
  18
  19 #ifndef KPGP_H
  20 #define KPGP_H
  21
  22 #include "libkpgp_export.h"
  23 #include "kpgpkey.h"
  24
  25 #include <QtCore/QByteArray>
  26 #include <QtCore/QString>
  27 #include <QtGui/QWidget>
  28 #include <QtGui/QComboBox>
  29 #include <QtGui/QLayout>
  30 #include <QtGui/QPushButton>
  31 #include <QtGui/QRadioButton>
  32 #include <QtGui/QCheckBox>
  33 #include <QtGui/QGridLayout>
  34
  35 #include <stdio.h>
  36
  37 class QCheckBox;
  38 class QGridLayout;
  39
  40 class KConfig;
  41
  42 namespace Kpgp {
  43
  44 /** This enumerated type is used by Kpgp::* to indicate which keys can be
  45     selected by the user. The following values are available:
  46     - Kpgp::PublicKeys: Public keys are shown in the selection dialog.
  47     - Kpgp::SecretKeys: Secret keys are shown in the selection dialog.
  48     - Kpgp::EncryptionKeys: Encryption keys can be selected.
  49     - Kpgp::SigningKeys: Signing keys can be selected.
  50     - Kpgp::ValidKeys: Only valid keys can be selected.
  51     - Kpgp::TrustedKeys: Only trusted keys can be selected.
  52     - Kpgp::AllKeys == PublicKeys | SecretKeys | EncryptionKeys | SigningKeys
  53 */
  54 enum { PublicKeys = 1,
  55        SecretKeys = 2,
  56        EncryptionKeys = 4,
  57        SigningKeys = 8,
  58        ValidKeys = 16,
  59        TrustedKeys = 32,
  60        AllKeys = PublicKeys | SecretKeys | EncryptionKeys | SigningKeys,
  61        PubSecKeys = PublicKeys | SecretKeys,
  62        EncrSignKeys = EncryptionKeys | SigningKeys
  63 };
  64
  65 enum Result
  66 {
  67        Failure = 0,
  68        Ok = 1,
  69        Canceled = 2
  70 };
  71
  72 class Base;
  73 class Block;
  74
  75 class KPGP_EXPORT Module
  76 {
  77   friend class Block;
  78
  79 private:
  80     // the class running pgp
  81     Base *pgp;
  82
  83   /**
  84    * Singleton pattern: use getKpgp()
  85    */
  86   Module();
  87
  88 public:
  89   virtual ~Module();
  90
  91   /** the following virtual function form the interface to the
  92       application using Kpgp
  93   */
  94   virtual void readConfig();
  95   virtual void writeConfig(bool sync);
  96   virtual void init();
  97
  98   /** decrypts the given OpenPGP block if the passphrase is good.
  99       returns false otherwise */
 100   bool decrypt( Block& block );
 101
 102   /** Tries to verify the given OpenPGP block */
 103   bool verify( Block& block );
 104
 105   /** clearsigns the given OpenPGP block with the key corresponding to the
 106       given key id. The charset is needed to display the text correctly.
 107       Returns
 108       Failure  if there was an unresolvable error
 109       Canceled if signing was canceled
 110       Ok       if everything is o.k.
 111   */
 112   Kpgp::Result clearsign( Block& block,
 113                   const KeyID& keyId, const QByteArray& charset = 0 );
 114
 115   /** encrypts the given OpenPGP block for a list of persons. if sign is true
 116       then the block is clearsigned with the key corresponding to the given
 117       key id. The charset is needed to display the text correctly.
 118       Returns
 119       Failure  if there was an unresolvable error
 120       Canceled if encryption was canceled
 121       Ok       if everything is o.k.
 122   */
 123   Kpgp::Result encrypt( Block& block,
 124                 const QStringList& receivers, const KeyID& keyId,
 125                 bool sign, const QByteArray& charset = 0 );
 126
 127   /** Determines the keys which should be used for encrypting the message
 128       to the given list of recipients.
 129       Returns:
 130       Failure  if there was an unresolvable error
 131       Canceled if encryption was canceled
 132       Ok       if everything is o.k.
 133   */
 134   Kpgp::Result getEncryptionKeys( KeyIDList& encryptionKeyIds,
 135                                   const QStringList& recipients,
 136                                   const KeyID& keyId );
 137
 138   /** checks if encrypting to the given list of persons is possible and
 139       desired, i.e. if we have a (trusted) key for every recipient and
 140       if encryption to all keys is allowed.
 141       Returns
 142        0 if encryption is not possible or not desired,
 143        1 if encryption is possible and desired,
 144        2 if encryption is possible, but the user wants to be asked and
 145       -1 if there is a conflict which can't be automatically resolved.
 146   */
 147   int encryptionPossible( const QStringList& recipients );
 148
 149 protected:
 150   int doEncSign( Block& block, const KeyIDList& recipientKeyIds, bool sign );
 151
 152 public:
 153   /** sign a key in the keyring with users signature. */
 154   bool signKey( const KeyID& keyID );
 155
 156   /** get the list of cached public keys. */
 157   const KeyList publicKeys();
 158
 159   /** get the list of cached secret keys. */
 160   const KeyList secretKeys();
 161
 162   /** Reads the list of public keys if necessary or if <em>reread</em> is true.
 163    */
 164   void readPublicKeys( bool reread = false );
 165
 166   /** Reads the list of secret keys if necessary or if <em>reread</em> is true.
 167    */
 168   void readSecretKeys( bool reread = false );
 169
 170   /** try to get an ascii armored key block for the given public key */
 171   QByteArray getAsciiPublicKey( const KeyID& keyID );
 172
 173   /** Returns the public key with the given key ID or null if no matching
 174       key is found.
 175   */
 176   Key* publicKey( const KeyID& keyID );
 177
 178   /** Returns the first public key with the given user ID or null if no
 179       matching key is found.
 180   */
 181   Key* publicKey( const QString& userID );
 182
 183   /** Returns the secret key with the given key ID or null if no matching
 184       key is found.
 185   */
 186   Key* secretKey( const KeyID& keyID );
 187
 188   /** Returns the trust value for the given key. This is the maximal trust
 189       value of any of the user ids of this key.
 190    */
 191   Validity keyTrust( const KeyID& keyID );
 192
 193   /** Returns the trust value of a key with the given user id. If more than
 194       one key have this user id then the first key with this user id will be
 195       chosen.
 196    */
 197   Validity keyTrust( const QString& userID );
 198
 199   /** Returns TRUE if the given key is at least trusted marginally. Otherwise
 200       FALSE is returned.
 201    */
 202   bool isTrusted( const KeyID& keyID );
 203
 204   /** Rereads the key data for the given key and returns the reread data. If
 205       <em>readTrust</em> is true then the trust of this key will be determined.
 206    */
 207   Key* rereadKey( const KeyID& keyID, const bool readTrust = true );
 208
 209   /** Request the change of the passphrase of the actual secret
 210       key. TBI */
 211   bool changePassPhrase();
 212
 213   /** set a user identity to use (if you have more than one...)
 214       by default, pgp uses the identity which was generated last. */
 215   void setUser(const KeyID& keyID);
 216   /** Returns the actual key ID of the currently set key. */
 217   const KeyID user() const;
 218
 219   /** always encrypt message to oneself? */
 220   void setEncryptToSelf(bool flag);
 221   bool encryptToSelf(void) const;
 222
 223   /** store passphrase in pgp object
 224       Problem: passphrase stays in memory.
 225       Advantage: you can call en-/decrypt without always passing the
 226       passphrase
 227   */
 228   void setStorePassPhrase(bool);
 229   bool storePassPhrase(void) const;
 230
 231   /** clears everything from memory */
 232   void clear(const bool erasePassPhrase = false);
 233
 234   /** returns the last error that occurred */
 235   const QString lastErrorMsg(void) const;
 236
 237   // what version of PGP/GPG should we use
 238   enum PGPType { tAuto, tGPG, tPGP2, tPGP5, tPGP6, tOff } pgpType;
 239
 240   // did we find a pgp executable?
 241   bool havePGP(void) const;
 242
 243   /** Should PGP/GnuPG be used? */
 244   bool usePGP(void) const { return (havePGP() && (pgpType != tOff)); }
 245
 246   // show the result of encryption/signing?
 247   void setShowCipherText(const bool flag);
 248   bool showCipherText(void) const;
 249
 250   // show the encryption keys for approval?
 251   void setShowKeyApprovalDlg(const bool flag);
 252   bool showKeyApprovalDlg(void) const;
 253
 254   /** Shows a key selection dialog with all secret keys and the given title
 255       and the (optional) text. If <em>keyId</em> is given, then the
 256       corresponding key is selected.
 257   */
 258   KeyID selectSecretKey( const QString& title,
 259                          const QString& text = QString(),
 260                          const KeyID& keyId = KeyID() );
 261
 262   /** Shows a key selection dialog with all public keys and the given title
 263       and the (optional) text. If <em>oldKeyId</em> is given, then the
 264       corresponding key is selected. If <em>address</em> is given, then the
 265       chosen key will be stored (if the user wants it to be stored).
 266       <em>mode</em> specifies which keys can be selected.
 267   */
 268   KeyID selectPublicKey( const QString& title,
 269                          const QString& text = QString(),
 270                          const KeyID& oldKeyId = KeyID(),
 271                          const QString& address = QString(),
 272                          const unsigned int allowedKeys = AllKeys );
 273
 274   /** Shows a key selection dialog with all public keys and the given title
 275       and the (optional) text. If <em>oldKeyId</em> is given, then the
 276       corresponding key is selected. If <em>address</em> is given, then the
 277       chosen key will be stored (if the user wants it to be stored).
 278       <em>mode</em> specifies which keys can be selected.
 279   */
 280   KeyIDList selectPublicKeys( const QString& title,
 281                               const QString& text = QString(),
 282                               const KeyIDList& oldKeyIds = KeyIDList(),
 283                               const QString& address = QString(),
 284                               const unsigned int allowedKeys = AllKeys );
 285
 286   // FIXME: key management
 287
 288   /** Reads the encryption preference for the given address
 289       from the config file.
 290    */
 291   EncryptPref encryptionPreference( const QString& address );
 292
 293   /** Writes the given encryption preference for the given address
 294       to the config file.
 295    */
 296   void setEncryptionPreference( const QString& address,
 297                                 const EncryptPref pref );
 298
 299   // -- static member functions --------------------------------------------
 300
 301   /** return the actual pgp object */
 302   static Kpgp::Module *getKpgp();
 303
 304   /** get the kpgp config object */
 305   static KConfig *getConfig();
 306
 307   /** Parses the given message and splits it into OpenPGP blocks and
 308       Non-OpenPGP blocks.
 309       Returns TRUE if the message contains at least one OpenPGP block and
 310       FALSE otherwise.
 311       The format is then:
 312       <pre>
 313       1st Non-OpenPGP block
 314       1st OpenPGP block
 315       2nd Non-OpenPGP block
 316       ...
 317       n-th OpenPGP block
 318       (n+1)-th Non-OpenPGP block
 319       </pre>
 320   */
 321   static bool prepareMessageForDecryption( const QByteArray& msg,
 322                                            QList<Block>& pgpBlocks,
 323                                            QList<QByteArray>& nonPgpBlocks );
 324
 325 private:
 326   /** check if we have a trusted encryption key for the given person */
 327   bool haveTrustedEncryptionKey( const QString& person );
 328
 329   /** get a list of encryption keys to be used for the given recipient */
 330   KeyIDList getEncryptionKeys( const QString& person );
 331
 332   /** Set pass phrase */
 333   bool setPassPhrase(const QString &pass);
 334
 335   /** test if the PGP executable is found and if there is a passphrase
 336       set or given. Returns:
 337        1 if everything is ok
 338        0 (together with some warning message) if something is missing
 339       -1 if the passphrase dialog was canceled
 340   */
 341   int prepare(bool needPassPhrase=false, Block* block = 0 );
 342
 343   /** cleanup passphrase if it should not be stored. */
 344   void cleanupPass() { if (!storePass) wipePassPhrase(); }
 345
 346   /** Wipes and optionally frees the memory used to hold the
 347       passphrase. */
 348   void wipePassPhrase(bool free=false);
 349
 350   // transform an address into canonical form
 351   QString canonicalAddress( const QString& person );
 352
 353   /** Shows a dialog to let the user select a key from the given list of keys
 354    */
 355   KeyID selectKey( const KeyList& keys,
 356                    const QString& title,
 357                    const QString& text = QString(),
 358                    const KeyID& keyId = KeyID(),
 359                    const unsigned int allowedKeys = AllKeys );
 360
 361   /** Shows a dialog to let the user select a key from the given list of keys
 362    */
 363   KeyIDList selectKeys( const KeyList& keys,
 364                         const QString& title,
 365                         const QString& text = QString(),
 366                         const KeyIDList& keyIds = KeyIDList(),
 367                         const unsigned int allowedKeys = AllKeys );
 368
 369   /** Shows a dialog to let the user select a key from the given list of keys.
 370       The dialog includes a checkbox ("Remember decision"). The state of the
 371       checkbox is returned in rememberChoice.
 372    */
 373   KeyID selectKey( bool& rememberChoice,
 374                    const KeyList& keys,
 375                    const QString& title,
 376                    const QString& text = QString(),
 377                    const KeyID& keyId = KeyID(),
 378                    const unsigned int allowedKeys = AllKeys );
 379
 380   /** Shows a dialog to let the user select a list of keys from the given
 381       list of keys. The dialog includes a checkbox ("Remember decision").
 382       The state of the checkbox is returned in rememberChoice.
 383    */
 384   KeyIDList selectKeys( bool& rememberChoice,
 385                         const KeyList& keys,
 386                         const QString& title,
 387                         const QString& text = QString(),
 388                         const KeyIDList& keyIds = KeyIDList(),
 389                         const unsigned int allowedKeys = AllKeys );
 390
 391   /** Returns the OpenPGP keys which should be used for encryption to the
 392       given address.
 393   */
 394   KeyIDList keysForAddress( const QString& address );
 395
 396   /** Set an email address -> list of OpenPGP keys association.
 397   */
 398   void setKeysForAddress( const QString& address, const KeyIDList& keyIDs );
 399
 400   /** Remove an email address -> OpenPGP key association. */
 401   void removeKeyForAddress( const QString& address );
 402
 403   /** Reads the email address -> OpenPGP key associations from the config
 404       file.
 405   */
 406   void readAddressData();
 407
 408   /** Writes the email address -> OpenPGP key associations to the config
 409       file.
 410   */
 411   void writeAddressData();
 412
 413   bool checkForPGP(void);
 414   void assignPGPBase(void);
 415
 416   KConfig *config;
 417
 418   struct AddressData {
 419     KeyIDList keyIds;
 420     EncryptPref encrPref;
 421   };
 422   typedef QMap<QString, AddressData> AddressDataDict;
 423   AddressDataDict addressDataDict;
 424
 425   KeyList mPublicKeys;
 426   bool mPublicKeysCached : 1; // did we already read the public keys?
 427   KeyList mSecretKeys;
 428   bool mSecretKeysCached : 1; // did we already read the secret keys?
 429
 430   bool storePass : 1;
 431   char * passphrase;
 432   size_t passphrase_buffer_len;
 433
 434   QString errMsg;
 435
 436   KeyID pgpUser; // the key ID which is used to sign/encrypt to self
 437   bool flagEncryptToSelf : 1;
 438
 439   bool havePgp : 1;
 440   bool havePGP5 : 1;
 441   bool haveGpg : 1;
 442   bool havePassPhrase : 1;
 443   bool showEncryptionResult : 1;
 444   bool mShowKeyApprovalDlg : 1;
 445 }; // class Module
 446
 447 // -- inlined member functions ---------------------------------------------
 448
 449 inline void
 450 Module::setShowKeyApprovalDlg( const bool flag )
 451 {
 452   mShowKeyApprovalDlg = flag;
 453 }
 454
 455 inline bool
 456 Module::showKeyApprovalDlg( void ) const
 457 {
 458   return mShowKeyApprovalDlg;
 459 }
 460
 461 // -------------------------------------------------------------------------
 462
 463 } // namespace Kpgp
 464
 465 #endif
 466