Debian Codegraph @

upstream/debian-unstable/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 It's also not recommended to use the pointer
139 returned as an argument for another call to
140 .Nm crypt_gensalt ,
141 as some implementations, including earlier
142 releases of libxcrypt, may overwrite the underlying
143 static output buffer before computing the setting.
144 However, it
145 .Em is
146 safe to pass the string returned by
147 .Nm crypt_gensalt
148 directly to
149 .Nm crypt
150 without copying it;
151 each function has its own static storage area.
152 .Pp
153 .Nm crypt_gensalt_rn
154 places its result in the supplied
155 .Fa output
156 buffer, which has
157 .Fa output_size
158 bytes of storage available.
159 .Fa output_size
160 should be greater than or equal to
161 .Dv CRYPT_GENSALT_OUTPUT_SIZE .
162 It's also not recommended to use the pointer
163 returned as an argument for another call to
164 .Nm crypt_gensalt_rn
165 using the same
166 .Fa output
167 buffer for subsequent calls, as some implementations,
168 including earlier releases of libxcrypt, may overwrite
169 the supplied buffer before computing the setting.
170 .Pp
171 .Nm crypt_gensalt_ra
172 allocates memory for its result using
173 .Xr malloc 3 .
174 It should be freed with
175 .Xr free 3
176 after use.
177 .Pp
178 Upon error, in addition to returning a null pointer,
179 .Nm crypt_gensalt
180 and
181 .Nm crypt_gensalt_rn
182 will write an invalid setting string
183 to their output buffer, if there is enough space;
184 this string will begin with a
185 .Sq Li \&*
186 and will not be equal to
187 .Fa prefix .
188 .Sh ERRORS
189 .Bl -tag -width Er
190 .It Er EINVAL
191 .Fa prefix
192 is invalid or not supported by this implementation;
193 .Fa count
194 is invalid for the requested
195 .Fa prefix ;
196 the input
197 .Fa nrbytes
198 is insufficient for the smallest valid salt with the requested
199 .Fa prefix .
200 .It Er ERANGE
201 .Nm crypt_gensalt_rn
202 only:
203 .Fa output_size
204 is too small to hold the compiled
205 .Fa setting
206 string.
207 .It Er ENOMEM
208 Failed to allocate internal scratch memory.
209 .br
210 .Nm crypt_gensalt_ra
211 only:
212 failed to allocate memory for the compiled
213 .Fa setting
214 string.
215 .It Er ENOSYS , EACCES , EIO , No etc.\&
216 Obtaining random bytes from the operating system failed.
217 This can only happen when
218 .Fa rbytes
219 is a null pointer.
220 .El
221 .Sh FEATURE TEST MACROS
222 The following macros are defined by
223 .In crypt.h :
224 .Bl -tag -width 6n
225 .It Dv CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX
226 A null pointer can be specified as the
227 .Fa prefix
228 argument.
229 .It Dv CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY
230 A null pointer can be specified as the
231 .Fa rbytes
232 argument.
233 .El
234 .Sh PORTABILITY NOTES
235 The functions
236 .Nm crypt_gensalt ,
237 .Nm crypt_gensalt_rn ,
238 and
239 .Nm crypt_gensalt_ra
240 are not part of any standard.
241 They originate with the Openwall project.
242 A function with the name
243 .Nm crypt_gensalt
244 also exists on Solaris 10 and newer, but its prototype and semantics differ.
245 .Pp
246 The default prefix and auto entropy features are available since libxcrypt
247 version 4.0.0. Portable software can use feature test macros to find out
248 whether null pointers can be used for the
249 .Fa prefix
250 and
251 .Fa rbytes
252 arguments.
253 .Pp
254 The set of supported hashing methods varies considerably from system
255 to system.
256 .Sh ATTRIBUTES
257 For an explanation of the terms used in this section, see
258 .Xr attributes 7 .
259 .ad l
260 .TS
261 allbox;
262 lb lb lb
263 l l l.
264 Interface Attribute Value
265 T{
266 .Nm crypt_gensalt
267 T} Thread safety MT-Unsafe race:crypt_gensalt
268 T{
269 .Nm crypt_gensalt_rn ,
270 .Nm crypt_gensalt_ra
271 T} Thread safety MT-Safe
272 .TE
273 .ad
274 .sp
275 .Sh SEE ALSO
276 .Xr crypt 3 ,
277 .Xr getpass 3 ,
278 .Xr getpwent 3 ,
279 .Xr shadow 3 ,
280 .Xr login 1 ,
281 .Xr passwd 1 ,
282 .Xr crypt 5 ,
283 .Xr passwd 5 ,
284 .Xr shadow 5 ,
285 .Xr pam 8