Libkleo

keycache.h
1/* -*- mode: c++; c-basic-offset:4 -*-
2 models/keycache.h
3
4 This file is part of Kleopatra, the KDE keymanager
5 SPDX-FileCopyrightText: 2007 Klarälvdalens Datakonsult AB
6
7 SPDX-License-Identifier: GPL-2.0-or-later
8*/
9
10#pragma once
11
12#include "kleo_export.h"
13
14#include <QObject>
15
16#include <gpgme++/global.h>
17
18#include <memory>
19#include <string>
20#include <vector>
21
22namespace GpgME
23{
24class Key;
25class DecryptionResult;
26class VerificationResult;
27class KeyListResult;
28class Signature;
29class Subkey;
30}
31
32namespace Kleo
33{
34
35class FileSystemWatcher;
36class KeyGroup;
37class KeyGroupConfig;
38
39class KeyCacheAutoRefreshSuspension;
40
41struct CardKeyStorageInfo {
42 QString serialNumber;
43 QString displaySerialNumber;
44 QString keyRef;
45};
46
47class KLEO_EXPORT KeyCache : public QObject
48{
49 Q_OBJECT
50
51protected:
52 explicit KeyCache();
53
54public:
55 enum class KeyUsage {
56 AnyUsage,
57 Sign,
58 Encrypt,
59 Certify,
60 Authenticate,
61 };
62
63 enum ReloadOption {
64 Reload, //< if a reload is already in progress then ignore the reload request
65 ForceReload, //< if a reload is already in progress then cancel it and start another reload
66 };
67
68 static std::shared_ptr<const KeyCache> instance();
69 static std::shared_ptr<KeyCache> mutableInstance();
70
71 ~KeyCache() override;
72
73 void setGroupsEnabled(bool enabled);
74 void setGroupConfig(const std::shared_ptr<KeyGroupConfig> &groupConfig);
75
76 void insert(const GpgME::Key &key);
77 void insert(const std::vector<GpgME::Key> &keys);
78 bool insert(const KeyGroup &group);
79
80 void refresh(const std::vector<GpgME::Key> &keys);
81 bool update(const KeyGroup &group);
82
83 void remove(const GpgME::Key &key);
84 void remove(const std::vector<GpgME::Key> &keys);
85 bool remove(const KeyGroup &group);
86
87 void addFileSystemWatcher(const std::shared_ptr<FileSystemWatcher> &watcher);
88
89 void enableFileSystemWatcher(bool enable);
90
91 void setRefreshInterval(int hours);
92 int refreshInterval() const;
93
94 std::shared_ptr<KeyCacheAutoRefreshSuspension> suspendAutoRefresh();
95
96 void enableRemarks(bool enable);
97 bool remarksEnabled() const;
98
99 const std::vector<GpgME::Key> &keys() const;
100 std::vector<GpgME::Key> secretKeys() const;
101
102 KeyGroup group(const QString &id) const;
103 std::vector<KeyGroup> groups() const;
104 std::vector<KeyGroup> configurableGroups() const;
105 void saveConfigurableGroups(const std::vector<KeyGroup> &groups);
106
107 const GpgME::Key &findByFingerprint(const char *fpr) const;
108 const GpgME::Key &findByFingerprint(const std::string &fpr) const;
109
110 std::vector<GpgME::Key> findByFingerprint(const std::vector<std::string> &fprs) const;
111
112 std::vector<GpgME::Key> findByEMailAddress(const char *email) const;
113 std::vector<GpgME::Key> findByEMailAddress(const std::string &email) const;
114
115 /** Look through the cache and search for the best key for a mailbox.
116 *
117 * The best key is the key with a UID for the provided mailbox that
118 * has the highest validity and a subkey that is capable for the given
119 * usage.
120 * If more then one key have a UID with the same validity
121 * the most recently created key is taken.
122 *
123 * @returns the "best" key for the mailbox. */
124 GpgME::Key findBestByMailBox(const char *addr, GpgME::Protocol proto, KeyUsage usage) const;
125
126 /**
127 * Looks for a group named @a name which contains keys with protocol @a protocol
128 * that are suitable for the usage @a usage.
129 *
130 * If @a protocol is GpgME::OpenPGP or GpgME::CMS, then only groups consisting of keys
131 * matching this protocol are considered. Use @a protocol GpgME::UnknownProtocol to consider
132 * any groups regardless of the protocol including mixed-protocol groups.
133 *
134 * If @a usage is not KeyUsage::AnyUsage, then only groups consisting of keys supporting this usage
135 * are considered.
136 * The validity of keys and the presence of a private key (necessary for signing, certification, and
137 * authentication) is not taken into account.
138 *
139 * The first group that fulfills all conditions is returned.
140 *
141 * @returns a matching group or a null group if no matching group is found.
142 */
143 KeyGroup findGroup(const QString &name, GpgME::Protocol protocol, KeyUsage usage) const;
144
145 const GpgME::Key &findByKeyIDOrFingerprint(const char *id) const;
146 const GpgME::Key &findByKeyIDOrFingerprint(const std::string &id) const;
147
148 std::vector<GpgME::Key> findByKeyIDOrFingerprint(const std::vector<std::string> &ids) const;
149
150 const GpgME::Subkey &findSubkeyByKeyGrip(const char *grip, GpgME::Protocol protocol = GpgME::UnknownProtocol) const;
151 const GpgME::Subkey &findSubkeyByKeyGrip(const std::string &grip, GpgME::Protocol protocol = GpgME::UnknownProtocol) const;
152
153 std::vector<GpgME::Subkey> findSubkeysByKeyGrip(const char *grip, GpgME::Protocol protocol = GpgME::UnknownProtocol) const;
154 std::vector<GpgME::Subkey> findSubkeysByKeyGrip(const std::string &grip, GpgME::Protocol protocol = GpgME::UnknownProtocol) const;
155
156 std::vector<GpgME::Subkey> findSubkeysByKeyID(const std::vector<std::string> &ids) const;
157
158 const GpgME::Subkey &findSubkeyByFingerprint(const std::string &fpr) const;
159
160 std::vector<GpgME::Key> findRecipients(const GpgME::DecryptionResult &result) const;
161 GpgME::Key findSigner(const GpgME::Signature &signature) const;
162 std::vector<GpgME::Key> findSigners(const GpgME::VerificationResult &result) const;
163
164 std::vector<GpgME::Key> findSigningKeysByMailbox(const QString &mb) const;
165 std::vector<GpgME::Key> findEncryptionKeysByMailbox(const QString &mb) const;
166
167 /** Get a list of (serial number, key ref) for all cards this subkey is stored on. */
168 std::vector<CardKeyStorageInfo> cardsForSubkey(const GpgME::Subkey &subkey) const;
169
170 /** Check for group keys.
171 *
172 * @returns A list of keys configured for groupName. Empty if no group cached.*/
173 std::vector<GpgME::Key> getGroupKeys(const QString &groupName) const;
174
175 enum Option {
176 // clang-format off
177 NoOption = 0,
178 RecursiveSearch = 1,
179 IncludeSubject = 2,
180 // clang-format on
181 };
182 Q_DECLARE_FLAGS(Options, Option)
183
184 std::vector<GpgME::Key> findSubjects(const GpgME::Key &key, Options option = RecursiveSearch) const;
185 std::vector<GpgME::Key> findSubjects(const std::vector<GpgME::Key> &keys, Options options = RecursiveSearch) const;
186
187 std::vector<GpgME::Key> findIssuers(const GpgME::Key &key, Options options = RecursiveSearch) const;
188
189 /** Check if at least one keylisting was finished. */
190 bool initialized() const;
191
192 /** Check if all keys have OpenPGP Protocol. */
193 bool pgpOnly() const;
194
195 /** Set the keys the cache shall contain. Marks cache as initialized. Use for tests only. */
196 void setKeys(const std::vector<GpgME::Key> &keys);
197
198 void setGroups(const std::vector<KeyGroup> &groups);
199
200public Q_SLOTS:
201 void clear();
202 void startKeyListing(GpgME::Protocol proto = GpgME::UnknownProtocol)
203 {
204 reload(proto);
205 }
206 void reload(GpgME::Protocol proto = GpgME::UnknownProtocol, ReloadOption option = Reload);
207 void cancelKeyListing();
208
209Q_SIGNALS:
210 void keyListingDone(const GpgME::KeyListResult &result);
211 void keysMayHaveChanged();
212 void groupAdded(const Kleo::KeyGroup &group);
213 void groupUpdated(const Kleo::KeyGroup &group);
214 void groupRemoved(const Kleo::KeyGroup &group);
215
216private:
217 class RefreshKeysJob;
218
219 class Private;
221};
222
223Q_DECLARE_OPERATORS_FOR_FLAGS(KeyCache::Options)
224
225}
bool insert(Part *part, qint64 *insertId=nullptr)
void update(Part *part, const QByteArray &data, qint64 dataSize)
bool remove(const QString &column, const QVariant &value)
QAction * clear(const QObject *recvr, const char *slot, QObject *parent)
const QList< QKeySequence > & reload()
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 13 2024 11:51:41 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.