librecrypt/librecrypt_encode.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
.TH LIBRECRYPT_ENCODE 3 LIBRECRYPT
.SH NAME
librecrypt_encode - Encode binary salt or hash result into ASCII

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

size_t \fBlibrecrypt_encode\fP(char *\fIout_buffer\fP, size_t \fIsize\fP,
                         const void *\fIbinary\fP, size_t \fIlen\fP,
                         const char \fIlut\fP[restrict static 256], char \fIpad\fP);
.fi
.PP
Link with
.IR -lrecrypt .

.SH DESCRIPTION
The
.BR librecrypt_encode ()
function encodes
.I len
bytes of binary data from
.IR binary
into an ASCII representation written to
.IR out_buffer .
This is used for encoding hash results and salts.
.PP
The
.I lut
argument is an encoding alphabet, consisting
of 64 characters, repeated 4 times.
.PP
The
.I pad
argument specifies the padding character to
use at the end, or the null byte if none.
.PP
On successful completion, up to
.I size
bytes are written to
.IR out_buffer ;
if
.I size
is positive, the output is always
null byte-terminated even if truncated.
.PP
The return value is the number of bytes
that would have been written, excluding
the terminating null byte, if
.I size
was sufficiently large.

.SH RETURN VALUES
The
.BR librecrypt_encode ()
function returns the number of bytes that
would have been written to
.IR out_buffer ,
excluding the terminating null byte.
On failure,
.I SIZE_MAX
is returned and
.IR errno
is set to describe the error.

.SH ERRORS
The
.BR librecrypt_encode ()
function will fail if:
.TP
.B EOVERFLOW
.I ascii
uses an invalid encoding.

The
.BR librecrypt_encode ()
function cannot fail.

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

.SH NOTES
The value
.I SIZE_MAX
can be returned on both success and failure.
.I errno
is only modified on failure. For practical
purposes, applications can treat
.I SIZE_MAX
as indicating an
.I ENOMEM
failure.

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

.SH SEE ALSO
.BR librecrypt (7),
.BR librecrypt_decode (3),
.BR librecrypt_get_encoding (3)