Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / shldata.h / shldata_initr.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
% limb manual
% shldata_initr(3)
% limb 0.2.0
% 2024-01-09

# NAME

shldata_initr, shldata_datasize, shldata_decrypt, shldata_finalr - decrypt
data using the shielded data protocol

# SYNOPSIS

    #include <limb/shldata.h>

```pre hl
ssize_t shldata_initr(const char *<em>sce</em>, size_t <em>slen</em>, const char *<em>pwd</em>, size_t <em>plen</em>, unsigned *<em>algo</em>, unsigned *<em>iter</em>, shldata_ctx *<em>ctx</em>)
size_t shldata_datasize(shldata_ctx *<em>ctx</em>)
int shldata_decrypt(char *<em>dst</em>, const char *<em>sce</em>, size_t <em>len</em>, shldata_ctx *<em>ctx</em>)
ssize_t shldata_finalr(const char *<em>sce</em>, size_t <em>slen</em>, shldata_ctx *<em>ctx</em>)
```

# DESCRIPTION

All those functions are used to read & decrypt data protected with a
user-supplied password using the shielded data protocol, as described in
[shldata](5).

First, the `shldata_initr`() function will read the memory pointed by `sce` (up
to a maximum of `slen` bytes) for derivation parameters. The algorithm and
number of iterations used will be stored in the variables pointed to by `algo`
and `iter` respectively.
Then it will derive a secret key from the password pointed by `pwd` of length
`plen` and initialize the opaque structure pointed by `ctx`.

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

The `shldata_decrypt`() function can then be used to decrypt data pointed by
`sce` of length `slen` into the memory pointed by `dst` (which must be able to
store at least `slen` bytes), using the specified `ctx`.

As with [ccpl_decrypt](3) it is possible to use the same memory area for both
`sce` and `dst`, and have it processed in-place.

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

Lastly, the `shldata_finalr`() function will read the memory pointed by `sce`
(up to a maximum of `slen` bytes) to authenticate both the derivation parameters
used during `shldata_initr`() and the encrypted data.

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_initr`(), and `shldata_finalr`() functions return the number of
bytes read and processed from `sce` on success. Otherwise they return -1 and set
`errno` to indicate the error.

For `shldata_initr`() this obviously means the offset at which encrypted data
begins in `sce`.

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

The `shldata_decrypt`() 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 decrypted is larger than the amount of encrypted data, which should
never happen.

# ERRORS

The `shldata_initr`() and `shldata_finalr`() functions may fail if :

: *EINVAL*
:: The memory pointed by `sce` contains invalid data.

: *ENODATA*
:: There is not enough data available in `sce`.

The `shldata_finalr`() function may fail if :

: *EINVAL*
:: The amount of data decrypted is different from the amount of encrypted data.

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

# SEE ALSO

[shldata_initw](3)