NetworkManager::SecretAgent Class
class NetworkManager::SecretAgentImplementation of a private D-Bus interface used by secret agents that store and provide secrets to NetworkManager. More...
| Header: | #include <NetworkManagerQt/SecretAgent> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS NetworkManagerQt)target_link_libraries(mytarget PRIVATE KF6::NetworkManagerQt) |
| Inherits: | QObject and QDBusContext (protected) |
Public Types
| flags | Capabilities |
| enum | Capability { NoCapability, VpnHints } |
| enum | Error { NotAuthorized, InvalidConnection, UserCanceled, AgentCanceled, InternalError, NoSecrets } |
| enum | GetSecretsFlag { None, AllowInteraction, RequestNew, UserRequested } |
| flags | GetSecretsFlags |
Public Functions
| SecretAgent(const QString &id, QObject *parent = nullptr) | |
| SecretAgent(const QString &id, NetworkManager::SecretAgent::Capabilities capabilities, QObject *parent = nullptr) | |
| void | sendError(NetworkManager::SecretAgent::Error error, const QString &explanation, const QDBusMessage &callMessage = QDBusMessage()) const |
Public Slots
| virtual void | CancelGetSecrets(const QDBusObjectPath &connection_path, const QString &setting_name) = 0 |
| virtual void | DeleteSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path) = 0 |
| virtual NMVariantMapMap | GetSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path, const QString &setting_name, const QStringList &hints, uint flags) = 0 |
| virtual void | SaveSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path) = 0 |
Detailed Description
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.
Member Type Documentation
enum SecretAgent::Capability
flags SecretAgent::Capabilities
Capabilities to pass to secret agents
| Constant | Value | Description |
|---|---|---|
NetworkManager::SecretAgent::NoCapability | 0 | No capability |
NetworkManager::SecretAgent::VpnHints | 0x01 | Pass hints to secret agent |
The Capabilities type is a typedef for QFlags<Capability>. It stores an OR combination of Capability values.
enum SecretAgent::Error
| Constant | Value |
|---|---|
NetworkManager::SecretAgent::NotAuthorized | 0 |
NetworkManager::SecretAgent::InvalidConnection | 1 |
NetworkManager::SecretAgent::UserCanceled | 2 |
NetworkManager::SecretAgent::AgentCanceled | 3 |
NetworkManager::SecretAgent::InternalError | 4 |
NetworkManager::SecretAgent::NoSecrets | 5 |
enum SecretAgent::GetSecretsFlag
flags SecretAgent::GetSecretsFlags
Flags modifying the behavior of GetSecrets request.
| Constant | Value | Description |
|---|---|---|
NetworkManager::SecretAgent::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. |
NetworkManager::SecretAgent::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. |
NetworkManager::SecretAgent::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. |
NetworkManager::SecretAgent::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. |
The GetSecretsFlags type is a typedef for QFlags<GetSecretsFlag>. It stores an OR combination of GetSecretsFlag values.
Member Function Documentation
[explicit] SecretAgent::SecretAgent(const QString &id, QObject *parent = nullptr)
Registers a SecretAgent with the id on NetworkManager Optionally add a capabilities argument
[explicit] SecretAgent::SecretAgent(const QString &id, NetworkManager::SecretAgent::Capabilities capabilities, QObject *parent = nullptr)
[pure virtual slot] void SecretAgent::CancelGetSecrets(const QDBusObjectPath &connection_path, const QString &setting_name)
Called when the subclass should cancel an outstanding request to get secrets for a given connection. Cancelling the request MUST sendError() with the original DBus message using AgentCanceled param as the error type.
connection_path Object path of the connection for which, if secrets for the given 'setting_name' are being requested, the request should be canceled.
setting_name Setting name for which secrets for this connection were originally being requested.
[pure virtual slot] void SecretAgent::DeleteSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path)
Called when the subclass should delete the secrets contained in the connection from backing storage.
connection Nested settings maps containing the connection properties (sans secrets), for which the agent should delete the secrets from backing storage.
connection_path Object path of the connection for which the agent should delete secrets from backing storage.
[pure virtual slot] NMVariantMapMap SecretAgent::GetSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path, const QString &setting_name, const QStringList &hints, uint flags)
Called when the subclass should retrieve and return secrets. If the request is canceled, called function should call sendError(), in this case the return value is ignored.
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.
connection_path Object path of the connection for which secrets are being requested.
setting_name Setting name for which secrets are being requested.
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.
flags Flags which modify the behavior of the secrets request (see GetSecretsFlag)
[pure virtual slot] void SecretAgent::SaveSecrets(const NMVariantMapMap &connection, const QDBusObjectPath &connection_path)
Called when the subclass should save the secrets contained in the connection to backing storage.
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.
connection_path Object path of the connection for which the agent should save secrets to backing storage.
void SecretAgent::sendError(NetworkManager::SecretAgent::Error error, const QString &explanation, const QDBusMessage &callMessage = QDBusMessage()) const
Send to NetworkManager the error the subclass has found, the explanation is useful for debugging purposes, and the callMessage is ONLY needed if setDelayedReply() was set to true when the method was called.