% limb manual
% buffer_shldata_putinit(3)
% limb 0.1.0
% 2023-07-24
# NAME
buffer\_shldata\_putinit, buffer\_shldata\_put, buffer\_shldata\_putfinal -
buffer\_shldata\_free - encrypt data using the shielded data protocol through
buffer interface
# SYNOPSIS
#include <limb/buffer-shldata.h>
```pre hl
ssize_t buffer_shldata_putinit(buffer *<em>buf</em>, const char *<em>pwd</em>, size_t <em>plen</em>, unsigned <em>algo</em>, unsigned <em>iter</em>,
size_t <em>len</em>, buffer_shldata_ctx *<em>ctx</em>)
ssize_t buffer_shldata_put(buffer *<em>buf</em>, char *<em>data</em>, size_t <em>dlen</em>, int <em>inplace</em>, buffer_shldata_ctx *<em>ctx</em>)
ssize_t buffer_shldata_putfinal(buffer *<em>buf</em>, buffer_shldata_ctx *<em>ctx</em>)
void buffer_shldata_free(buffer_shldata_ctx *<em>ctx</em>)
```
# DESCRIPTION
All those functions are used to protect data with a user-supplied password using
the shielded data protocol, as described in [shldata](5), through the
[buffer.h](0) interface.
First, the `buffer_shldata_putinit`() function must be called to both write to
the buffer pointed by `buf` the necessary parameters that will be needed for
decryption, and to prepare the opaque structure pointed by `ctx` (which must
have been initialized to *BUFFER_SHLDATA_ZERO*) in order to perform data
encryption.
Key derivation will be performed using PBKDF2 from the password pointed by `pwd`
of length `plen`, with the HMAC based on the algorithm indicated in `algo` -
which must be a valid index/constant as defined in [hasher.h](0) - and the
number of iterations indicated in `iter`.
It is recommended, if possible, to indicate the exact length of data to be
encrypted in `len`. It is however possible to use zero if not yet known.
The `buffer_shldata_put`() function can then be used to encrypt data pointed by
`data` of length `dlen` and write the encrypted data into the buffer pointed by
`buf`, using the specified `ctx`.
In `inplace` is non-zero the data might be encrypted in-place before being
written to the buffer, meaning that afterwards the memory pointed by `data` will
contain the /encrypted/ data. Otherwise, memory might be heap-allocated before
encrypting data.
! INFO:
! Note that even with `inplace` set to a non-zero value, the data might be
! encrypted elsewhere in memory, and stored to be written later on - i.e. during
! the call to `buffer_shldata_putfinal`(). This will happen if the length of
! data to encrypt wasn't specified to `buffer_shldata_init`().
! Refer to [shldata_initw](3) for more.
It is possible to call this function as many times as needed.
Then the `buffer_shldata_putfinal`() function must be called to write to the
buffer pointed by `buf` the final additional data (MAC). As described above, if
the length of the data to encrypt wasn't known/given to
`buffer_shldata_putinit`() then encrypted data will also be written then, before
the MAC.
Lastly, the `buffer_shldata_free`() function must be called to free memory
associated with the given `ctx`.
# RETURN VALUE
These functions (except `buffer_shldata_free`()) return the number of bytes
written to the buffer pointed by `buf` on success. Otherwise they return -1 and
set `errno` to indicate the error.
# ERRORS
The `buffer_shldata_putinit`() function may fail for any of the errors described
for [shldata_initw](3), save for *ENOBUFS*.
The `buffer_shldata_put`() and `buffer_shldata_putfinal`() functions may fail
if :
: *EINVAL*
:: The total amount of data given to encrypt was larger than that specified to
:: `buffer_shldata_putinit`().
The `buffer_shldata_put`() function may also fail if :
: *ENOMEM*
:: Out of memory.
The `buffer_shldata_put`() function may also fail for any of the errors
described for [buffer_put](3).
The `buffer_shldata_putfinal`() function may fail for any of the errors
described for [shldata_finalw](3), save for *ENOBUFS*, as well as any of the
errors described for [buffer_putv](3).
# SEE ALSO
[buffer_shldata_getinit](3), [shldata_initw](3)