1 <?xml version="1.0" encoding="UTF-8" ?>
3 <node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
5 <interface name="org.freedesktop.NetworkManager.SecretAgent">
7 Private D-Bus interface used by secret agents that store and provide
8 secrets to NetworkManager. If an agent provides secrets to
9 NetworkManager as part of connection creation, and the some of those
10 secrets are "agent owned" the agent should store those secrets
11 itself and should not expect its SaveSecrets() method to be called.
12 SaveSecrets() will be called eg if some program other than the
13 agent itself (like a connection editor) changes the secrets out of
14 band. The agent should implement this D-Bus interface on an object
15 with the path /org/freedesktop/NetworkManager/SecretAgent.
18 <method name="GetSecrets">
20 Retrieve and return stored secrets, if any, or request new
21 secrets from the agent's user. If user interaction is allowed
22 and the user enters new secrets, the agent is expected to save
23 the new secrets to persistent storage (if the secret's flags
24 include AGENT_OWNED) as NetworkManager will not send these
25 secrets back to the same agent via a SaveSecrets() call. If
26 the user canceled any interaction, the agent should return the
27 UserCanceled error (see below).
29 <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_get_secrets"/>
30 <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
31 <arg name="connection" type="a{sa{sv}}" direction="in" tp:type="String_String_Variant_Map_Map">
33 Nested settings maps containing the connection for which
34 secrets are being requested. This may contain system-owned
35 secrets if the agent has successfully authenticated to
36 modify system network settings and the GetSecrets request
37 flags allow user interaction.
40 <arg name="connection_path" type="o" direction="in">
42 Object path of the connection for which secrets are being
46 <arg name="setting_name" type="s" direction="in">
48 Setting name for which secrets are being requested.
51 <arg name="hints" type="as" direction="in">
53 Array of strings of key names in the requested setting for
54 which NetworkManager thinks a secrets may be required,
55 and/or well-known identifiers and data that may be useful
56 to the client in processing the secrets request. Note that
57 it's not always possible to determine which secret is
58 required, so in some cases no hints may be given. The Agent
59 should return any secrets it has, or that it thinks are
60 required, regardless of what hints NetworkManager sends
61 in this request. Some hints have special prefixes that
62 provide information to the agent; for example, VPN requests
63 may send server-specific messages prefixed with
67 <arg name="flags" type="u" direction="in" tp:type="NM_SECRET_AGENT_GET_SECRETS_FLAGS">
69 Flags which modify the behavior of the secrets request.
70 If true, new secrets are assumed to be invalid or incorrect,
71 and the agent should ask the user for new secrets. If false,
72 existing secrets should be retrieved from storage and
73 returned without interrupting the user.
77 <arg name="secrets" type="a{sa{sv}}" direction="out" tp:type="String_String_Variant_Map_Map">
79 Nested settings maps containing secrets. Each setting MUST
80 contain at least the 'name' field, containing the name of
81 the setting, and one or more secrets.
86 <tp:error name="org.freedesktop.NetworkManager.SecretAgent.NotAuthorized">
88 Should be returned when the process requesting secrets is
89 not authorized to do so (like if the caller is not root
90 or not NetworkManager).
93 <tp:error name="org.freedesktop.NetworkManager.SecretAgent.InvalidConnection">
95 Should be returned if the 'connection' argument is invalid.
98 <tp:error name="org.freedesktop.NetworkManager.SecretAgent.UserCanceled">
100 Should be returned when the user has canceled the request.
103 <tp:error name="org.freedesktop.NetworkManager.SecretAgent.AgentCanceled">
105 Should be returned when NetworkManager has requested that
106 the agent cancel the request.
109 <tp:error name="org.freedesktop.NetworkManager.SecretAgent.InternalError">
111 Should be returned if the agent has encountered some internal
112 error processing the request.
115 <tp:error name="org.freedesktop.NetworkManager.SecretAgent.NoSecrets">
117 Should be returned if there are no available secrets, for
118 example if user interaction is not allowed and there are
119 no secrets stored by the agent for this connection.
122 </tp:possible-errors>
125 <tp:flags name="NM_SECRET_AGENT_GET_SECRETS_FLAGS" value-prefix="NM_SECRET_AGENT_GET_SECRETS_FLAG" type="u">
127 Flags modifying the behavior of GetSecrets request.
129 <tp:flag suffix="NONE" value="0x0">
131 No special behavior; by default no user interaction is allowed and
132 requests for secrets are fulfilled from persistent storage, or
133 if no secrets are available an error is returned.
136 <tp:flag suffix="ALLOW_INTERACTION" value="0x1">
138 Allows the request to interact with the user, possibly prompting
139 via UI for secrets if any are required, or if none are found in
143 <tp:flag suffix="REQUEST_NEW" value="0x2">
145 Explicitly prompt for new secrets from the user. This flag
146 signals that NetworkManager thinks any existing secrets are
147 invalid or wrong. This flag implies that interaction is allowed.
150 <tp:flag suffix="USER_REQUESTED" value="0x4">
152 Set if the request was initiated by user-requested action via the
153 D-Bus interface, as opposed to automatically initiated by
154 NetworkManager in response to (for example) scan results or
160 <method name="CancelGetSecrets">
162 Cancel a pending GetSecrets request for secrets of the given
163 connection. Any GetSecrets request with the same
164 'connection_path' and 'setting_name' that are given in a
165 CancelGetSecrets request should be canceled.
167 <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_cancel_get_secrets"/>
168 <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
169 <arg name="connection_path" type="o" direction="in">
171 Object path of the connection for which, if secrets for
172 the given 'setting_name' are being requested, the request
176 <arg name="setting_name" type="s" direction="in">
178 Setting name for which secrets for this connection were
179 originally being requested.
184 <method name="SaveSecrets">
186 Save given secrets to backing storage.
188 <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_save_secrets"/>
189 <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
190 <arg name="connection" type="a{sa{sv}}" direction="in" tp:type="String_String_Variant_Map_Map">
192 Nested settings maps containing the entire connection
193 (including secrets), for which the agent should save the
194 secrets to backing storage. This method will not be called
195 when the agent itself is the process creating or updating
196 a connection; in that case the agent is assumed to have
197 already saved those secrets since it had them already.
200 <arg name="connection_path" type="o" direction="in">
202 Object path of the connection for which the agent should
203 save secrets to backing storage.
208 <method name="DeleteSecrets">
210 Delete secrets from backing storage.
212 <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_delete_secrets"/>
213 <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
214 <arg name="connection" type="a{sa{sv}}" direction="in" tp:type="String_String_Variant_Map_Map">
216 Nested settings maps containing the connection properties
217 (sans secrets), for which the agent should delete the
218 secrets from backing storage.
221 <arg name="connection_path" type="o" direction="in">
223 Object path of the connection for which the agent should
224 delete secrets from backing storage.
229 <tp:flags name="NM_SECRET_AGENT_CAPABILITIES" value-prefix="NM_SECRET_AGENT_CAPABILITY" type="u">
230 <tp:flag suffix="NONE" value="0x0">
231 <tp:docstring>No special capabilities.</tp:docstring>
233 <tp:flag suffix="VPN_HINTS" value="0x1">
235 The agent supports passing hints to VPN plugin authentication