Debian Codegraph @

upstream/debian-trixie/man3/crypt_gensalt.3

raw
1 .\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.
2 .\" Revised by Zack Weinberg <zackw at panix.com> in 2017.
3 .\" Converted to mdoc format by Zack Weinberg in 2018.
4 .\"
5 .\" No copyright is claimed, and this man page is hereby placed in the public
6 .\" domain. In case this attempt to disclaim copyright and place the man page
7 .\" in the public domain is deemed null and void, then the man page is
8 .\" Copyright 2000-2011 Solar Designer, 2017 Zack Weinberg, and it is
9 .\" hereby released to the general public under the following terms:
10 .\"
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted.
13 .\"
14 .\" There's ABSOLUTELY NO WARRANTY, express or implied.
15 .\"
16 .Dd March 27, 2024
17 .Dt CRYPT_GENSALT 3
18 .Os "Openwall Project"
19 .Sh NAME
20 .Nm crypt_gensalt , crypt_gensalt_rn , crypt_gensalt_ra
21 .Nd encode settings for passphrase hashing
22 .Sh LIBRARY
23 .Lb libcrypt
24 .Sh SYNOPSIS
25 .In crypt.h
26 .Ft "char *"
27 .Fo crypt_gensalt
28 .Fa "const char *prefix"
29 .Fa "unsigned long count"
30 .Fa "const char *rbytes"
31 .Fa "int nrbytes"
32 .Fc
33 .Ft "char *"
34 .Fo crypt_gensalt_rn
35 .Fa "const char * prefix"
36 .Fa "unsigned long count"
37 .Fa "const char *rbytes"
38 .Fa "int nrbytes"
39 .Fa "char * output"
40 .Fa "int output_size"
41 .Fc
42 .Ft "char *"
43 .Fo crypt_gensalt_ra
44 .Fa "const char *prefix"
45 .Fa "unsigned long count"
46 .Fa "const char *rbytes"
47 .Fa "int nrbytes"
48 .Fc
49 .Sh DESCRIPTION
50 The
51 .Nm crypt_gensalt ,
52 .Nm crypt_gensalt_rn ,
53 and
54 .Nm crypt_gensalt_ra
55 functions compile a string for use as the
56 .Fa setting
57 argument to
58 .Nm crypt ,
59 .Nm crypt_r ,
60 .Nm crypt_rn ,
61 and
62 .Nm crypt_ra .
63 .Fa prefix
64 selects the hashing method to use.
65 .Fa count
66 controls the processing cost of the hash;
67 the valid range and exact meaning of
68 .Fa count
69 depend on the hashing method,
70 but larger numbers correspond to more costly hashes
71 in terms of CPU time and possibly memory usage.
72 .Fa rbytes
73 should point to
74 .Fa nrbytes
75 cryptographically random bytes for use as
76 .Dq salt.
77 .Pp
78 If
79 .Fa prefix
80 is a null pointer, the best available hashing method will be selected.
81 .Po Sy CAUTION :
82 if
83 .Fa prefix
84 is an empty string,
85 the
86 .Dq traditional
87 DES-based hashing method will be selected;
88 this method is unacceptably weak by modern standards.
89 .Pc
90 If
91 .Fa count
92 is 0, a low default cost will be selected.
93 If
94 .Fa rbytes
95 is a null pointer, an appropriate number of random bytes will be
96 obtained from the operating system, and
97 .Fa nrbytes
98 is ignored.
99 .Pp
100 See
101 .Xr crypt 5
102 for other strings that can be used as
103 .Fa prefix ,
104 and valid values of
105 .Fa count
106 for each.
107 .Sh RETURN VALUES
108 .Nm crypt_gensalt ,
109 .Nm crypt_gensalt_rn ,
110 and
111 .Nm crypt_gensalt_ra
112 return a pointer to an encoded setting string.
113 This string will be entirely printable ASCII,
114 and will not contain whitespace or the characters
115 .Sq Li \&: ,
116 .Sq Li \&; ,
117 .Sq Li \&* ,
118 .Sq Li \&! ,
119 or
120 .Sq Li \&\e .
121 See
122 .Xr crypt 5
123 for more detail on the format of this string.
124 Upon error, they return a null pointer and set
125 .Va errno
126 to an appropriate error code.
127 When the functions succeed, the value of
128 .Va errno
129 is unspecified and must not be relied upon.
130 .Pp
131 .Nm crypt_gensalt
132 places its result in a static storage area,
133 which will be overwritten by subsequent calls to
134 .Nm crypt_gensalt .
135 It is not safe to call
136 .Nm crypt_gensalt
137 from multiple threads simultaneously.
138 However, it
139 .Em is
140 safe to pass the string returned by
141 .Nm crypt_gensalt
142 directly to
143 .Nm crypt
144 without copying it;
145 each function has its own static storage area.
146 .Pp
147 .Nm crypt_gensalt_rn
148 places its result in the supplied
149 .Fa output
150 buffer, which has
151 .Fa output_size
152 bytes of storage available.
153 .Fa output_size
154 should be greater than or equal to
155 .Dv CRYPT_GENSALT_OUTPUT_SIZE .
156 .Pp
157 .Nm crypt_gensalt_ra
158 allocates memory for its result using
159 .Xr malloc 3 .
160 It should be freed with
161 .Xr free 3
162 after use.
163 .Pp
164 Upon error, in addition to returning a null pointer,
165 .Nm crypt_gensalt
166 and
167 .Nm crypt_gensalt_rn
168 will write an invalid setting string
169 to their output buffer, if there is enough space;
170 this string will begin with a
171 .Sq Li \&*
172 and will not be equal to
173 .Fa prefix .
174 .Sh ERRORS
175 .Bl -tag -width Er
176 .It Er EINVAL
177 .Fa prefix
178 is invalid or not supported by this implementation;
179 .Fa count
180 is invalid for the requested
181 .Fa prefix ;
182 the input
183 .Fa nrbytes
184 is insufficient for the smallest valid salt with the requested
185 .Fa prefix .
186 .It Er ERANGE
187 .Nm crypt_gensalt_rn
188 only:
189 .Fa output_size
190 is too small to hold the compiled
191 .Fa setting
192 string.
193 .It Er ENOMEM
194 Failed to allocate internal scratch memory.
195 .br
196 .Nm crypt_gensalt_ra
197 only:
198 failed to allocate memory for the compiled
199 .Fa setting
200 string.
201 .It Er ENOSYS , EACCES , EIO , No etc.\&
202 Obtaining random bytes from the operating system failed.
203 This can only happen when
204 .Fa rbytes
205 is a null pointer.
206 .El
207 .Sh FEATURE TEST MACROS
208 The following macros are defined by
209 .In crypt.h :
210 .Bl -tag -width 6n
211 .It Dv CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX
212 A null pointer can be specified as the
213 .Fa prefix
214 argument.
215 .It Dv CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY
216 A null pointer can be specified as the
217 .Fa rbytes
218 argument.
219 .El
220 .Sh PORTABILITY NOTES
221 The functions
222 .Nm crypt_gensalt ,
223 .Nm crypt_gensalt_rn ,
224 and
225 .Nm crypt_gensalt_ra
226 are not part of any standard.
227 They originate with the Openwall project.
228 A function with the name
229 .Nm crypt_gensalt
230 also exists on Solaris 10 and newer, but its prototype and semantics differ.
231 .Pp
232 The default prefix and auto entropy features are available since libxcrypt
233 version 4.0.0. Portable software can use feature test macros to find out
234 whether null pointers can be used for the
235 .Fa prefix
236 and
237 .Fa rbytes
238 arguments.
239 .Pp
240 The set of supported hashing methods varies considerably from system
241 to system.
242 .Sh ATTRIBUTES
243 For an explanation of the terms used in this section, see
244 .Xr attributes 7 .
245 .ad l
246 .TS
247 allbox;
248 lb lb lb
249 l l l.
250 Interface Attribute Value
251 T{
252 .Nm crypt_gensalt
253 T} Thread safety MT-Unsafe race:crypt_gensalt
254 T{
255 .Nm crypt_gensalt_rn ,
256 .Nm crypt_gensalt_ra
257 T} Thread safety MT-Safe
258 .TE
259 .ad
260 .sp
261 .Sh SEE ALSO
262 .Xr crypt 3 ,
263 .Xr getpass 3 ,
264 .Xr getpwent 3 ,
265 .Xr shadow 3 ,
266 .Xr login 1 ,
267 .Xr passwd 1 ,
268 .Xr crypt 5 ,
269 .Xr passwd 5 ,
270 .Xr shadow 5 ,
271 .Xr pam 8