Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/crypt_gensalt.3 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
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 October 11, 2017
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 CPU time cost of the hash;
67 the valid range for
68 .Fa count
69 and the exact meaning of
70 .Dq CPU time cost
71 depends on the hashing method,
72 but larger numbers correspond to more costly hashes.
73 .Fa rbytes
74 should point to
75 .Fa nrbytes
76 cryptographically random bytes for use as
77 .Dq salt.
78 .Pp
79 If
80 .Fa prefix
81 is a null pointer, the best available hashing method will be selected.
82 .Po Sy CAUTION :
83 if
84 .Fa prefix
85 is an empty string,
86 the
87 .Dq traditional
88 DES-based hashing method will be selected;
89 this method is unacceptably weak by modern standards.
90 .Pc
91 If
92 .Fa count
93 is 0, a low default cost will be selected.
94 If
95 .Fa rbytes
96 is a null pointer, an appropriate number of random bytes will be
97 obtained from the operating system, and
98 .Fa nrbytes
99 is ignored.
100 .Pp
101 See
102 .Xr crypt 5
103 for other strings that can be used as
104 .Fa prefix ,
105 and valid values of
106 .Fa count
107 for each.
108 .Sh RETURN VALUES
109 .Nm crypt_gensalt ,
110 .Nm crypt_gensalt_rn ,
111 and
112 .Nm crypt_gensalt_ra
113 return a pointer to an encoded setting string.
114 This string will be entirely printable ASCII,
115 and will not contain whitespace or the characters
116 .Sq Li \&: ,
117 .Sq Li \&; ,
118 .Sq Li \&* ,
119 .Sq Li \&! ,
120 or
121 .Sq Li \&\e .
122 See
123 .Xr crypt 5
124 for more detail on the format of this string.
125 Upon error, they return a null pointer and set
126 .Va errno
127 to an appropriate error code.
128 .Pp
129 .Nm crypt_gensalt
130 places its result in a static storage area,
131 which will be overwritten by subsequent calls to
132 .Nm crypt_gensalt .
133 It is not safe to call
134 .Nm crypt_gensalt
135 from multiple threads simultaneously.
136 However, it
137 .Em is
138 safe to pass the string returned by
139 .Nm crypt_gensalt
140 directly to
141 .Nm crypt
142 without copying it;
143 each function has its own static storage area.
144 .Pp
145 .Nm crypt_gensalt_rn
146 places its result in the supplied
147 .Fa output
148 buffer, which has
149 .Fa output_size
150 bytes of storage available.
151 .Fa output_size
152 should be greater than or equal to
153 .Dv CRYPT_GENSALT_OUTPUT_SIZE .
154 .Pp
155 .Nm crypt_gensalt_ra
156 allocates memory for its result using
157 .Xr malloc 3 .
158 It should be freed with
159 .Xr free 3
160 after use.
161 .Pp
162 Upon error, in addition to returning a null pointer,
163 .Nm crypt_gensalt
164 and
165 .Nm crypt_gensalt_rn
166 will write an invalid setting string
167 to their output buffer, if there is enough space;
168 this string will begin with a
169 .Sq Li \&*
170 and will not be equal to
171 .Fa prefix .
172 .Sh ERRORS
173 .Bl -tag -width Er
174 .It Er EINVAL
175 .Fa prefix
176 is invalid or not supported by this implementation;
177 .Fa count
178 is invalid for the requested
179 .Fa prefix ;
180 the input
181 .Fa nrbytes
182 is insufficient for the smallest valid salt with the requested
183 .Fa prefix .
184 .It Er ERANGE
185 .Nm crypt_gensalt_rn
186 only:
187 .Fa output_size
188 is too small to hold the compiled
189 .Fa setting
190 string.
191 .It Er ENOMEM
192 Failed to allocate internal scratch memory.
193 .br
194 .Nm crypt_gensalt_ra
195 only:
196 failed to allocate memory for the compiled
197 .Fa setting
198 string.
199 .It Er ENOSYS , EACCES , EIO , No etc.\&
200 Obtaining random bytes from the operating system failed.
201 This can only happen when
202 .Fa rbytes
203 is a null pointer.
204 .El
205 .Sh FEATURE TEST MACROS
206 The following macros are defined by
207 .In crypt.h :
208 .Bl -tag -width 6n
209 .It Dv CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX
210 A null pointer can be specified as the
211 .Fa prefix
212 argument.
213 .It Dv CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY
214 A null pointer can be specified as the
215 .Fa rbytes
216 argument.
217 .El
218 .Sh PORTABILITY NOTES
219 The functions
220 .Nm crypt_gensalt ,
221 .Nm crypt_gensalt_rn ,
222 and
223 .Nm crypt_gensalt_ra
224 are not part of any standard.
225 They originate with the Openwall project.
226 A function with the name
227 .Nm crypt_gensalt
228 also exists on Solaris 10 and newer, but its prototype and semantics differ.
229 .Pp
230 The default prefix and auto entropy features are available since libxcrypt
231 version 4.0.0. Portable software can use feature test macros to find out
232 whether null pointers can be used for the
233 .Fa prefix
234 and
235 .Fa rbytes
236 arguments.
237 .Pp
238 The set of supported hashing methods varies considerably from system
239 to system.
240 .Sh ATTRIBUTES
241 For an explanation of the terms used in this section, see
242 .Xr attributes 7 .
243 .TS
244 allbox;
245 lb lb lb
246 l l l.
247 Interface Attribute Value
248 T{
249 .Nm crypt_gensalt
250 T} Thread safety MT-Unsafe race:crypt_gensalt
251 T{
252 .Nm crypt_gensalt_rn ,
253 .Nm crypt_gensalt_ra
254 T} Thread safety MT-Safe
255 .TE
256 .sp
257 .Sh SEE ALSO
258 .Xr crypt 3 ,
259 .Xr getpass 3 ,
260 .Xr getpwent 3 ,
261 .Xr shadow 3 ,
262 .Xr login 1 ,
263 .Xr passwd 1 ,
264 .Xr crypt 5 ,
265 .Xr passwd 5 ,
266 .Xr shadow 5 ,
267 .Xr pam 8