librecrypt/librecrypt_crypt.3 at master · maandree/librecrypt · GitHub

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
.TH LIBRECRYPT_CRYPT 3 LIBRECRYPT
.SH NAME
librecrypt_crypt - Compute password hash encoded in ASCII with settings prefix

.SH SYNOPSIS
.nf
#include <librecrypt.h>

ssize_t \fBlibrecrypt_crypt\fP(char *restrict \fIout_buffer\fP, size_t \fIsize\fP,
                         const char *\fIphrase\fP, size_t \fIlen\fP,
                         const char *\fIsettings\fP, LIBRECRYPT_CONTEXT *\fIctx\fP);
.fi
.PP
Link with
.IR -lrecrypt .
Static linking may require additional flags
depending on enabled hash algorithms.

.SH DESCRIPTION
The
.BR librecrypt_crypt ()
function computes the hash of a password.
The resulting hash is encoded with
.BR librecrypt_encode (3)
and the settings string is included in the front
of the output.
.PP
The password is provided in
.IR phrase
and can contain null bytes; its length is
specified, in bytes, by
.IR len .
.PP
The password hash configuration string is
provided in
.IR settings .
If
.I settings
contains a resulting hash, it is ignored.
.PP
The
.I ctx
parameter is used for providing library
configurations, see
.BR librecrypt_create_context (3)
for more information; used
.I NULL
for default configurations.
.PP
On successful completion, if
.I size
is positive, the output is
null byte-terminated even if truncated.
.PP
Any encountered
.BR EINTR
is ignored.
.PP
On failure,
.I out_buffer
may be partially written.
.PP
.I settings
must not be
.IR NULL .

.SH RETURN VALUES
The
.BR librecrypt_crypt ()
function returns the number of bytes that would
have been written to
.IR out_buffer
if
.I size
was sufficiently large, excluding the terminating
null byte. On failure, -1 is returned and
.I errno
is set to describe the error.

.SH ERRORS
The
.BR librecrypt_crypt ()
function will fail if:
.TP
.B EINVAL
.I settings
is invalid.
.TP
.B ERANGE
.I len
is too large or too small for the selected
initial algorithm.
.TP
.B EOVERFLOW
The expected return value is greater than {SSIZE_MAX}.
.TP
.B ENOMEM
Failed to allocate internal scratch memory.
.TP
.B ENOSYS
A selected hash algorithm is not recognised
or was disabled at compile-time.

.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_crypt ()
T}	Thread safety	MT-Safe
T{
.BR librecrypt_crypt ()
T}	Async-signal safety	AS-Unsafe
.TE
.sp

.SH HISTORY
The
.BR librecrypt_crypt ()
function was introduced in version 1.0 of
.BR librecrypt .

Since version 1.1 of the
.BR librecrypt_crypt ()
function, the
.I ctx
parameter (previously called
.IR reserved )
has the type
.B LIBRECRYPT_CONTEXT *
(previously
.BR "void *" ),
and setting it to
.RI non- NULL
no longer causes failure with
.I errno
set to
.IR EINVAL .

.SH SEE ALSO
.BR librecrypt (7),
.BR librecrypt_hash_binary (3),
.BR librecrypt_hash (3),
.BR librecrypt_verify (3),
.BR librecrypt_test_supported (3)