% limb manual
% buffer_shldata_getinit(3)
% limb 0.2.0
% 2024-01-09

# NAME

buffer\_shldata\_getinit\_sa, buffer\_shldata\_getinit, buffer\_shldata\_get,
buffer\_shldata\_getfinal\_sa, buffer\_shldata\_getfinal - decrypt data using
the shielded data protocol through buffer interface

# SYNOPSIS

    #include <limb/buffer-shldata.h>

```pre hl
int buffer_shldata_getinit_sa(buffer *<em>buf</em>, const char *<em>pwd</em>, size_t <em>plen</em>, unsigned *<em>algo</em>, unsigned *<em>iter</em>, stralloc *<em>sa</em>, buffer_shldata_ctx *<em>ctx</em>)
int buffer_shldata_getinit(buffer *<em>buf</em>, const char *<em>pwd</em>, size_t <em>plen</em>, unsigned *<em>algo</em>, unsigned *<em>iter</em>, buffer_shldata_ctx *<em>ctx</em>)
size_t buffer_shldata_datasize(buffer_shldata_ctx *<em>ctx</em>)
ssize_t buffer_shldata_get(buffer *<em>buf</em>, char *<em>dst</em>, size_t <em>dlen</em>, buffer_shldata_ctx *<em>ctx</em>)
int buffer_shldata_getfinal_sa(buffer *<em>buf</em>, stralloc *<em>sa</em>, buffer_shldata_ctx *<em>ctx</em>)
int buffer_shldata_getfinal(buffer *<em>buf</em>, buffer_shldata_ctx *<em>ctx</em>)
```

# DESCRIPTION

All those functions are used to read data through the [buffer.h](0) interface
and decrypt it with a user-supplied password, as per the shielded data protocol
described in [shldata](5).

The `buffer_shldata_getinit`() function reads data from the buffer pointed by
`buf` for derivation parameters, storing in the memory pointed to by `algo` and
`iter` the used algorithm and iterations number, respectively.
It then derives a secret key from the password pointed by `pwd` of length `plen`
and initializes the opaque structure pointed by `ctx` for decryption.

The `buffer_shldata_getinit_sa`() function is similar but using the *stralloc*
`sa` as head-allocated temporary space.

The `buffer_shldata_datasize`() macro returns the length of the encrypted data,
and therefore decrypted data.

The `buffer_shldata_get`() function will read `dlen` bytes of data from the
buffer pointed by `buf` and decrypt it into the memory pointed by `dst` (which
must be able to store at least `dlen` bytes).

It is possible to call this function as many times as needed.

! INFO:
! If trying to decrypt more than there is encrypted data (i.e. total amount
! requested to `buffer_shldata_get`() gets larger than the value returned by
! `buffer_shldata_datasize`()) only as much as there is left will be processed.

The `buffer_shldata_getfinal`() function will read data from the buffer pointed
by `buf` to authenticate both the derivation parameters used during
`buffer_shldata_getinit`() and the encrypted data.

Lastly, the [buffer_shldata_free](3) function must be called to free memory
associated with the given `ctx`.

# RETURN VALUE

The `buffer_shldata_getinit_sa`(), `buffer_shldata_getinit`(),
`buffer_shldata_getfinal_sa`() and `buffer_shldata_getfinal`() functions return
1 on success. Otherwise they return 0 and set `errno` to indicate the error.

The `buffer_shldata_datasize`() macro returns the length of the data to be
decrypted.

The `buffer_shldata_get`() function returns the length of data decrypted and
written into `dst`, which might be less than requested (even zero) if trying to
decrypt more than there is encrypted data.

# ERRORS

The `buffer_shldata_getinit_sa`(), `buffer_shldata_getinit`(),
`buffer_shldata_getfinal_sa`() and `buffer_shldata_getfinal`() functions may
fail if :

: *EINVAL*
:: Invalid data from the buffer.

: *ENOMEM*
:: Out of memory.

: *EPIPE*
:: Premature reach of end-of-file.

They may also fail for any of the errors described for [buffer_fill](3).

The `buffer_shldata_getfinal_sa`() and `buffer_shldata_getfinal`() functions may
also fail if :

: *EBADMSG*
:: Authentication of the message (derivation parameters and encrypted data)
:: failed. (This could be caused by a wrong password being used.)

# SEE ALSO

[buffer_shldata_putinit](3), [shldata_initr](3)