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
19namespace NetworkManager
20{
21class 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 */
34class NETWORKMANAGERQT_EXPORT SecretAgent : public QObject, protected QDBusContext
35{
36 Q_OBJECT
37public:
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
112public 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
175private:
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}
184Q_DECLARE_OPERATORS_FOR_FLAGS(NetworkManager::SecretAgent::GetSecretsFlags)
185Q_DECLARE_OPERATORS_FOR_FLAGS(NetworkManager::SecretAgent::Capabilities)
186
187#endif // NETWORKMANAGERQT_SECRETAGENT_H
188

source code of networkmanager-qt/src/secretagent.h