blob: 7473ae137e62afe9704457c6951ddcc9a69dc7d2 [file] [log] [blame]
// 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;
});
};