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

KDE's Doxygen guidelines are available online.