1 | /* |
2 | SPDX-FileCopyrightText: 2011 Ilia Kats <ilia-kats@gmx.net> |
3 | SPDX-FileCopyrightText: 2011-2013 Lamarque Souza <lamarque@kde.org> |
4 | |
5 | SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL |
6 | */ |
7 | |
8 | #ifndef NETWORKMANAGERQT_SECRETAGENT_H |
9 | #define NETWORKMANAGERQT_SECRETAGENT_H |
10 | |
11 | #include <QDBusContext> |
12 | #include <QDBusMessage> |
13 | #include <QDBusObjectPath> |
14 | #include <QObject> |
15 | |
16 | #include "generictypes.h" |
17 | #include <networkmanagerqt/networkmanagerqt_export.h> |
18 | |
19 | namespace NetworkManager |
20 | { |
21 | class SecretAgentPrivate; |
22 | |
23 | /*! |
24 | * \class NetworkManager::SecretAgent |
25 | * \inheaderfile NetworkManagerQt/SecretAgent |
26 | * \inmodule NetworkManagerQt |
27 | * |
28 | * \brief Implementation of a private D-Bus interface used by secret agents that store and provide secrets to NetworkManager. |
29 | * |
30 | * If an agent provides secrets to NetworkManager as part of connection creation, and the some of those secrets are "agent owned" |
31 | * the agent should store those secrets itself and should not expect its SaveSecrets() method to be called. |
32 | * SaveSecrets() will be called eg if some program other than the agent itself (like a connection editor) changes the secrets out of band. |
33 | */ |
34 | class NETWORKMANAGERQT_EXPORT SecretAgent : public QObject, protected QDBusContext |
35 | { |
36 | Q_OBJECT |
37 | public: |
38 | /*! |
39 | * |
40 | * \value NotAuthorized |
41 | * \value InvalidConnection |
42 | * \value UserCanceled |
43 | * \value AgentCanceled |
44 | * \value InternalError |
45 | * \value NoSecrets |
46 | */ |
47 | enum Error { |
48 | NotAuthorized, |
49 | InvalidConnection, |
50 | UserCanceled, |
51 | AgentCanceled, |
52 | InternalError, |
53 | NoSecrets, |
54 | }; |
55 | |
56 | /*! |
57 | * |
58 | * Flags modifying the behavior of GetSecrets request. |
59 | * |
60 | * \value None |
61 | * No special behavior; by default no user interaction is allowed and requests for secrets are fulfilled from persistent storage, or if no secrets |
62 | * are available an error is returned. |
63 | * \value AllowInteraction Allows the request to interact with the user, possibly prompting via UI for secrets if any |
64 | * are required, or if none are found in persistent storage. |
65 | * \value RequestNew Explicitly prompt for new secrets from the user. This flag signals that |
66 | * NetworkManager thinks any existing secrets are invalid or wrong. This flag implies that interaction is allowed. |
67 | * \value UserRequested Set if the request |
68 | * was initiated by user-requested action via the D-Bus interface, as opposed to automatically initiated by NetworkManager in response to (for example) scan |
69 | * results or carrier changes. |
70 | */ |
71 | enum GetSecretsFlag { |
72 | None = 0, |
73 | AllowInteraction = 0x01, |
74 | RequestNew = 0x02, |
75 | UserRequested = 0x04, |
76 | }; |
77 | Q_DECLARE_FLAGS(GetSecretsFlags, GetSecretsFlag) |
78 | |
79 | /*! |
80 | * |
81 | * Capabilities to pass to secret agents |
82 | * |
83 | * \value NoCapability |
84 | * No capability |
85 | * \value VpnHints |
86 | * Pass hints to secret agent |
87 | */ |
88 | enum Capability { |
89 | NoCapability = 0, |
90 | VpnHints = 0x01, |
91 | }; |
92 | Q_DECLARE_FLAGS(Capabilities, Capability) |
93 | |
94 | /*! |
95 | * Registers a SecretAgent with the \a id on NetworkManager |
96 | * Optionally add a capabilities argument |
97 | */ |
98 | explicit SecretAgent(const QString &id, QObject *parent = nullptr); |
99 | /*! |
100 | */ |
101 | explicit SecretAgent(const QString &id, NetworkManager::SecretAgent::Capabilities capabilities, QObject *parent = nullptr); |
102 | ~SecretAgent() override; |
103 | |
104 | /*! |
105 | * Send to NetworkManager the \a error the subclass has |
106 | * found, the \a explanation is useful for debugging purposes, |
107 | * and the \a callMessage is ONLY needed if setDelayedReply() |
108 | * was set to \a true when the method was called. |
109 | */ |
110 | void sendError(Error error, const QString &explanation, const QDBusMessage &callMessage = QDBusMessage()) const; |
111 | |
112 | public Q_SLOTS: |
113 | /*! |
114 | * Called when the subclass should retrieve and return secrets. |
115 | * If the request is canceled, called function should call |
116 | * sendError(), in this case the return value is ignored. |
117 | * |
118 | * \a connection Nested settings maps containing the connection for which secrets are being requested. |
119 | * This may contain system-owned secrets if the agent has successfully authenticated to modify system network settings |
120 | * and the GetSecrets request flags allow user interaction. |
121 | * |
122 | * \a connection_path Object path of the connection for which secrets are being requested. |
123 | * |
124 | * \a setting_name Setting name for which secrets are being requested. |
125 | * |
126 | * \a hints Array of strings of key names in the requested setting for which NetworkManager thinks a secrets may be required, |
127 | * and/or well-known identifiers and data that may be useful to the client in processing the secrets request. Note that it's not |
128 | * always possible to determine which secret is required, so in some cases no hints may be given. The Agent should return any |
129 | * secrets it has, or that it thinks are required, regardless of what hints NetworkManager sends in this request. |
130 | * |
131 | * \a flags Flags which modify the behavior of the secrets request (see \ GetSecretsFlag) |
132 | */ |
133 | virtual NMVariantMapMap GetSecrets(const NMVariantMapMap &connection, |
134 | const QDBusObjectPath &connection_path, |
135 | const QString &setting_name, |
136 | const QStringList &hints, |
137 | uint flags) = 0; |
138 | |
139 | /*! |
140 | * Called when the subclass should cancel an outstanding request to |
141 | * get secrets for a given connection. |
142 | * Cancelling the request MUST sendError() with the original |
143 | * DBus message using AgentCanceled param as the error type. |
144 | * |
145 | * \a connection_path Object path of the connection for which, if secrets for the given 'setting_name' are being requested, the request should be |
146 | * canceled. |
147 | * |
148 | * \a setting_name Setting name for which secrets for this connection were originally being requested. |
149 | */ |
150 | virtual void CancelGetSecrets(const QDBusObjectPath &connection_path, const QString &setting_name) = 0; |
151 | |
152 | /*! |
153 | * Called when the subclass should save the secrets contained in the |
154 | * connection to backing storage. |
155 | * |
156 | * \a connection Nested settings maps containing the connection for which secrets are being saved. |
157 | * This may contain system-owned secrets if the agent has successfully authenticated to modify system network settings |
158 | * and the GetSecrets request flags allow user interaction. |
159 | * |
160 | * \a connection_path Object path of the connection for which the agent should save secrets to backing storage. |
161 | */ |
162 | virtual void SaveSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path) = 0; |
163 | |
164 | /*! |
165 | * Called when the subclass should delete the secrets contained in the |
166 | * connection from backing storage. |
167 | * |
168 | * \a connection Nested settings maps containing the connection properties (sans secrets), |
169 | * for which the agent should delete the secrets from backing storage. |
170 | * |
171 | * \a connection_path Object path of the connection for which the agent should delete secrets from backing storage. |
172 | */ |
173 | virtual void DeleteSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path) = 0; |
174 | |
175 | private: |
176 | Q_DECLARE_PRIVATE(SecretAgent) |
177 | Q_PRIVATE_SLOT(d_func(), void registerAgent()) |
178 | Q_PRIVATE_SLOT(d_func(), void registerAgent(const NetworkManager::SecretAgent::Capabilities capabilities)) |
179 | Q_PRIVATE_SLOT(d_func(), void dbusInterfacesAdded(const QDBusObjectPath &path, const QVariantMap &interfaces)) |
180 | |
181 | SecretAgentPrivate *const d_ptr; |
182 | }; |
183 | } |
184 | Q_DECLARE_OPERATORS_FOR_FLAGS(NetworkManager::SecretAgent::GetSecretsFlags) |
185 | Q_DECLARE_OPERATORS_FOR_FLAGS(NetworkManager::SecretAgent::Capabilities) |
186 | |
187 | #endif // NETWORKMANAGERQT_SECRETAGENT_H |
188 | |