Struct Vmgs

pub struct Vmgs { /* private fields */ }

Implementation of the VMGS file format, backed by a generic Disk device.

Implementations

impl Vmgs

pub fn open_from_saved(disk: Disk, state: SavedVmgsState) -> Self

Construct a Vmgs instance, re-using existing saved-state from an earlier instance.

Safety

open_from_saved does NOT perform ANY validation on the provided state, and will blindly assume that it matches the underlying storage instance!

Callers MUST ensure that the provided state matches the provided storage, and that no external entities have modified storage between the call to save and open_from_saved.

Failing to do so may result in data corruption/loss, read/write failures, encryption errors, etc… (though, notably: it will not result in any memory-unsafety, hence why the function isn’t marked unsafe).

pub fn save(&self) -> SavedVmgsState

Save the in-memory Vmgs file metadata.

This saved state can be used alongside open_from_saved to obtain a new Vmgs instance without needing to invoke any IOs on the underlying storage.

impl Vmgs

pub async fn format_new(disk: Disk) -> Result<Self, Error>

Format and open a new VMGS file.

pub async fn open(disk: Disk) -> Result<Self, Error>

Open the VMGS file.

pub fn get_file_info(&self, file_id: FileId) -> Result<VmgsFileInfo, Error>

Get allocated and valid bytes from File Control Block for file_id.

When reading data from a file, the buffer must be at least valid_bytes long.

pub async fn read_file(&mut self, file_id: FileId) -> Result<Vec<u8>, Error>

Reads the specified file_id, decrypting its contents.

pub async fn read_file_raw(&mut self, file_id: FileId) -> Result<Vec<u8>, Error>

Reads the specified file_id, but does not decrypt the contents.

pub async fn write_file( &mut self, file_id: FileId, buf: &[u8], ) -> Result<(), Error>

Writes buf to a file_id without encrypting it.

If the file is already encrypted, this will return a failure. Use Self::write_file_allow_overwrite_encrypted if you want to allow this.

To write encrypted data, use write_file_encrypted instead.

pub async fn write_file_allow_overwrite_encrypted( &mut self, file_id: FileId, buf: &[u8], ) -> Result<(), Error>

Writes buf to a file_id without encrypting it, allowing overrites of an already-encrypted file.

pub async fn write_file_encrypted( &mut self, file_id: FileId, buf: &[u8], ) -> Result<(), Error>

Encrypts buf and writes the encrypted payload to a file_id if the VMGS file has encryption configured. If the VMGS doesn’t have encryption configured, will do a plaintext write instead.

pub async fn unlock_with_encryption_key( &mut self, encryption_key: &[u8], ) -> Result<usize, Error>

Decrypts the extended file table by the encryption_key and updates the related metadata in memory.

pub async fn add_new_encryption_key( &mut self, encryption_key: &[u8], encryption_algorithm: EncryptionAlgorithm, ) -> Result<usize, Error>

Associates a new root key with the data store. Returns the index of the newly associated key.

pub async fn remove_encryption_key( &mut self, key_index: usize, ) -> Result<(), Error>

Disassociates the root key at the specified index from the data store.

pub fn get_encryption_algorithm(&self) -> EncryptionAlgorithm

Gets the encryption algorithm of the VMGS

pub fn is_encrypted(&self) -> bool

Whether the VMGS file is encrypted

pub fn get_active_datastore_key_index(&self) -> Option<usize>

Get the active datastore key index

Trait Implementations

impl Inspect for Vmgs

fn inspect(&self, req: Request<'_>)

Inspects the object.