<?xml version="1.0"?>
<!--
 Copyright (C) 2019 Red Hat, Inc.

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public
 License along with this library. If not, see <http://www.gnu.org/licenses/>.

 Author: Daiki Ueno <dueno@redhat.com>
-->

<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
  <!--
      org.freedesktop.portal.Secret:
      @short_description: Portal for retrieving application secret

      The Secret portal allows sandboxed applications to retrieve a
      per-application secret.  The secret can then be used for
      encrypting confidential data inside the sandbox.

      This documentation describes version 1 of this interface.
  -->
  <interface name="org.freedesktop.portal.Secret">

    <!--
        RetrieveSecret:
        @fd: Writable file descriptor for transporting the secret
        @options: Vardict with optional further information
        @handle: Object path for the #org.freedesktop.portal.Request object representing this call

        Retrieves a master secret for a sandboxed application.

        The master secret is unique per application and does not
        change as long as the application is installed (once it has
        been created). In a typical backend implementation, it is
        stored in the user's keyring, under the application ID as a
        key.

        While the master secret can be used for encrypting any
        confidential data in the sandbox, the format is opaque to the
        application. In particular, the length of the secret might not
        be sufficient for the use with certain encryption
        algorithm. In that case, the application is supposed to expand
        it using a KDF algorithm.

        The portal may return an additional identifier associated with
        the secret in the results vardict of
        org.freedesktop.portal.Request.Response() call. In the next
        call of this method, the application shall indicate it through
        a token element in @options.

        Supported keys in the @options vardict include:
        <variablelist>
          <varlistentry>
            <term>token s</term>
            <listitem><para>
              An opaque string returned by a previous org.freedesktop.portal.Secret.RetrieveSecret() call.
            </para></listitem>
          </varlistentry>
        </variablelist>
    -->
    <method name="RetrieveSecret">
      <annotation name="org.gtk.GDBus.C.Name" value="retrieve_secret"/>
      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
      <arg type="h" name="fd" direction="in"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="handle" direction="out"/>
    </method>
    <property name="version" type="u" access="read"/>
  </interface>
</node>