File indexing completed on 2025-03-16 12:58:26

 /*
     SPDX-FileCopyrightText: 2011 Ilia Kats <ilia-kats@gmx.net>
     SPDX-FileCopyrightText: 2011-2013 Lamarque Souza <lamarque@kde.org>
 
     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
 */
 
 #ifndef NETWORKMANAGERQT_SECRETAGENT_H
 #define NETWORKMANAGERQT_SECRETAGENT_H
 
 #include <QDBusContext>
 #include <QDBusMessage>
 #include <QDBusObjectPath>
 #include <QObject>
 
 #include "generictypes.h"
 #include <networkmanagerqt/networkmanagerqt_export.h>
 
 namespace NetworkManager
 {
 class SecretAgentPrivate;
 
 /**
  * Implementation of a private D-Bus interface used by secret agents that store and provide secrets to NetworkManager.
  * If an agent provides secrets to NetworkManager as part of connection creation, and the some of those secrets are "agent owned"
  * the agent should store those secrets itself and should not expect its SaveSecrets() method to be called.
  * SaveSecrets() will be called eg if some program other than the agent itself (like a connection editor) changes the secrets out of band.
  */
 class NETWORKMANAGERQT_EXPORT SecretAgent : public QObject, protected QDBusContext
 {
     Q_OBJECT
 public:
     enum Error {
         NotAuthorized,
         InvalidConnection,
         UserCanceled,
         AgentCanceled,
         InternalError,
         NoSecrets,
     };
 
     /**
      * Flags modifying the behavior of GetSecrets request.
      */
     enum GetSecretsFlag {
         None = 0, /**<  No special behavior; by default no user interaction is allowed and requests for secrets are fulfilled from persistent storage, or if no
                      secrets are available an error is returned. */
         AllowInteraction = 0x01, /**< Allows the request to interact with the user, possibly prompting via UI for secrets if any are required, or if none are
                                     found in persistent storage. */
         RequestNew = 0x02, /**< Explicitly prompt for new secrets from the user. This flag signals that NetworkManager thinks any existing secrets are invalid
                               or wrong. This flag implies that interaction is allowed. */
         UserRequested = 0x04, /**< Set if the request was initiated by user-requested action via the D-Bus interface, as opposed to automatically initiated by
                                  NetworkManager in response to (for example) scan results or carrier changes. */
     };
     Q_DECLARE_FLAGS(GetSecretsFlags, GetSecretsFlag)
 
     /**
      * Capabilities to pass to secret agents
      */
     enum Capability {
         NoCapability = 0, /**< No capability */
         VpnHints = 0x01, /**< Pass hints to secret agent */
     };
     Q_DECLARE_FLAGS(Capabilities, Capability)
 
     /**
      * Registers a SecretAgent with the \p id on NetworkManager
      * Optionally add a capabilities argument
      */
     explicit SecretAgent(const QString &id, QObject *parent = nullptr);
     explicit SecretAgent(const QString &id, NetworkManager::SecretAgent::Capabilities capabilities, QObject *parent = nullptr);
     ~SecretAgent() override;
 
     /**
      * Send to NetworkManager the \p error the subclass has
      * found, the \p explanation is useful for debugging purposes,
      * and the \p callMessage is ONLY needed if \ref setDelayedReply()
      * was set to @p true when the method was called.
      */
     void sendError(Error error, const QString &explanation, const QDBusMessage &callMessage = QDBusMessage()) const;
 
 public Q_SLOTS:
     /**
      * Called when the subclass should retrieve and return secrets.
      * If the request is canceled, called function should call
      * \ref sendError(), in this case the return value is ignored.
      *
      * @param connection Nested settings maps containing the connection for which secrets are being requested.
      *        This may contain system-owned secrets if the agent has successfully authenticated to modify system network settings
      *        and the GetSecrets request flags allow user interaction.
      * @param connection_path Object path of the connection for which secrets are being requested.
      * @param setting_name Setting name for which secrets are being requested.
      * @param hints Array of strings of key names in the requested setting for which NetworkManager thinks a secrets may be required,
      *        and/or well-known identifiers and data that may be useful to the client in processing the secrets request. Note that it's not
      *        always possible to determine which secret is required, so in some cases no hints may be given. The Agent should return any
      *        secrets it has, or that it thinks are required, regardless of what hints NetworkManager sends in this request.
      * @param flags Flags which modify the behavior of the secrets request (see @ref GetSecretsFlag)
      */
     virtual NMVariantMapMap GetSecrets(const NMVariantMapMap &connection,
                                        const QDBusObjectPath &connection_path,
                                        const QString &setting_name,
                                        const QStringList &hints,
                                        uint flags) = 0;
 
     /**
      * Called when the subclass should cancel an outstanding request to
      * get secrets for a given connection.
      * Cancelling the request MUST \ref sendError() with the original
      * DBus message using \ref AgentCanceled param as the error type.
      *
      * @param connection_path Object path of the connection for which, if secrets for the given 'setting_name' are being requested, the request should be
      * canceled.
      * @param setting_name Setting name for which secrets for this connection were originally being requested.
      */
     virtual void CancelGetSecrets(const QDBusObjectPath &connection_path, const QString &setting_name) = 0;
 
     /**
      * Called when the subclass should save the secrets contained in the
      * connection to backing storage.
      *
      * @param connection Nested settings maps containing the connection for which secrets are being saved.
      *        This may contain system-owned secrets if the agent has successfully authenticated to modify system network settings
      *        and the GetSecrets request flags allow user interaction.
      * @param connection_path Object path of the connection for which the agent should save secrets to backing storage.
      */
     virtual void SaveSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path) = 0;
 
     /**
      * Called when the subclass should delete the secrets contained in the
      * connection from backing storage.
      *
      * @param connection Nested settings maps containing the connection properties (sans secrets),
      *        for which the agent should delete the secrets from backing storage.
      * @param connection_path Object path of the connection for which the agent should delete secrets from backing storage.
      */
     virtual void DeleteSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path) = 0;
 
 private:
     Q_DECLARE_PRIVATE(SecretAgent)
     Q_PRIVATE_SLOT(d_func(), void registerAgent())
     Q_PRIVATE_SLOT(d_func(), void registerAgent(const NetworkManager::SecretAgent::Capabilities capabilities))
     Q_PRIVATE_SLOT(d_func(), void dbusInterfacesAdded(const QDBusObjectPath &path, const QVariantMap &interfaces))
 
     SecretAgentPrivate *const d_ptr;
 };
 }
 Q_DECLARE_OPERATORS_FOR_FLAGS(NetworkManager::SecretAgent::GetSecretsFlags)
 Q_DECLARE_OPERATORS_FOR_FLAGS(NetworkManager::SecretAgent::Capabilities)
 
 #endif // NETWORKMANAGERQT_SECRETAGENT_H