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

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