NAME
shldata_initw, shldata_encrypt, shldata_predata, shldata_finalw - encrypt data using the shielded data protocol
SYNOPSIS
#include <limb/shldata.h>
ssize_t shldata_initw(char *dst, size_t dlen, const char *pwd, size_t plen,
unsigned algo, unsigned iter, size_t len, shldata_ctx *ctx)
int shldata_encrypt(char *dst, const char *data, size_t dlen, shldata_ctx *ctx)
ssize_t shldata_predata(char *dst, size_t dlen, shldata_ctx *ctx)
ssize_t shldata_finalw(char *dst, size_t dlen, 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).
First, the shldata_initw() function must be called to both write into the
memory pointed by dst of length dlen bytes the necessary parameters that
will be needed for decryption, and to initialize the opaque structure pointed by
ctx 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 shldata_encrypt() function can then be used to encrypt data pointed by
data of length dlen into the memory pointed by dst (which must be able to
store at least dlen bytes), using the specified ctx.
As with ccpl_encrypt(3) it is possible to use the same memory area for both
data and dst, and have it processed in-place.
It is possible to call this function as many times as needed.
If the length of data to be encrypted was known and given to shldata_initw()
it is correct to write encrypted data right after the parameters written by
said function, and no call to shldata_predata() is required.
If, however, the length was not given (i.e. len was zero), one should
not write encrypted data yet, but hold them in memory somewhere. All data
to be encrypted must be encrypted through shldata_encrypt() (in as many
calls as needed), and only then a call to shldata_predata() must be done.
The shldata_predata() function will write into the memory pointed by dst of
length dlen additional data that must be written out after the output written
by shldata_initw() but before the encrypted data written by
shldata_encrypt().
This is because the length of encrypted data must be specified before the
actual data. This is also why specifying said length to shldata_initw() means
it will already have been written out then, and no call to shldata_predata()
is then required (though it is valid to call it anyways, but it will never write
anything).
Lastly, the shldata_finalw() function must be called, and will write into the
memory pointed by dst of length dlen the final additional data (i.e. the
message authentication code).
Once done, it is possible to re-use an opaque structure for a new processing of data. It is also allowed to to so more than once per shielded data file, as per shldata(5).
RETURN VALUE
The shldata_initw(), shldata_predata() and shldata_finalw() functions
return the number of bytes written into dst on success. Otherwise they return
-1 and set errno to indicate the error.
The shldata_encrypt() function returns 1 on success, 0 otherwise. It should
never fail, as the only possible reason for failure is that the amount of data
given to be encrypted is larger than that specified to shldata_initw(), which
should never happen.
ERRORS
The shldata_initw(), shldata_predata() and shldata_finalw() functions may
fail if :
ENOBUFS
There is not enough space in dst.
The shldata_initw() may fail if :
EINVAL
The value of algo or iter is invalid.
The shldata_predata() and shldata_finalw() function may fail if :
EINVAL
The length specified to shldata_initw() and the length of encrypted data
are different (which should never happen).