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 
26 namespace GpgME
27 {
28 class Key;
29 }
30 
31 namespace 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  */
57 class KLEO_EXPORT KeyResolver : public QObject
58 {
59  Q_OBJECT
60 
61 public:
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 
180 Q_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 
193 private:
194  class Private;
195  std::unique_ptr<Private> d;
196 };
197 } // namespace Kleo
Q_SCRIPTABLE Q_NOREPLY void start()
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
typedef WindowFlags
Class to find Keys for E-Mail signing and encryption.
Definition: keyresolver.h:57
Solution represents the solution found by the KeyResolver.
Definition: keyresolver.h:65
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 03:56:14 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.