blob: 788f6707ed8b45d4f276ca0ed4e54670b8d24aba [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 uint32 MAX_KEY_SIZE = 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).
protocol DeviceManager {
/// 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.
Unseal(bytes:MAX_KEY_SIZE key, uint8 slot) -> (zx.status 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.
Seal() -> (zx.status 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.
Shred() -> (zx.status status);