PROTOCOLS
DeviceManager
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
An interface to the block-verified driver, as bound to a single block
device with a block-verified-formatted superblock. When bound, the device
starts out in closed
mode. Before use, block-verified devices must first
be placed into either authoring
mode, by calling OpenForWrite
, or into
verified-read
mode, by calling OpenForVerifiedRead
.
This protocol allows the caller to make requests to open the device in
either mode, as well as a way to seal a device and receive a cryptographic
representation of the contents of the device which, if presented to
OpenForVerifiedRead
, ensures any contents read from the verified
child
device will match those last written while in authoring
mode.
Close
Requests that the device in either authoring
mode or verified-read
mode
unbind any child devices and return to closed
mode.
Returns ZX_ERR_BAD_STATE
if the device is not in authoring
or
verified-read
mode at the time of the call.
On success, the device does the following:
- If the device was in
authoring
mode, removes the childmutable
device - If the device was in
verified-read
mode, removes the childverified
device - Enters
closed
mode. - Returns from this call
Request
Name | Type |
---|
Response
Name | Type |
---|---|
result |
DeviceManager_Close_Result
|
CloseAndGenerateSeal
Requests that the device in authoring
mode:
- unbind the child device named
mutable
- regenerate the integrity data necessary to provide the guarantees
expected by
OpenForVerifiedRead
- flush all writes to the underlying block device
- switch to
closed
mode - return a
Seal
that can be used to ensure that any data read in the future from this device matches that which was written prior to this particular call ofCloseAndGenerateSeal
.
If the device was not in "authoring" mode at the time of the call, this
function will return ZX_ERR_BAD_STATE
and have no visible side effects.
If the underlying block device returns a failure while regenerating
integrity data or flushing writes, the device will enter the failed
mode
and this call will propagate that error.
On success, the returned seal
will contain a hash of the device
superblock that should be stored in tamper-proof storage, so it can be
retrieved and presented in a future OpenForVerifiedRead
call.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
result |
DeviceManager_CloseAndGenerateSeal_Result
|
OpenForVerifiedRead
Requests that the device verify that the provided config
matches the
one on disk, and that the given seal
covers the content of the
superblock. If all match as expected, then the device will bind a child
device named verified
which speaks the fuchsia.hardware.block
protocol and enter the verified-read
mode. Reads issued to the
verified
block device will either successfully return the same content
as the mutable
block device would have returned at the time the volume
was authored, or return a failure. That is to say: modifying the
underlying storage will cause the verified
device to return read
failures for any modified blocks as ZX_ERR_IO_DATA_INTEGRITY
rather
than data other than what was present at the time CloseAndGenerateSeal
was called.
- Returns
ZX_ERR_BAD_STATE
if the device was not in theclosed
state at the time of the call - Returns
ZX_ERR_INVALID_ARGS
ifconfig
lacks eitherhash_function
orblock_size
- Returns
ZX_ERR_INVALID_ARGS
ifseal
is of an unrecognized variant - Returns
ZX_ERR_IO_DATA_INTEGRITY
if theseal
provided is inconsistent with the superblock, or if the properties inconfig
are inconsistent with the configuration data stored in the superblock on the underlying block device. - Returns the underlying I/O error code if the underlying block device returns an error.
On success, the device binds a child device verified
, enters
verified-read
mode, and returns from this call.
Request
Name | Type |
---|---|
config |
Config
|
seal |
Seal
|
Response
Name | Type |
---|---|
result |
DeviceManager_OpenForVerifiedRead_Result
|
OpenForWrite
Requests that the driver format the underlying block device as described
by the parameters in config
, and enter authoring
mode.
If config
has any unpopulated fields, or those fields contain enum
values that are not known to this version of the driver, this method
will return ZX_ERR_INVALID_ARGS
.
If the device was not in closed
mode at the time of the call, this
method will return ZX_ERR_BAD_STATE
.
If the underlying block device returns an error, this method will return
that same error code.
On success, the driver will enter authoring
mode, expose a child
device named mutable
which speaks the fuchsia.hardware.block
protocol in the device tree, then return.
Request
Name | Type |
---|---|
config |
Config
|
Response
Name | Type |
---|---|
result |
DeviceManager_OpenForWrite_Result
|
STRUCTS
DeviceManager_CloseAndGenerateSeal_Response
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Name | Type | Description | Default |
---|---|---|---|
seal |
Seal
|
No default |
DeviceManager_Close_Response
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Name | Type | Description | Default |
---|
DeviceManager_OpenForVerifiedRead_Response
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Name | Type | Description | Default |
---|
DeviceManager_OpenForWrite_Response
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Name | Type | Description | Default |
---|
Sha256Seal
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
A cryptographic seal of the superblock generated with the SHA256 hash function
Name | Type | Description | Default |
---|---|---|---|
superblock_hash |
uint8[32]
|
SHA256 hash of superblock |
No default |
ENUMS
BlockSize
Type: uint8
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
The block size this device is expected to see in its backing storage, which impacts hash tree layout and total available data size. At present, the only supported block size is blocks of 4096 bytes.
Name | Value | Description |
---|---|---|
SIZE_4096 |
1 |
Blocks of 4096 bytes each |
HashFunction
Type: uint8
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Hash function to use in the Merkle tree that verifies content. At present, the only supported value for this field is SHA256.
Name | Value | Description |
---|---|---|
SHA256 |
1 |
TABLES
Config
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Properties of the device that must be decided upon in advance by the client.
A Config must be presented to the device whenver the user wants to open it
in any mode.
block_size
affects how much or little data we authenticate as a unit, which
affects the number of hashes that fit into a block, which affects the
number of blocks needed to store integrity information, which affects overall
on-disk layout.
Ordinal | Name | Type | Description |
---|---|---|---|
1 | hash_function |
HashFunction
|
Which hash function to use throughout the Merkle tree and when generating a Seal over the superblock. |
2 | block_size |
BlockSize
|
Size of each block in the Merkle tree. |
UNIONS
DeviceManager_CloseAndGenerateSeal_Result
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Name | Type | Description |
---|---|---|
response |
DeviceManager_CloseAndGenerateSeal_Response
|
|
err |
zx/status
|
DeviceManager_Close_Result
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Name | Type | Description |
---|---|---|
response |
DeviceManager_Close_Response
|
|
err |
zx/status
|
DeviceManager_OpenForVerifiedRead_Result
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Name | Type | Description |
---|---|---|
response |
DeviceManager_OpenForVerifiedRead_Response
|
|
err |
zx/status
|
DeviceManager_OpenForWrite_Result
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Name | Type | Description |
---|---|---|
response |
DeviceManager_OpenForWrite_Response
|
|
err |
zx/status
|
Seal
Defined in fuchsia.hardware.block.verified/devicemanager.fidl
Data representing a cryptographic seal of the contents of the device. This currently contains the hash of the superblock, and the superblock contains the expected dimensions of the device and the root hash of the integrity information Merkle tree
Name | Type | Description |
---|---|---|
sha256 |
Sha256Seal
|