Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / shldata-rw.h / shldata_write.3.md 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
% limb manual
% shldata_write(3)
% limb 0.2.0
% 2024-01-09

# NAME

shldata\_write, shldata\_read, shldata\_chkmagic - write/read shielded data
files

# SYNOPSIS

    #include <limb/shldata-rw.h>

```pre hl
int shldata_chkmagic(u32 <em>magic</em>)

int shldata_write(int <em>bfd</em>, const char *<em>file</em>, u32 <em>magic</em>, u64 <em>ver</em>,
                  const char *<em>pwd</em>, size_t <em>plen</em>, unsigned <em>algo</em>, unsigned <em>iter</em>,
                  int <em>inplace</em>, const struct iovec <em>v</em>[], unsigned <em>n</em>)
int shldata_read(u32 *<em>magic</em>, u64 *<em>ver</em>, unsigned *<em>algo</em>, unsigned *<em>iter</em>, stralloc *<em>sa</em>,
                 int <em>bfd</em>, const char *<em>file</em>, const char *<em>pwd</em>, size_t <em>plen</em>)
```

# 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`.

! INFO:
! 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).