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
|
.TH LIBRECRYPT_VERIFY 3 LIBRECRYPT
.SH NAME
librecrypt_verify - Verify password against known password hash
.SH SYNOPSIS
.nf
#include <librecrypt.h>
int \fBlibrecrypt_verify\fP(const char *\fIphrase\fP, size_t \fIlen\fP,
const char *\fIsettings\fP, void *\fIreserved\fP);
.fi
.PP
Link with
.IR -lrecrypt .
Static linking may require additional flags
depending on enabled hash algorithms.
.SH DESCRIPTION
The
.BR librecrypt_verify ()
function computes the hash of a password and compares
it against a provided hash.
.PP
The password is provided in
.IR phrase
and can contain null bytes; its length is specified by
.IR len .
.PP
The password hash configuration string is provided in
.IR settings ,
and shall include the hash result, that is, it shall
conform to the output of the
.BR librecrypt_crypt (3)
function. If
.I settings
contains a resulting hash, it is ignored.
If
.I settings
uses asterisk-encoding to specify random salts,
the function fails.
.PP
The
.I reserved
parameter is reserved for future use and should be
.IR NULL .
.PP
Any encountered
.BR EINTR
is ignored.
.PP
.I settings
must not be
.IR NULL .
.SH RETURN VALUES
The
.BR librecrypt_hash ()
function returns 1 if the hash of the input
password matches the provided hash, 0 otherwise.
On failure, -1 is returned and
.I errno
is set to describe the error.
.SH ERRORS
The
.BR librecrypt_verify ()
function will fail if:
.TP
.B EINVAL
.I reserved
is not
.IR NULL .
.TP
.B EINVAL
.I settings
is invalid.
.TP
.B EINVAL
.I settings
uses asterisk-encoding to specify random salts.
.TP
.B EINVAL
.I settings
uses asterisk-encoding in place of a hash result.
.TP
.B EINVAL
.I settings
contains no hash result.
.TP
.B ERANGE
.I len
is too large or too small for the selected
initial algorithm.
.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_verify ()
T} Thread safety MT-Safe
T{
.BR librecrypt_verify ()
T} Async-signal safety AS-Unsafe
.TE
.sp
.SH HISTORY
The
.BR librecrypt_verify ()
function was introduced in version 1.1 of
.BR librecrypt .
.SH SEE ALSO
.BR librecrypt (7),
.BR librecrypt_hash_binary (3),
.BR librecrypt_hash (3),
.BR librecrypt_crypt (3),
.BR librecrypt_equal (3),
.BR librecrypt_equal_binary (3)
|
