// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.identity.transfer;

using fuchsia.identity.account;
using fuchsia.kms;

/// The control protocol used by two AccountManager components on different
/// devices to exchange information.
///
/// Note: this is a sensitive interface and connections should only be created
/// between AccountManagers on remotely attested devices.  No components on
/// the same device should connect over this protocol.
[Discoverable]
protocol AccountManagerPeer {
    /// Requests an account transfer.
    /// `lifetime` The lifetime that the transferred account should have
    ///   on the target device.
    /// `account_transfer` The server end of an `AccountTransfer` channel.
    ReceiveAccount(fuchsia.identity.account.Lifetime lifetime,
                   request<AccountTransfer> account_transfer);
};

/// The control channel through which AccountManager components on different
/// devices communicate to execute an account transfer.
///
/// When an account needs to be transferred, the source device should request
/// an `AccountTransfer` connection using the `ReceiveAccount` method on the
/// `AccountManagerPeer` exposed by the target device.
/// Once the target device is ready, it sends an `OnTransferReady` containing
/// a `target_key`.
/// The source device should then encrypt the account using the `target_key`
/// and complete the transfer with `CompleteAccountTransfer`.
/// Once the account transfer is complete, the channel is closed.
protocol AccountTransfer {

    /// This event is sent once by the target device when it has completed
    /// preparing to receive an account.  The event contains a `target_key`
    /// which should be used to encrypt the account data sent through
    /// `CompleteAccountTransfer`.
    -> OnTransferReady(fuchsia.kms.PublicKey target_key);

    /// Completes the account transfer by sending the transfered data.
    /// The data is opaque to the AccountManager binary, and should be
    /// supplied and encrypted by the account handler on the source device
    /// using the `target_key` received through `OnTransferReady`.
    ///
    /// If the account is already present on the target device this fails
    /// with UNSUPPORTED_OPERATION.
    CompleteAccountTransfer(bytes encrypted_account_data)
        -> () error fuchsia.identity.account.Error;
};