Struct Container

pub struct Container<B: Backend> { /* private fields */ }

The Container type.

A Container acts like an encrypted block device, where you can read and write encrypted blocks of data.

To create a new container use the Container::create method. You can open an existing container with the Container::open method. With the Container::read and Container::write methods you can read data from the container resp. write data into the container.

Implementations

impl<B: Backend> Container<B>

pub fn create<C: Create<B>>( backend_options: C, options: CreateOptions, ) -> ContainerResult<Container<B>, B>

Creates a new container.

This method expects two arguments:

1. backend_options, which is a type that implements the Create trait. It acts as a builder for a concrete Backend instance.
2. options, which is a builder of this Container. A CreateOptions instance can be created with the CreateOptionsBuilder utility.

If encryption is turned on, you will be asked for a password over the password callback. The returned password is then used for encryption of the secure part of the header.

The header with the (possibly encrypted) secret is created and passed to the Backend. The header contains all information you need to open the container again.

Errors

Errors are listed in the Error type.

pub fn create_service<F: ServiceFactory<B>>( container: Container<B>, ) -> Result<F::Service, F::Err>

Creates a service running on top of the given container.

Basically, this method performs the following tasks:

1. The super-block is created, if requested by the service.
2. Uses ServiceFactory::create to create and return the service instance.

This should be the preferred way to create a nuts-service!

pub fn open<O: Open<B>>( backend_options: O, options: OpenOptions, ) -> ContainerResult<Container<B>, B>

Opens an existing container.

This method expects two arguments:

1. backend_options, which is a type that implements the Open trait. It acts as a builder for a concrete Backend instance.
2. options, which is a builder of this Container. A OpenOptions instance can be created with the OpenOptionsBuilder utility.

If encryption is turned on for the container, you will be asked for a password over the password callback. The returned password is then used to decrypt the secure part of the header.

Errors

Errors are listed in the Error type.

pub fn open_service<F: ServiceFactory<B>>( container: Container<B>, migrate: bool, ) -> Result<F::Service, F::Err>

Opens a service running on top of an existing container.

Basically, this method uses ServiceFactory::open to open and return the service instance.

This should be the preferred way to open a nuts-service!

pub fn backend(&self) -> &B

Returns the backend of this container.

pub fn into_backend(self) -> B

Consumes this container, returning the inner backend.

pub fn info(&self) -> ContainerResult<Info<B>, B>

Returns information from the container.

Errors

Errors are listed in the Error type.

pub fn top_id(&self) -> Option<&B::Id>

Returns the top-id of the container.

A service (running on top of the container) can use the top-id as a starting point or some kind of super-block. The top-id is stored encrypted in the header of the container. Calling this method will neither fetch nor create the top-id. It returns an entry, where you can decide what to do.

pub fn block_size(&self) -> u32

The (net) block size specifies the number of userdata bytes you can store in a block. It can be less than the gross block size specified by the backend!

Depending on the selected cipher, you need to store additional data in a block. I.e. an AE-cipher results into a tag, which needs to be stored additionally. Such data must be substracted from the gross block size and results into the net block size.

pub fn modify(&mut self, options: ModifyOptions) -> ContainerResult<(), B>

Modifies the container with the given options.

Use ModifyOptionsBuilder to create a ModifyOptions instance, which collects all modification tasks.

Errors

Errors are listed in the Error type.

pub fn aquire(&mut self) -> ContainerResult<B::Id, B>

Aquires a new block in the backend.

Once aquired you should be able to read and write from/to it.

By default an aquired block, which is not written yet, returns an all-zero buffer.

Returns the id of the block.

Errors

Errors are listed in the Error type.

pub fn release(&mut self, id: B::Id) -> ContainerResult<(), B>

Releases a block again.

A released block cannot be read and written, the id cannot be used afterwards.

Errors

Errors are listed in the Error type.

pub fn read(&mut self, id: &B::Id, buf: &mut [u8]) -> ContainerResult<usize, B>

Reads a block from the container.

Reads the block with the given id and places the decrypted data in buf.

You cannot read not more data than block-size bytes. If buf is larger, than not the whole buffer is filled. In the other direction, if buf is not large enough to store the whole block, buf is filled with the first buf.len() bytes.

The methods returns the number of bytes actually read, which cannot be greater than the block-size.

Errors

Errors are listed in the Error type.

pub fn write(&mut self, id: &B::Id, buf: &[u8]) -> ContainerResult<usize, B>

Writes a block into the container.

Encrypts the plain data from buf and writes the encrypted data into the block with the given id.

Writes up to buf.len() bytes from the unencrypted buf buffer into the container.

If buf is not large enough to fill the whole block, the destination block is automatically padded with all zeros.

If buf holds more data than the block-size, then the first block-size bytes are copied into the block.

The method returns the number of bytes actually written.

Errors

Errors are listed in the Error type.

pub fn delete(self)

Deletes the entire container and all traces.

The method must not fail!

Trait Implementations

impl<B: Debug + Backend> Debug for Container<B>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.