mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-10-14 20:18:39 +00:00
16bb798861
A new agent registration method enables agents to pass capabilities during the registration process.
241 lines
12 KiB
XML
241 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
|
|
<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
|
|
|
|
<interface name="org.freedesktop.NetworkManager.SecretAgent">
|
|
<tp:docstring>
|
|
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. The agent should implement this D-Bus interface on an object
|
|
with the path /org/freedesktop/NetworkManager/SecretAgent.
|
|
</tp:docstring>
|
|
|
|
<method name="GetSecrets">
|
|
<tp:docstring>
|
|
Retrieve and return stored secrets, if any, or request new
|
|
secrets from the agent's user. If user interaction is allowed
|
|
and the user enters new secrets, the agent is expected to save
|
|
the new secrets to persistent storage (if the secret's flags
|
|
include AGENT_OWNED) as NetworkManager will not send these
|
|
secrets back to the same agent via a SaveSecrets() call. If
|
|
the user canceled any interaction, the agent should return the
|
|
UserCanceled error (see below).
|
|
</tp:docstring>
|
|
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_get_secrets"/>
|
|
<annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
|
|
<arg name="connection" type="a{sa{sv}}" direction="in" tp:type="String_String_Variant_Map_Map">
|
|
<tp:docstring>
|
|
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.
|
|
</tp:docstring>
|
|
</arg>
|
|
<arg name="connection_path" type="o" direction="in">
|
|
<tp:docstring>
|
|
Object path of the connection for which secrets are being
|
|
requested.
|
|
</tp:docstring>
|
|
</arg>
|
|
<arg name="setting_name" type="s" direction="in">
|
|
<tp:docstring>
|
|
Setting name for which secrets are being requested.
|
|
</tp:docstring>
|
|
</arg>
|
|
<arg name="hints" type="as" direction="in">
|
|
<tp:docstring>
|
|
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.
|
|
</tp:docstring>
|
|
</arg>
|
|
<arg name="flags" type="u" direction="in" tp:type="NM_SECRET_AGENT_GET_SECRETS_FLAGS">
|
|
<tp:docstring>
|
|
Flags which modify the behavior of the secrets request.
|
|
If true, new secrets are assumed to be invalid or incorrect,
|
|
and the agent should ask the user for new secrets. If false,
|
|
existing secrets should be retrieved from storage and
|
|
returned without interrupting the user.
|
|
</tp:docstring>
|
|
</arg>
|
|
|
|
<arg name="secrets" type="a{sa{sv}}" direction="out" tp:type="String_String_Variant_Map_Map">
|
|
<tp:docstring>
|
|
Nested settings maps containing secrets. Each setting MUST
|
|
contain at least the 'name' field, containing the name of
|
|
the setting, and one or more secrets.
|
|
</tp:docstring>
|
|
</arg>
|
|
|
|
<tp:possible-errors>
|
|
<tp:error name="org.freedesktop.NetworkManager.SecretAgent.NotAuthorized">
|
|
<tp:docstring>
|
|
Should be returned when the process requesting secrets is
|
|
not authorized to do so (like if the caller is not root
|
|
or not NetworkManager).
|
|
</tp:docstring>
|
|
</tp:error>
|
|
<tp:error name="org.freedesktop.NetworkManager.SecretAgent.InvalidConnection">
|
|
<tp:docstring>
|
|
Should be returned if the 'connection' argument is invalid.
|
|
</tp:docstring>
|
|
</tp:error>
|
|
<tp:error name="org.freedesktop.NetworkManager.SecretAgent.UserCanceled">
|
|
<tp:docstring>
|
|
Should be returned when the user has canceled the request.
|
|
</tp:docstring>
|
|
</tp:error>
|
|
<tp:error name="org.freedesktop.NetworkManager.SecretAgent.AgentCanceled">
|
|
<tp:docstring>
|
|
Should be returned when NetworkManager has requested that
|
|
the agent cancel the request.
|
|
</tp:docstring>
|
|
</tp:error>
|
|
<tp:error name="org.freedesktop.NetworkManager.SecretAgent.InternalError">
|
|
<tp:docstring>
|
|
Should be returned if the agent has encountered some internal
|
|
error processing the request.
|
|
</tp:docstring>
|
|
</tp:error>
|
|
<tp:error name="org.freedesktop.NetworkManager.SecretAgent.NoSecrets">
|
|
<tp:docstring>
|
|
Should be returned if there are no available secrets, for
|
|
example if user interaction is not allowed and there are
|
|
no secrets stored by the agent for this connection.
|
|
</tp:docstring>
|
|
</tp:error>
|
|
</tp:possible-errors>
|
|
</method>
|
|
|
|
<tp:flags name="NM_SECRET_AGENT_GET_SECRETS_FLAGS" value-prefix="NM_SECRET_AGENT_GET_SECRETS_FLAG" type="u">
|
|
<tp:docstring>
|
|
Flags modifying the behavior of GetSecrets request.
|
|
</tp:docstring>
|
|
<tp:flag suffix="NONE" value="0x0">
|
|
<tp:docstring>
|
|
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.
|
|
</tp:docstring>
|
|
</tp:flag>
|
|
<tp:flag suffix="ALLOW_INTERACTION" value="0x1">
|
|
<tp:docstring>
|
|
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.
|
|
</tp:docstring>
|
|
</tp:flag>
|
|
<tp:flag suffix="REQUEST_NEW" value="0x2">
|
|
<tp:docstring>
|
|
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.
|
|
</tp:docstring>
|
|
</tp:flag>
|
|
<tp:flag suffix="USER_REQUESTED" value="0x4">
|
|
<tp:docstring>
|
|
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.
|
|
</tp:docstring>
|
|
</tp:flag>
|
|
</tp:flags>
|
|
|
|
<method name="CancelGetSecrets">
|
|
<tp:docstring>
|
|
Cancel a pending GetSecrets request for secrets of the given
|
|
connection. Any GetSecrets request with the same
|
|
'connection_path' and 'setting_name' that are given in a
|
|
CancelGetSecrets request should be canceled.
|
|
</tp:docstring>
|
|
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_cancel_get_secrets"/>
|
|
<annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
|
|
<arg name="connection_path" type="o" direction="in">
|
|
<tp:docstring>
|
|
Object path of the connection for which, if secrets for
|
|
the given 'setting_name' are being requested, the request
|
|
should be canceled.
|
|
</tp:docstring>
|
|
</arg>
|
|
<arg name="setting_name" type="s" direction="in">
|
|
<tp:docstring>
|
|
Setting name for which secrets for this connection were
|
|
originally being requested.
|
|
</tp:docstring>
|
|
</arg>
|
|
</method>
|
|
|
|
<method name="SaveSecrets">
|
|
<tp:docstring>
|
|
Save given secrets to backing storage.
|
|
</tp:docstring>
|
|
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_save_secrets"/>
|
|
<annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
|
|
<arg name="connection" type="a{sa{sv}}" direction="in" tp:type="String_String_Variant_Map_Map">
|
|
<tp:docstring>
|
|
Nested settings maps containing the entire connection
|
|
(including secrets), for which the agent should save the
|
|
secrets to backing storage. This method will not be called
|
|
when the agent itself is the process creating or updating
|
|
a connection; in that case the agent is assumed to have
|
|
already saved those secrets since it had them already.
|
|
</tp:docstring>
|
|
</arg>
|
|
<arg name="connection_path" type="o" direction="in">
|
|
<tp:docstring>
|
|
Object path of the connection for which the agent should
|
|
save secrets to backing storage.
|
|
</tp:docstring>
|
|
</arg>
|
|
</method>
|
|
|
|
<method name="DeleteSecrets">
|
|
<tp:docstring>
|
|
Delete secrets from backing storage.
|
|
</tp:docstring>
|
|
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_delete_secrets"/>
|
|
<annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
|
|
<arg name="connection" type="a{sa{sv}}" direction="in" tp:type="String_String_Variant_Map_Map">
|
|
<tp:docstring>
|
|
Nested settings maps containing the connection properties
|
|
(sans secrets), for which the agent should delete the
|
|
secrets from backing storage.
|
|
</tp:docstring>
|
|
</arg>
|
|
<arg name="connection_path" type="o" direction="in">
|
|
<tp:docstring>
|
|
Object path of the connection for which the agent should
|
|
delete secrets from backing storage.
|
|
</tp:docstring>
|
|
</arg>
|
|
</method>
|
|
|
|
<tp:flags name="NM_SECRET_AGENT_CAPABILITIES" value-prefix="NM_SECRET_AGENT_CAPABILITY" type="u">
|
|
<tp:flag suffix="NONE" value="0x0">
|
|
<tp:docstring>No special capabilities.</tp:docstring>
|
|
</tp:flag>
|
|
<tp:flag suffix="VPN_HINTS" value="0x1">
|
|
<tp:docstring>
|
|
The agent supports passing hints to VPN plugin authentication
|
|
dialogs.
|
|
</tp:docstring>
|
|
</tp:flag>
|
|
</tp:flags>
|
|
|
|
</interface>
|
|
|
|
</node>
|