Struct nuts_container::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( backend_options: B::CreateOptions, 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 Backend::CreateOptions 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 open( backend_options: B::OpenOptions, 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 Backend::OpenOptions 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 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 userdata(&self) -> &[u8]

Returns userdata assigned to the container.

Userdata are arbitrary data stored in the (encrypted) header of the container. It can be used by a service running on top of a nuts container to store information about the service itself.

pub fn update_userdata(&mut self, userdata: &[u8]) -> ContainerResult<(), B>

Updates the userdata.

Assigns a new set of new userdata to the container; any previous userdata are overwritten.

Errors

Errors are listed in the Error type.

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 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.

Trait Implementations

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

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

Formats the value using the given formatter.