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>

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

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.

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 :

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 :

SEE ALSO

buffer_shldata_putinit(3), shldata_initr(3)