// 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.hardware.block.encrypted;

using zx;

/// We require simple layout to use the simple C bindings, and simple layout
/// requires that we have non-maximal length bounds, so give some excessively
/// large key length here so we can use the simple layout.
const MAX_KEY_SIZE uint32 = 256;

/// An interface to the zxcrypt driver, as bound to a single block device with
/// a zxcrypt superblock.  zxcrypt devices are encrypted, and before their
/// plaintext contents can be accessed, they must be unsealed with a key.
/// This protocol allows the caller to make requests to unseal the device (by
/// providing the appropriate key) and to seal the device (rendering its
/// contents inaccessible).
closed protocol DeviceManager {
    /// Formats the device, destroying any previously-secured data.  A new data
    /// key is generated and wrapped with the provided `key` into key slot `slot`,
    /// Returns `ZX_ERR_BAD_STATE` if the device is not currently sealed.
    /// Returns `ZX_OK` on success.
    strict Format(struct {
        key vector<uint8>:MAX_KEY_SIZE;
        slot uint8;
    }) -> (struct {
        status zx.Status;
    });

    /// Attempts to unseal the device by using the provided master key to unwrap
    /// the data key wrapped in the specified key slot.  If the key provided was
    /// the correct key for this slot, then the device node responding to this
    /// protocol will create an unsealed zxcrypt device as a child of itself in
    /// the device tree before returning success.
    /// Returns `ZX_ERR_INVALID_ARGS` if `slot` is invalid.
    /// Returns `ZX_ERR_BAD_STATE` and keeps the device open if the device is already unsealed.
    /// Returns other errors if operations on the underlying block device return errors.
    /// Returns `ZX_OK` on success.
    strict Unseal(struct {
        key vector<uint8>:MAX_KEY_SIZE;
        slot uint8;
    }) -> (struct {
        status zx.Status;
    });

    /// Seals the device, causing any previously-created child zxcrypt Device to
    /// be removed some time later.  (Someday we'd like this to only return once
    /// the unsealed child device is removed, but that's not straightforward today.)
    /// Returns `ZX_ERR_BAD_STATE` if the device is already sealed.
    /// Returns `ZX_OK` on success.
    strict Seal() -> (struct {
        status zx.Status;
    });

    /// Shreds the device, permanently overwriting the keys that would allow
    /// `Unseal()`ing the device again in the future.  This call does *not*
    /// impact the current sealed/unsealed state of the device -- if currently
    /// unsealed, the device will remain in that state until `Seal()` is called
    /// or the device is unbound.
    /// Returns `ZX_OK` on success.
    /// Returns other errors if operations on the underlying block device return errors.
    strict Shred() -> (struct {
        status zx.Status;
    });
};