introspection/nm-secret-agent.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2
   3 <node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   4
   5     <interface name="org.freedesktop.NetworkManager.SecretAgent">
   6         <annotation name="org.gtk.GDBus.DocString" value="
   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 &quot;agent owned&quot; 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.
  16         " />
  17
  18         <method name="GetSecrets">
  19             <annotation name="org.gtk.GDBus.DocString" value="
  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).
  28             " />
  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">
  32                 <annotation name="org.gtk.GDBus.DocString" value="
  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.
  38                 " />
  39             </arg>
  40             <arg name="connection_path" type="o" direction="in">
  41                 <annotation name="org.gtk.GDBus.DocString" value="
  42                     Object path of the connection for which secrets are being
  43                     requested.
  44                 " />
  45             </arg>
  46             <arg name="setting_name" type="s" direction="in">
  47                 <annotation name="org.gtk.GDBus.DocString" value="
  48                     Setting name for which secrets are being requested.
  49                 " />
  50             </arg>
  51             <arg name="hints" type="as" direction="in">
  52                 <annotation name="org.gtk.GDBus.DocString" value="
  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
  64                     &quot;x-vpn-message:&quot;.
  65                 " />
  66             </arg>
  67             <arg name="flags" type="u" direction="in" tp:type="NM_SECRET_AGENT_GET_SECRETS_FLAGS">
  68                 <annotation name="org.gtk.GDBus.DocString" value="
  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.
  74                 " />
  75             </arg>
  76
  77             <arg name="secrets" type="a{sa{sv}}" direction="out" tp:type="String_String_Variant_Map_Map">
  78                 <annotation name="org.gtk.GDBus.DocString" value="
  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.
  82                 " />
  83             </arg>
  84
  85             <tp:possible-errors>
  86               <tp:error name="org.freedesktop.NetworkManager.SecretAgent.NotAuthorized">
  87                   <annotation name="org.gtk.GDBus.DocString" value="
  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).
  91                   " />
  92               </tp:error>
  93               <tp:error name="org.freedesktop.NetworkManager.SecretAgent.InvalidConnection">
  94                   <annotation name="org.gtk.GDBus.DocString" value="
  95                       Should be returned if the 'connection' argument is invalid.
  96                   " />
  97               </tp:error>
  98               <tp:error name="org.freedesktop.NetworkManager.SecretAgent.UserCanceled">
  99                   <annotation name="org.gtk.GDBus.DocString" value="
 100                       Should be returned when the user has canceled the request.
 101                   " />
 102               </tp:error>
 103               <tp:error name="org.freedesktop.NetworkManager.SecretAgent.AgentCanceled">
 104                   <annotation name="org.gtk.GDBus.DocString" value="
 105                       Should be returned when NetworkManager has requested that
 106                       the agent cancel the request.
 107                   " />
 108               </tp:error>
 109               <tp:error name="org.freedesktop.NetworkManager.SecretAgent.InternalError">
 110                   <annotation name="org.gtk.GDBus.DocString" value="
 111                       Should be returned if the agent has encountered some internal
 112                       error processing the request.
 113                   " />
 114               </tp:error>
 115               <tp:error name="org.freedesktop.NetworkManager.SecretAgent.NoSecrets">
 116                   <annotation name="org.gtk.GDBus.DocString" value="
 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.
 120                   " />
 121               </tp:error>
 122             </tp:possible-errors>
 123         </method>
 124
 125         <tp:flags name="NM_SECRET_AGENT_GET_SECRETS_FLAGS" value-prefix="NM_SECRET_AGENT_GET_SECRETS_FLAG" type="u">
 126           <annotation name="org.gtk.GDBus.DocString" value="
 127             Flags modifying the behavior of GetSecrets request.
 128           " />
 129           <tp:flag suffix="NONE" value="0x0">
 130             <annotation name="org.gtk.GDBus.DocString" value="
 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.
 134             " />
 135           </tp:flag>
 136           <tp:flag suffix="ALLOW_INTERACTION" value="0x1">
 137             <annotation name="org.gtk.GDBus.DocString" value="
 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
 140               persistent storage.
 141             " />
 142           </tp:flag>
 143           <tp:flag suffix="REQUEST_NEW" value="0x2">
 144             <annotation name="org.gtk.GDBus.DocString" value="
 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.
 148             " />
 149           </tp:flag>
 150           <tp:flag suffix="USER_REQUESTED" value="0x4">
 151             <annotation name="org.gtk.GDBus.DocString" value="
 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
 155               carrier changes.
 156             " />
 157           </tp:flag>
 158         </tp:flags>
 159
 160         <method name="CancelGetSecrets">
 161             <annotation name="org.gtk.GDBus.DocString" value="
 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.
 166             " />
 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">
 170                 <annotation name="org.gtk.GDBus.DocString" value="
 171                     Object path of the connection for which, if secrets for
 172                     the given 'setting_name' are being requested, the request
 173                     should be canceled.
 174                 " />
 175             </arg>
 176             <arg name="setting_name" type="s" direction="in">
 177                 <annotation name="org.gtk.GDBus.DocString" value="
 178                     Setting name for which secrets for this connection were
 179                     originally being requested.
 180                 " />
 181             </arg>
 182         </method>
 183
 184         <method name="SaveSecrets">
 185             <annotation name="org.gtk.GDBus.DocString" value="
 186                 Save given secrets to backing storage.
 187             " />
 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">
 191                 <annotation name="org.gtk.GDBus.DocString" value="
 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.
 198                 " />
 199             </arg>
 200             <arg name="connection_path" type="o" direction="in">
 201                 <annotation name="org.gtk.GDBus.DocString" value="
 202                     Object path of the connection for which the agent should
 203                     save secrets to backing storage.
 204                 " />
 205             </arg>
 206         </method>
 207
 208         <method name="DeleteSecrets">
 209             <annotation name="org.gtk.GDBus.DocString" value="
 210                 Delete secrets from backing storage.
 211             " />
 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">
 215                 <annotation name="org.gtk.GDBus.DocString" value="
 216                     Nested settings maps containing the connection properties
 217                     (sans secrets), for which the agent should delete the
 218                     secrets from backing storage.
 219                 " />
 220             </arg>
 221             <arg name="connection_path" type="o" direction="in">
 222                 <annotation name="org.gtk.GDBus.DocString" value="
 223                     Object path of the connection for which the agent should
 224                     delete secrets from backing storage.
 225                 " />
 226             </arg>
 227         </method>
 228
 229         <tp:flags name="NM_SECRET_AGENT_CAPABILITIES" value-prefix="NM_SECRET_AGENT_CAPABILITY" type="u">
 230             <tp:flag suffix="NONE" value="0x0">
 231                 <annotation name="org.gtk.GDBus.DocString" value="No special capabilities." />
 232             </tp:flag>
 233             <tp:flag suffix="VPN_HINTS" value="0x1">
 234                 <annotation name="org.gtk.GDBus.DocString" value="
 235                     The agent supports passing hints to VPN plugin authentication
 236                     dialogs.
 237                 " />
 238             </tp:flag>
 239         </tp:flags>
 240
 241     </interface>
 242
 243 </node>