librecrypt.7


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

.TH LIBRECRYPT 7 LIBRECRYPT
.SH NAME
librecrypt - Offline-hardenable password hashing

.SH SYNOPSIS
.ni
#include <librecrypt.h>
.fi
.PP
Link with
.IR -lrecrypt .
Static linking may require additional
flags depending on enabled hash algorithms.

.SH DESCRIPTION
The
.B librecrypt
library provides a unified interface for
several password hash functions and the ability to chain
password hash functions so that a weaking hashed password
can be hardend, without knowing the plain-text password,
by hashing the hash with a stronger function.
.PP
.B librecrypt
extends
.BR crypt (3)\(aqs
password hash string syntax
by introducing the
.RB \(aq > \(aq
character to specifying chaining.
The left-most hash function is used on the plain-text
password, and the next to the right, is used on the binary
hash result, and so on, and only the final hash is stored
in the string: as part of the last
.RB \(aq > \(aq-delimited
section.
.PP
It also supports specifying a password hashing configuration
without specifying actual salt values, but instead how many
bytes of salt to generate. This done using asterisk-encoding:
an ASCII asterisk character
.RB (\(aq * \(aq)
followed by the number of
bytes encoded as a non-negative decimal number in ASCII.
.PP
The
.B librecrypt
library implements the following functions:
.sp
.SS Password hashing functions:
.TP
.BR librecrypt_crypt (3)
Compute password hash encoded in ASCII with settings
prefix.
.TP
.BR librecrypt_hash (3)
Compute password hash encoded in ASCII without
settings prefix.
.TP
.BR librecrypt_hash_binary (3)
Compute password hash in raw binary form.
.TP
.BR librecrypt_add_algorithm (3)
Append an algorithm chain to a password hash string.
.sp
.SS Password hashing configuration generation functions:
.TP
.BR librecrypt_test_supported (3)
Check whether an algorithm chain is supported.
.TP
.BR librecrypt_make_settings (3)
Generate a password hash settings string.
.TP
.BR librecrypt_realise_salts (3)
Realise asterisk-encoded random salts in a settings
string.
.sp
.SS Secure application helper functions:
.TP
.BR librecrypt_equal (3)
Compare strings in constant time.
.TP
.BR librecrypt_equal_binary (3)
Compare memory segments in constant time.
.TP
.BR librecrypt_wipe (3)
Securely erase a memory buffer.
.TP
.BR librecrypt_wipe_str (3)
Securely erase a string.
.sp
.SS Password hash string decomposition functions (ADVANCED):
.TP
.BR librecrypt_settings_prefix (3)
Get length of settings prefix in a password hash
string.
.TP
.BR librecrypt_chain_length (3)
Get number of algorithms in a chained password hash
string.
.TP
.BR librecrypt_decompose_chain (3)
Split a chained password hash string into algorithm
components.
.TP
.BR librecrypt_decompose_chain1 (3)
Replace algorithm link delimiters with null bytes.
.TP
.BR librecrypt_next_algorithm (3)
Iterate over algorithms in a chained password hash
string.
.sp
.SS Binary value encoding functions (ADVANCED):
.TP
.BR librecrypt_encode (3)
Encode binary salt or hash result into ASCII.
.TP
.BR librecrypt_decode (3)
Decode ASCII encoding of a salt or hash result into
binary.
.TP
.BR librecrypt_get_encoding (3)
Get encoding alphabet for the last algorithm in a
chain.

.SH SEE ALSO
.BR crypt (3),
.BR crypt (5)