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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
.TH LIBRECRYPT_REALISE_SALTS 3 LIBRECRYPT
.SH NAME
librecrypt_realise_salts - Realise asterisk-encoded random salts in a settings string
.SH SYNOPSIS
.nf
#include <librecrypt.h>
ssize_t \fBlibrecrypt_realise_salts\fP(char *restrict \fIout_buffer\fP, size_t \fIsize\fP, const char *\fIsettings\fP,
ssize_t (*\fIrng\fP)(void *\fIout\fP, size_t \fIn\fP, void *\fIuser\fP), void *\fIuser\fP);
.fi
.PP
Link with
.IR -lrecrypt .
Static linking may require additional flags
depending on enabled hash algorithms.
.SH DESCRIPTION
The
.BR librecrypt_realise_salts ()
function locates all asterisks followed by a
non-negative decimal number in
.IR settings
and replaces each with ASCII-encoded random
bytes (as many bytes as the number specifies),
writing the result to
.IR out_buffer .
.PP
.IR *rng ,
or a default implementation (which tries to use
cryptographic random number generation but has
a non-cryptographic random number generation as
a last resort) if
.I rng
is
.IR NULL ,
used to generate random bytes.
.I *rng
shall fill out with at least 1, and up to
.IR n ,
random bytes, and return the number of bytes
written, or return -1 on failure.
.PP
The
.I data
argument is passed into the
.IR *rng -parameter
with the same name, as is and may be used by
.I *rng
for user-defined purposes.
.PP
If
.I rng
is
.IR NULL ,
a default cryptographic random number generator
is used. The
.I *rng
function shall generate between 1 and
.I n
bytes (inclusively), write them to the front of
.IR out ,
and return the number of generated bytes, or
-1 on failure.
.PP
On successful completion, if
.I size
is positive, the output is
null byte-terminated even if truncated.
.PP
If
.I rng
is
.IR NULL ,
any encountered
.BR EINTR
is ignored; if it is encountered,
.I errno
will be set to
.BR EINTR ,
but is otherwise left unmodified unless the
function fails due to one of the
errors listed in the
.B ERRORS
section.
.PP
.I settings
must not be
.IR NULL .
.SH RETURN VALUES
The
.BR librecrypt_realise_salts ()
function returns the number of bytes that
would have been written to
.IR out_buffer
if
.I size
was sufficiently large, or -1 on failure.
.SH ERRORS
The
.BR librecrypt_realise_salts ()
function will fail if:
.TP
.B ERANGE
The expected return value is greater than {SSIZE_MAX}.
.TP
.B EINVAL
Asterisk-encoding was used in an invalid context.
.TP
.B ENOSYS
.I settings
contain an algorithm that is not recognised or was
disabled at compile-time.
.PP
Additionally, unless
.I rng
is
.IR NULL ,
.I *rng
may set
.IR errno .
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.PP
.TS
allbox;
lb lb lb
l l l.
Interface Attribute Value
T{
.BR librecrypt_realise_salts ()
T} Thread safety MT-Safe
T{
.BR librecrypt_realise_salts ()
T} Async-signal safety T{
AS-Safe /\fIrng\fP
.br
AS-Unsafe /\fI!rng\fP
T}
.TE
.sp
.PP
.I rng
is
.RI non- NULL ,
.I *rng
may weaken the safety attributes.
.SH HISTORY
The
.BR librecrypt_realise_salts ()
function was introduced in version 1.0 of
.BR librecrypt .
.SH SEE ALSO
.BR librecrypt (7),
.BR librecrypt_make_settings (3)
|
