| // 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). |
| @for_deprecated_c_bindings |
| 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. |
| Format(struct { |
| key bytes: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. |
| Unseal(struct { |
| key bytes: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. |
| 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. |
| Shred() -> (struct { |
| status zx.status; |
| }); |
| }; |