<?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.
        </tp:docstring>

        <method name="GetSecrets">
            <tp:docstring>
                Retrieve and return stored secrets, if any, or request new
                secrets from the agent's user.
            </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. 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>
        </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 matching 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 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>

    </interface>

</node>
