Libkleo

keyresolver.h
1/* -*- c++ -*-
2 keyresolver.h
3
4 This file is part of libkleopatra, the KDE keymanagement library
5 SPDX-FileCopyrightText: 2018 Intevation GmbH
6 SPDX-FileCopyrightText: 2021 g10 Code GmbH
7 SPDX-FileContributor: Ingo Klöcker <dev@ingo-kloecker.de>
8
9 SPDX-License-Identifier: GPL-2.0-or-later
10*/
11
12#pragma once
13
14#include "kleo_export.h"
15
16#include <QMap>
17#include <QObject>
18#include <QString>
19#include <QStringList>
20
21#include <gpgme++/global.h>
22
23#include <memory>
24#include <vector>
25
26namespace GpgME
27{
28class Key;
29}
30
31namespace Kleo
32{
33/**
34 * Class to find Keys for E-Mail signing and encryption.
35 *
36 * The KeyResolver uses the Keycache to find keys for signing
37 * or encryption.
38 *
39 * Overrides can be provided for address book integration.
40 *
41 * If no override key(s) are provided for an address and no
42 * KeyGroup for this address is found, then the key
43 * with a uid that matches the address and has the highest
44 * validity is used. If both keys have the same validity,
45 * then the key with the newest subkey is used.
46 *
47 * The KeyResolver also supports groups so the number of
48 * encryption keys does not necessarily
49 * need to match the amount of sender addresses. For this reason
50 * maps are used to map addresses to lists of keys.
51 *
52 * The keys can be OpenPGP keys and S/MIME (CMS) keys.
53 * As a caller you need to partition the keys by their protocol and
54 * send one message for each protocol for the recipients and signed
55 * by the signing keys.
56 */
57class KLEO_EXPORT KeyResolver : public QObject
58{
59 Q_OBJECT
60
61public:
62 /**
63 * Solution represents the solution found by the KeyResolver.
64 */
65 struct Solution {
66 /**
67 * This property holds a hint at the protocol of the signing and encryption
68 * keys, i.e. if @p protocol is either @c GpgME::OpenPGP or @c GpgME::CMS,
69 * then all keys have the corresponding protocol. Otherwise, the keys have
70 * mixed protocols.
71 */
72 GpgME::Protocol protocol = GpgME::UnknownProtocol;
73
74 /**
75 * This property contains the signing keys to use. It contains zero or one
76 * OpenPGP key and zero or one S/MIME key.
77 */
78 std::vector<GpgME::Key> signingKeys;
79
80 /**
81 * This property contains the encryption keys to use for the different recipients.
82 *
83 * The list of keys will contain for regular users either one S/MIME key
84 * or one OpenPGP key. For a group address, the list of keys will instead contain
85 * the keys required to encrypt for every member of the group.
86 *
87 * The keys of the map represent the normalized email addresses of the recipients.
88 *
89 * @see Kleo::KeyGroup
90 */
92 };
93
94 /** Creates a new key resolver object.
95 *
96 * @param encrypt: Should encryption keys be selected.
97 * @param sign: Should signing keys be selected.
98 * @param protocol: A specific key protocol (OpenPGP, S/MIME) for selection. Default: Both protocols.
99 * @param allowMixed: Specify if multiple message formats may be resolved.
100 **/
101 explicit KeyResolver(bool encrypt, bool sign, GpgME::Protocol protocol = GpgME::UnknownProtocol, bool allowMixed = true);
102
103 ~KeyResolver() override;
104
105 /**
106 * Set the list of recipient addresses.
107 *
108 * @param addresses: A list of (not necessarily normalized) email addresses
109 */
110 void setRecipients(const QStringList &addresses);
111
112 /**
113 * Set the sender's address.
114 *
115 * This address is added to the list of recipients (for encryption to self)
116 * and it is used for signing key resolution, if the signing keys are not
117 * explicitly set through setSigningKeys.
118 *
119 * @param sender: The sender of this message.
120 */
121 void setSender(const QString &sender);
122
123 /**
124 * Set up possible override keys for recipients addresses.
125 * The keys for the fingerprints are looked
126 * up and used when found.
127 *
128 * Overrides for @c GpgME::UnknownProtocol are used regardless of the
129 * protocol. Overrides for a specific protocol are only used for this
130 * protocol. Overrides for @c GpgME::UnknownProtocol takes precedence over
131 * overrides for a specific protocol.
132 *
133 * @param overrides: A map of <protocol> -> (<address> <fingerprints>)
134 */
135 void setOverrideKeys(const QMap<GpgME::Protocol, QMap<QString, QStringList>> &overrides);
136
137 /**
138 * Set explicit signing keys to use.
139 */
140 void setSigningKeys(const QStringList &fingerprints);
141
142 /**
143 * Set the minimum user id validity for autoresolution.
144 *
145 * The default value is marginal
146 *
147 * @param validity int representation of a GpgME::UserID::Validity.
148 */
149 void setMinimumValidity(int validity);
150
151 /**
152 * Get the result of the resolution.
153 *
154 * @return the resolved keys for signing and encryption.
155 */
156 Solution result() const;
157
158 /**
159 * Starts the key resolving procedure. Emits keysResolved on success or
160 * error.
161 *
162 * @param showApproval: If set to true a dialog listing the keys
163 * will always be shown.
164 * @param parentWidget: Optional, a Widget to use as parent for dialogs.
165 */
166 void start(bool showApproval, QWidget *parentWidget = nullptr);
167
168 /**
169 * Set window flags for a possible dialog.
170 */
171 void setDialogWindowFlags(Qt::WindowFlags flags);
172
173 /**
174 * Set the protocol that is preferred to be displayed first when
175 * it is not clear from the keys. E.g. if both OpenPGP and S/MIME
176 * can be resolved.
177 */
178 void setPreferredProtocol(GpgME::Protocol proto);
179
180Q_SIGNALS:
181 /**
182 * Emitted when key resolution finished.
183 *
184 * @param success: The general result. If true continue sending,
185 * if false abort.
186 * @param sendUnencrypted: If there could be no key found for one of
187 * the recipients the user was queried if the
188 * mail should be sent out unencrypted.
189 * sendUnencrypted is true if the user agreed
190 * to this.*/
191 void keysResolved(bool success, bool sendUnencrypted);
192
193private:
194 class Private;
195 std::unique_ptr<Private> d;
196};
197} // namespace Kleo
Q_SCRIPTABLE Q_NOREPLY void start()
typedef WindowFlags
Solution represents the solution found by the KeyResolver.
Definition keyresolver.h:65
QMap< QString, std::vector< GpgME::Key > > encryptionKeys
This property contains the encryption keys to use for the different recipients.
Definition keyresolver.h:91
std::vector< GpgME::Key > signingKeys
This property contains the signing keys to use.
Definition keyresolver.h:78
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:51:59 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.