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>
ssize_t buffer_shldata_putinit(buffer *buf, const char *pwd, size_t plen, unsigned algo, unsigned iter,
size_t len, buffer_shldata_ctx *ctx)
ssize_t buffer_shldata_put(buffer *buf, char *data, size_t dlen, int inplace, buffer_shldata_ctx *ctx)
ssize_t buffer_shldata_putfinal(buffer *buf, buffer_shldata_ctx *ctx)
void buffer_shldata_free(buffer_shldata_ctx *ctx)
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.
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).