% limb manual
% shldata_initw(3)
% limb 0.1.0
% 2023-07-24

# NAME

shldata\_initw, shldata\_encrypt, shldata\_predata, shldata\_finalw - encrypt
data using the shielded data protocol

# SYNOPSIS

    #include <limb/shldata.h>

```pre hl
ssize_t shldata_initw(char *<em>dst</em>, size_t <em>dlen</em>, const char *<em>pwd</em>, size_t <em>plen</em>,
                      unsigned <em>algo</em>, unsigned <em>iter</em>, size_t <em>len</em>, shldata_ctx *<em>ctx</em>)
int shldata_encrypt(char *<em>dst</em>, const char *<em>data</em>, size_t <em>dlen</em>, shldata_ctx *<em>ctx</em>)
ssize_t shldata_predata(char *<em>dst</em>, size_t <em>dlen</em>, shldata_ctx *<em>ctx</em>)
ssize_t shldata_finalw(char *<em>dst</em>, size_t <em>dlen</em>, 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).

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.

! INFO: Pay attention when to write data
! 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).

# SEE ALSO

[shldata_initr](3)