Messagelib

keyresolver.h
1 /* -*- c++ -*-
2  keyresolver.h
3 
4  This file is part of libkleopatra, the KDE keymanagement library
5  SPDX-FileCopyrightText: 2004 Klarälvdalens Datakonsult AB
6 
7  Based on kpgp.h
8  Copyright (C) 2001,2002 the KPGP authors
9  See file libkdenetwork/AUTHORS.kpgp for details
10 
11  SPDX-License-Identifier: GPL-2.0-or-later
12 */
13 
14 #pragma once
15 
16 #include "messagecomposer_export.h"
17 #include <Libkleo/Enum>
18 #include <Libkleo/KeyApprovalDialog>
19 
20 #include <gpgme++/key.h>
21 
22 #include <vector>
23 
24 #include <QSharedPointer>
25 #include <QStringList>
26 
27 namespace MessageComposer
28 {
29 class ContactPreference;
30 class NearExpiryChecker;
31 using NearExpiryCheckerPtr = QSharedPointer<NearExpiryChecker>;
32 }
33 
34 namespace Kleo
35 {
36 enum Result {
37  Failure = 0,
38  Ok = 1,
39  Canceled = 2,
40 };
41 /**
42  \short A class to resolve signing/encryption keys w.r.t. per-recipient preferences
43 
44  \section Step 1: Set the information needed
45 
46  The constructor takes some basic options as arguments, such as
47  whether or not encryption was actually requested. Recipient and
48  sender information is then set by using \c
49  setEncryptToSelfKeys(), \c setSigningKeys(), \c
50  setPrimaryRecipients() (To/Cc) and \c setSecondaryRecipients()
51  (Bcc).
52 
53  \section Step 2: Lookup and check per-recipient crypto preferences / Opportunistic Encryption
54 
55  First, \c checkSigningPreferences() goes through all recipient's
56  signing preferences, to determine whether or not to sign. It also
57  takes into account the available signing keys and whether or not
58  the user explicitly requested signing.
59 
60  \c checkEncryptionPreferences() does the same for encryption
61  preferences. If opportunistic encryption is enabled, recipients
62  without encryption preferences set are treated as if they had a
63  preference of \c AskWheneverPossible.
64 
65  In both cases an Action code is returned, with the following
66  meanings:
67 
68  <dl><dt>Conflict</dt><dd>A conflict was detected. E.g. one
69  recipient's preference was set to "always encrypt", while another
70  one's preference was set to "never encrypt". You should ask the
71  user what to do.</dd></dt>
72 
73  <dt>DoIt, DontDoIt</dt><dd>Do/Don't sign/encrypt</dd>
74 
75  <dt>Ask</dt><dd>(Some) crypto preferences request to prompt the
76  user, so do it.</dd>
77 
78  <dt>Impossible</dt><dd>Signing or encryption is impossible,
79  e.g. due to missing keys or unsupported formats.</dd> </dl>
80 
81  \section Step 3: Resolve all keys.
82 
83  In case signing or encryption was implicitly or explicitly
84  requested by the user, \c resolveAllKeys() tries to find signing
85  keys for each required format, as well as encryption keys for all
86  recipients (incl. the sender, if encrypt-to-self is set).
87 
88  \section Step 4: Get signing keys.
89 
90  If, after key resolving, signing is still requested and
91  apparently possible, you can get the result of all this by
92  iterating over the available message formats and retrieving the
93  set of signing keys to use with a call to \c signingKeys().
94 
95  \section Step 5: Get encryption key sets.
96 
97  If after key resolving, encryption is still requested and
98  apparently possible, you can get the result of all this by
99  calling \c encryptionItems() with the current message format at
100  hand as its argument.
101 
102  This will return a list of recipient-list/key-list pairs that
103  each describe a copy of the (possibly signed) message to be
104  encrypted independently.
105 
106  Note that it's only necessary to sign the message once for each
107  message format, although it might be necessary to create more
108  than one message when encrypting. This is because encryption
109  allows the recipients to learn about the other recipients the
110  message was encrypted to, so each secondary (BCC) recipient need
111  a copy of it's own to hide the other secondary recipients.
112  */
113 
114 class MESSAGECOMPOSER_EXPORT KeyResolver
115 {
116 public:
117  KeyResolver(bool encToSelf, bool showApproval, bool oppEncryption, unsigned int format, const MessageComposer::NearExpiryCheckerPtr &nearExpiryChecker);
118 
119  ~KeyResolver();
120 
121  struct Item : public KeyApprovalDialog::Item {
122  Item()
123  : KeyApprovalDialog::Item()
124  , signPref(UnknownSigningPreference)
125  , format(AutoFormat)
126  , needKeys(true)
127  {
128  }
129 
130  Item(const QString &a, EncryptionPreference e, SigningPreference s, CryptoMessageFormat f)
131  : KeyApprovalDialog::Item(a, std::vector<GpgME::Key>(), e)
132  , signPref(s)
133  , format(f)
134  , needKeys(true)
135  {
136  }
137 
138  Item(const QString &a, const std::vector<GpgME::Key> &k, EncryptionPreference e, SigningPreference s, CryptoMessageFormat f)
139  : KeyApprovalDialog::Item(a, k, e)
140  , signPref(s)
141  , format(f)
142  , needKeys(false)
143  {
144  }
145 
146  SigningPreference signPref;
147  CryptoMessageFormat format;
148  bool needKeys;
149  };
150 
151  /**
152  Set the fingerprints of keys to be used for encrypting to
153  self. Also looks them up and complains if they're not usable or
154  found.
155  */
156  Q_REQUIRED_RESULT Kleo::Result setEncryptToSelfKeys(const QStringList &fingerprints);
157  /**
158  Set the fingerprints of keys to be used for signing. Also
159  looks them up and complains if they're not usable or found.
160  */
161  Q_REQUIRED_RESULT Kleo::Result setSigningKeys(const QStringList &fingerprints);
162  /**
163  Set the list of primary (To/CC) recipient addresses. Also looks
164  up possible keys, but doesn't interact with the user.
165  */
166  void setPrimaryRecipients(const QStringList &addresses);
167  /**
168  Set the list of secondary (BCC) recipient addresses. Also looks
169  up possible keys, but doesn't interact with the user.
170  */
171  void setSecondaryRecipients(const QStringList &addresses);
172 
173  /**
174  Determine whether to sign or not, depending on the
175  per-recipient signing preferences, as well as the availability
176  of usable signing keys.
177  */
178  Q_REQUIRED_RESULT Action checkSigningPreferences(bool signingRequested) const;
179  /**
180  Determine whether to encrypt or not, depending on the
181  per-recipient encryption preferences, as well as the availability
182  of usable encryption keys.
183  */
184  Q_REQUIRED_RESULT Action checkEncryptionPreferences(bool encryptionRequested) const;
185 
186  /**
187  Queries the user for missing keys and displays a key approval
188  dialog if needed.
189  */
190  Q_REQUIRED_RESULT Kleo::Result resolveAllKeys(bool &signingRequested, bool &encryptionRequested);
191 
192  /**
193  @return the signing keys to use (if any) for the given message
194  format.
195  */
196  Q_REQUIRED_RESULT std::vector<GpgME::Key> signingKeys(CryptoMessageFormat f) const;
197 
198  struct SplitInfo {
199  SplitInfo() = default;
200 
201  explicit SplitInfo(const QStringList &r)
202  : recipients(r)
203  {
204  }
205 
206  SplitInfo(const QStringList &r, const std::vector<GpgME::Key> &k)
207  : recipients(r)
208  , keys(k)
209  {
210  }
211 
212  QStringList recipients;
213  std::vector<GpgME::Key> keys;
214  };
215  /** @return the found distinct sets of items for format \a f. The
216  returned vector will contain more than one item only if
217  secondary recipients have been specified.
218  */
219  Q_REQUIRED_RESULT std::vector<SplitInfo> encryptionItems(CryptoMessageFormat f) const;
220 
221  std::vector<GpgME::Key> encryptToSelfKeysFor(CryptoMessageFormat f) const;
222 
223  /** If Autocrypt keys are used to find valid PGP Keys
224  */
225  void setAutocryptEnabled(bool autocryptEnabled);
226 
227  std::map<QByteArray, QString> useAutocrypt() const;
228 
229  /** Disable ContactSearchJob in KeyResolver.
230  A usecase is that ests won't fireup an Akonadi instance only for this feature.
231  @default is true: The ContactSearchJob is executed.
232  */
233  void setAkonadiLookupEnabled(bool akonadiLookupEnabled);
234 
235 private:
236  void dump() const;
237  std::vector<Item> getEncryptionItems(const QStringList &recipients);
238  std::vector<GpgME::Key> getEncryptionKeys(const QString &recipient, bool quiet) const;
239 
240  Kleo::Result showKeyApprovalDialog(bool &finalySendUnencrypted);
241 
242  bool encryptionPossible() const;
243  bool signingPossible() const;
244  Kleo::Result resolveEncryptionKeys(bool signingRequested, bool &finalySendUnencrypted);
245  Kleo::Result resolveSigningKeysForEncryption();
246  Kleo::Result resolveSigningKeysForSigningOnly();
247  void collapseAllSplitInfos();
248  void addToAllSplitInfos(const std::vector<GpgME::Key> &keys, unsigned int formats);
249  void addKeys(const std::vector<Item> &items, CryptoMessageFormat f);
250  void addKeys(const std::vector<Item> &items);
251  QStringList allRecipients() const;
252  std::vector<GpgME::Key> signingKeysFor(CryptoMessageFormat f) const;
253 
254  std::vector<GpgME::Key> lookup(const QStringList &patterns, bool secret = false) const;
255 
256  std::vector<GpgME::Key>
257  selectKeys(const QString &person, const QString &msg, const std::vector<GpgME::Key> &selectedKeys = std::vector<GpgME::Key>()) const;
258 
259  QStringList keysForAddress(const QString &address) const;
260  void setKeysForAddress(const QString &address, const QStringList &pgpKeyFingerprints, const QStringList &smimeCertFingerprints) const;
261 
262  bool encryptToSelf() const;
263  bool showApprovalDialog() const;
264 
265  MessageComposer::ContactPreference lookupContactPreferences(const QString &address) const;
266  void saveContactPreference(const QString &email, const MessageComposer::ContactPreference &pref) const;
267 
268 private:
269  class EncryptionPreferenceCounter;
270  friend class ::Kleo::KeyResolver::EncryptionPreferenceCounter;
271  class SigningPreferenceCounter;
272  friend class ::Kleo::KeyResolver::SigningPreferenceCounter;
273 
274  struct KeyResolverPrivate;
275  std::unique_ptr<KeyResolverPrivate> const d;
276 
277  bool mEncryptToSelf;
278  const bool mShowApprovalDialog : 1;
279  const bool mOpportunisticEncyption : 1;
280  const unsigned int mCryptoMessageFormats;
281 };
282 } // namespace Kleo
Simple interface that both EncryptJob and SignEncryptJob implement so the composer can extract some e...
A class to resolve signing/encryption keys w.r.t.
Definition: keyresolver.h:114
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Dec 6 2022 04:05:09 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.