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
27namespace MessageComposer
28{
29class ContactPreference;
30}
31
32namespace Kleo
33{
34class ExpiryChecker;
35
36enum 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
114class MESSAGECOMPOSER_EXPORT KeyResolver
115{
116public:
117 KeyResolver(bool encToSelf, bool showApproval, bool oppEncryption, unsigned int format, const std::shared_ptr<Kleo::ExpiryChecker> &expiryChecker);
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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 /** Sets crypto preferences for given email address.
236 * This is an alternative to setting crypto preferences for a contact when Akonadi
237 * lookup is disabled - useful mostly for testing cases when it's not possible to
238 * index contacts on demand.
239 */
240 void setContactPreferences(const QString &address, const MessageComposer::ContactPreference &preference);
241
242private:
243 void dump() const;
244 std::vector<Item> getEncryptionItems(const QStringList &recipients);
245 std::vector<GpgME::Key> getEncryptionKeys(const QString &recipient, bool quiet) const;
246
247 Kleo::Result showKeyApprovalDialog(bool &finalySendUnencrypted);
248
249 bool encryptionPossible() const;
250 bool signingPossible() const;
251 Kleo::Result resolveEncryptionKeys(bool signingRequested, bool &finalySendUnencrypted);
252 Kleo::Result resolveSigningKeysForEncryption();
253 Kleo::Result resolveSigningKeysForSigningOnly();
254 void collapseAllSplitInfos();
255 void addToAllSplitInfos(const std::vector<GpgME::Key> &keys, unsigned int formats);
256 void addKeys(const std::vector<Item> &items, CryptoMessageFormat f);
257 void addKeys(const std::vector<Item> &items);
258 QStringList allRecipients() const;
259 std::vector<GpgME::Key> signingKeysFor(CryptoMessageFormat f) const;
260
261 std::vector<GpgME::Key> lookup(const QStringList &patterns, bool secret = false) const;
262
263 std::vector<GpgME::Key>
264 selectKeys(const QString &person, const QString &msg, const std::vector<GpgME::Key> &selectedKeys = std::vector<GpgME::Key>()) const;
265
266 QStringList keysForAddress(const QString &address) const;
267 void setKeysForAddress(const QString &address, const QStringList &pgpKeyFingerprints, const QStringList &smimeCertFingerprints) const;
268
269 bool encryptToSelf() const;
270 bool showApprovalDialog() const;
271
272 MessageComposer::ContactPreference lookupContactPreferences(const QString &address) const;
273 void saveContactPreference(const QString &email, const MessageComposer::ContactPreference &pref) const;
274
275private:
276 class EncryptionPreferenceCounter;
277 friend class ::Kleo::KeyResolver::EncryptionPreferenceCounter;
278 class SigningPreferenceCounter;
279 friend class ::Kleo::KeyResolver::SigningPreferenceCounter;
280
281 struct KeyResolverPrivate;
282 std::unique_ptr<KeyResolverPrivate> const d;
283
284 bool mEncryptToSelf;
285 const bool mShowApprovalDialog : 1;
286 const bool mOpportunisticEncyption : 1;
287 const unsigned int mCryptoMessageFormats;
288};
289} // namespace Kleo
A class to resolve signing/encryption keys w.r.t.
Simple interface that both EncryptJob and SignEncryptJob implement so the composer can extract some e...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:37:30 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.