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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
.TH LIBRECRYPT_MAKE_SETTINGS 3 LIBRECRYPT
.SH NAME
librecrypt_make_settings - Generate a password hash settings string
.SH SYNOPSIS
.nf
#include <librecrypt.h>
ssize_t \fBlibrecrypt_make_settings\fP(char *\fIout_buffer\fP, size_t \fIsize\fP, const char *\fIalgorithm\fP,
size_t \fImemcost\fP, uintmax_t \fItimecost\fP, int \fIgensalt\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_make_settings ()
function generates a password hash setting string
and writes it to
.IR out_buffer .
.PP
If
.I algorithm
is
.IR NULL ,
a default strong algorithm is selected.
The empty string selects the deprecated DES algorithm.
Algorithm chains are disallowed for this function.
.PP
The
.I memcost
parameter specifies an approximate memory cost in bytes.
A default value is selected if 0 is specified.
.PP
The
.I timecost
parameter specifies a total time cost in an
implementation-dependent, monotonic unit.
A default value is selected if 0 is specified.
.PP
If
.I gensalt
is non-zero, random salts are included in the
generated output, otherwise the output will only
specify the sizes the salts shall have.
.PP
If
.I gensalt
is non-zero,
.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
.I 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
.IR *rng
for user-defined purposes.
.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 (cannot happen if
.I gensalt
is zero); 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 below.
.SH RETURN VALUES
The
.BR librecrypt_make_settings ()
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 and
.I errno
is set to describe the error.
.SH ERRORS
The
.BR librecrypt_make_settings ()
function will fail if:
.TP
.B EINVAL
.I algorithm
represents a chain of algorithms.
.TP
.B ENOSYS
.I algorithm
represents an algorithm that is not recognised or
was disabled at compile-time.
.TP
.B ENOSYS
.I algorithm
is
.IR NULL
but all algorithms were disabled at compile-time.
.PP
Additionally, unless
.I rng
is
.IR NULL ,
.I *rng
may set
.I errno
(if
.I gensalt
is non-zero).
.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_make_settings ()
T} Thread safety MT-Safe
T{
.BR librecrypt_make_settings ()
T} Async-signal safety AS-Unsafe
.TE
.sp
.PP
If
.I gensalt
is non-zero and
.I rng
is
.RI non- NULL ,
.I *rng
may weaken the safety attributes.
.SH HISTORY
The
.BR librecrypt_make_settings ()
function was introduced in version 1.0 of
.BR librecrypt .
.SH SEE ALSO
.BR librecrypt (7),
.BR librecrypt_realise_salts (3)
|
