Mercurial > repos > rliterman > csp2

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