NAME
shldata_write, shldata_read, shldata_chkmagic - write/read shielded data files
SYNOPSIS
#include <limb/shldata-rw.h>
int shldata_chkmagic(u32 magic)
int shldata_write(int bfd, const char *file, u32 magic, u64 ver,
const char *pwd, size_t plen, unsigned algo, unsigned iter,
int inplace, const struct iovec v[], unsigned n)
int shldata_read(u32 *magic, u64 *ver, unsigned *algo, unsigned *iter, stralloc *sa,
int bfd, const char *file, const char *pwd, size_t plen)
DESCRIPTION
The shldata_chkmagic() function returns whether or not magic is a valid
magic constant for a shielded data file, as per shldata(5).
The shldata_write() function will write to file the shielded data consisting
of the data pointed by the array v of n struct iovec, encrypted using a
key derived via PBKDF2 from the password pointed by pwd of length plen and
algorithm algo and iter iterations.
When file specifies a relative path, file written is then determined relative
to the directory associated with the file descriptor bfd.
If passed the special value AT_FDCWD in the bfd parameter, the current
working directory is used.
The file will first have the magic magic and version number ver written out
as header, then all derivation parameters, encrypted data and authentication
code as needed, in patrim(5) format.
If inplace is non-zero, data will first be encrypted in-place before being
written out, otherwise memory will be allocated as needed.
The shldata_read() function will read the file - which must be a shielded
data file. Its magic number will be put as value pointed by magic and its
version number put as value pointed by ver.
When file specifies a relative path, file written is then determined relative
to the directory associated with the file descriptor bfd.
If passed the special value AT_FDCWD in the bfd parameter, the current
working directory is used.
If the magic is valid, parameters will read; The algorithm and iterations number
used for key derivation will be put as value pointed by algo and iter
respectively, and used with the password pointed by pwd of length plen to
derive the encryption key. The decrypted data will be placed into the stralloc
pointed by sa.
It is possible to set the value pointed to by magic to the expected magic
from the file. shldata_read() will check the value before reading the file,
and if it was set to a valid magic (as per shldata_chkmagic()) instead of
just checking the magic from the file is valid, it will check that it matches
the expected value.
RETURN VALUE
The shldata_chkmagic() function returns 1 is magic is a valid shielded data
magic number, otherwise it returns zero and sets errno to EINVAL.
The shldata_write() and shldata_read() functions return 1 on success.
Otherwise they return 0 and set errno to indicate the error.
ERRORS
The shldata_write() and shldta_read() functions may fail if :
EINVAL
The magic number (given in magic or read from file, respectively) isn't
a valid magic for a shielded data file (or doesn't match the expected magic).
ENOMEM
Out of memory.
The shldata_write() function may also fail if :
EINVAL
The value of algo or iter is invalid.
The shldata_write() function may also fail for the errors described for
open_exclat(3) save for EEXIST, buffer_putv(3), buffer_put(3),
buffer_flush(3) and renameat(3).
The shldata_read() function may also fail if :
EPIPE
Not enough data could be read from file (e.g: file truncated)
EINVAL
Invalid data read from file.
EBADMSG
Authentication of the message (derivation parameters and encrypted data) failed. (This could be caused by a wrong password being used.)
The shldata_read() function may also fail for the errors described for
open_readat(3), buffer_get(3) and buffer_fill(3).