Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/crypt.h @ 69:33d812a61356

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 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 /* High-level libcrypt interfaces.
jpayne@69 2
jpayne@69 3 Copyright (C) 1991-2017 Free Software Foundation, Inc.
jpayne@69 4
jpayne@69 5 This library is free software; you can redistribute it and/or
jpayne@69 6 modify it under the terms of the GNU Lesser General Public License
jpayne@69 7 as published by the Free Software Foundation; either version 2.1 of
jpayne@69 8 the License, or (at your option) any later version.
jpayne@69 9
jpayne@69 10 This library is distributed in the hope that it will be useful,
jpayne@69 11 but WITHOUT ANY WARRANTY; without even the implied warranty of
jpayne@69 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
jpayne@69 13 GNU Lesser General Public License for more details.
jpayne@69 14
jpayne@69 15 You should have received a copy of the GNU Lesser General Public
jpayne@69 16 License along with this library; if not, see
jpayne@69 17 <https://www.gnu.org/licenses/>. */
jpayne@69 18
jpayne@69 19 #ifndef _CRYPT_H
jpayne@69 20 #define _CRYPT_H 1
jpayne@69 21
jpayne@69 22 #include <sys/cdefs.h>
jpayne@69 23
jpayne@69 24 __BEGIN_DECLS
jpayne@69 25
jpayne@69 26 /* The strings returned by crypt, crypt_r, crypt_rn, and crypt_ra will
jpayne@69 27 be no longer than this, counting the terminating NUL. (Existing
jpayne@69 28 algorithms all produce much shorter strings, but we have reserved
jpayne@69 29 generous space for future expansion.) This is NOT the appropriate
jpayne@69 30 size to use in allocating the buffer supplied to crypt_rn; use
jpayne@69 31 sizeof (struct crypt_data) instead. */
jpayne@69 32 #define CRYPT_OUTPUT_SIZE 384
jpayne@69 33
jpayne@69 34 /* Passphrases longer than this (counting the terminating NUL) are not
jpayne@69 35 supported. Note that some hash algorithms have lower limits. */
jpayne@69 36 #define CRYPT_MAX_PASSPHRASE_SIZE 512
jpayne@69 37
jpayne@69 38 /* The strings returned by crypt_gensalt, crypt_gensalt_rn, and
jpayne@69 39 crypt_gensalt_ra will be no longer than this. This IS the
jpayne@69 40 appropriate size to use when allocating the buffer supplied to
jpayne@69 41 crypt_gensalt_rn. (Again, existing algorithms all produce
jpayne@69 42 much shorter strings, but we have reserved generous space for
jpayne@69 43 future expansion.) */
jpayne@69 44 #define CRYPT_GENSALT_OUTPUT_SIZE 192
jpayne@69 45
jpayne@69 46 /* One-way hash the passphrase PHRASE as specified by SETTING, and
jpayne@69 47 return a string suitable for storage in a Unix-style "passwd" file.
jpayne@69 48
jpayne@69 49 If SETTING is a previously hashed passphrase, the string returned
jpayne@69 50 will be equal to SETTING if and only if PHRASE is the same as the
jpayne@69 51 passphrase that was previously hashed. See the documentation for
jpayne@69 52 other ways to use this function.
jpayne@69 53
jpayne@69 54 The string returned by this function is stored in a statically-
jpayne@69 55 allocated buffer, and will be overwritten if the function is called
jpayne@69 56 again. It is not safe to call this function from multiple threads
jpayne@69 57 concurrently.
jpayne@69 58
jpayne@69 59 If an error occurs (such as SETTING being nonsense or unsupported)
jpayne@69 60 the string returned will begin with '*', and will not be equal to
jpayne@69 61 SETTING nor to any valid hashed passphrase. Otherwise, the string
jpayne@69 62 will not begin with '*'. */
jpayne@69 63 extern char *crypt (const char *__phrase, const char *__setting)
jpayne@69 64 __THROW;
jpayne@69 65
jpayne@69 66 /* These sizes are chosen to make sizeof (struct crypt_data) add up to
jpayne@69 67 exactly 32768 bytes. */
jpayne@69 68 #define CRYPT_DATA_RESERVED_SIZE 767
jpayne@69 69 #define CRYPT_DATA_INTERNAL_SIZE 30720
jpayne@69 70
jpayne@69 71 /* Memory area used by crypt_r. */
jpayne@69 72 struct crypt_data
jpayne@69 73 {
jpayne@69 74 /* crypt_r writes the hashed password to this field of its 'data'
jpayne@69 75 argument. crypt_rn and crypt_ra do the same, treating the
jpayne@69 76 untyped data area they are supplied with as this struct. */
jpayne@69 77 char output[CRYPT_OUTPUT_SIZE];
jpayne@69 78
jpayne@69 79 /* Applications are encouraged, but not required, to use this field
jpayne@69 80 to store the "setting" string that must be passed to crypt_*.
jpayne@69 81 Future extensions to the API may make this more ergonomic.
jpayne@69 82
jpayne@69 83 A valid "setting" is either previously hashed password or the
jpayne@69 84 string produced by one of the crypt_gensalt functions; see the
jpayne@69 85 crypt_gensalt documentation for further details. */
jpayne@69 86 char setting[CRYPT_OUTPUT_SIZE];
jpayne@69 87
jpayne@69 88 /* Applications are encouraged, but not required, to use this field
jpayne@69 89 to store the unhashed passphrase they will pass to crypt_*.
jpayne@69 90 Future extensions to the API may make this more ergonomic. */
jpayne@69 91 char input[CRYPT_MAX_PASSPHRASE_SIZE];
jpayne@69 92
jpayne@69 93 /* Reserved for future application-visible fields. For maximum
jpayne@69 94 forward compatibility, applications should set this field to all
jpayne@69 95 bytes zero before calling crypt_r, crypt_rn, or crypt_ra for the
jpayne@69 96 first time with a just-allocated 'struct crypt_data'. Future
jpayne@69 97 extensions to the API may make this more ergonomic. */
jpayne@69 98 char reserved[CRYPT_DATA_RESERVED_SIZE];
jpayne@69 99
jpayne@69 100 /* This field should be set to 0 before calling crypt_r, crypt_rn,
jpayne@69 101 or crypt_ra for the first time with a just-allocated
jpayne@69 102 'struct crypt_data'. This is not required if crypt_ra is allowed
jpayne@69 103 to do the allocation itself (i.e. if the *DATA argument is a null
jpayne@69 104 pointer). Future extensions to the API may make this more ergonomic. */
jpayne@69 105 char initialized;
jpayne@69 106
jpayne@69 107 /* Scratch space used internally. Applications should not read or
jpayne@69 108 write this field. All data written to this area is erased before
jpayne@69 109 returning from the library. */
jpayne@69 110 char internal[CRYPT_DATA_INTERNAL_SIZE];
jpayne@69 111 };
jpayne@69 112
jpayne@69 113 /* Thread-safe version of crypt. Instead of writing to a static
jpayne@69 114 storage area, the string returned by this function will be within
jpayne@69 115 DATA->output. Otherwise, behaves exactly the same as crypt. */
jpayne@69 116 extern char *crypt_r (const char *__phrase, const char *__setting,
jpayne@69 117 struct crypt_data *__restrict __data)
jpayne@69 118 __THROW;
jpayne@69 119
jpayne@69 120 /* Another thread-safe version of crypt. Instead of writing to a
jpayne@69 121 static storage area, the string returned by this function will be
jpayne@69 122 somewhere within the space provided at DATA, which is of length SIZE
jpayne@69 123 bytes. SIZE must be at least sizeof (struct crypt_data).
jpayne@69 124
jpayne@69 125 Also, if an error occurs, this function returns a null pointer,
jpayne@69 126 not a special string. (However, the string returned on success
jpayne@69 127 still will never begin with '*'.) */
jpayne@69 128 extern char *crypt_rn (const char *__phrase, const char *__setting,
jpayne@69 129 void *__data, int __size)
jpayne@69 130 __THROW;
jpayne@69 131
jpayne@69 132 /* Yet a third thread-safe version of crypt; this one works like
jpayne@69 133 getline(3). *DATA must be either 0 or a pointer to memory
jpayne@69 134 allocated by malloc, and *SIZE must be the size of the allocation.
jpayne@69 135 This space will be allocated or reallocated as necessary and the
jpayne@69 136 values updated. The string returned by this function will be
jpayne@69 137 somewhere within the space at *DATA. It is safe to deallocate
jpayne@69 138 this space with free when it is no longer needed.
jpayne@69 139
jpayne@69 140 Like crypt_rn, this function returns a null pointer on failure, not
jpayne@69 141 a special string. */
jpayne@69 142 extern char *crypt_ra (const char *__phrase, const char *__setting,
jpayne@69 143 void **__data, int *__size)
jpayne@69 144 __THROW;
jpayne@69 145
jpayne@69 146
jpayne@69 147 /* Generate a string suitable for use as the setting when hashing a
jpayne@69 148 new passphrase. PREFIX controls which hash function will be used,
jpayne@69 149 COUNT controls the computational cost of the hash (for functions
jpayne@69 150 where this is tunable), and RBYTES should point to NRBYTES bytes of
jpayne@69 151 random data. If PREFIX is a null pointer, the current best default
jpayne@69 152 is used; if RBYTES is a null pointer, random data will be retrieved
jpayne@69 153 from the operating system if possible. (Caution: setting PREFIX to
jpayne@69 154 an *empty string* selects the use of the oldest and least secure
jpayne@69 155 hash in the library. Don't do that.)
jpayne@69 156
jpayne@69 157 The string returned is stored in a statically-allocated buffer, and
jpayne@69 158 will be overwritten if the function is called again. It is not
jpayne@69 159 safe to call this function from multiple threads concurrently.
jpayne@69 160 However, within a single thread, it is safe to pass the string as
jpayne@69 161 the SETTING argument to crypt without copying it first; the two
jpayne@69 162 functions use separate buffers.
jpayne@69 163
jpayne@69 164 If an error occurs (e.g. a prefix that does not correspond to a
jpayne@69 165 supported hash function, or an inadequate amount of random data),
jpayne@69 166 this function returns a null pointer. */
jpayne@69 167 extern char *crypt_gensalt (const char *__prefix, unsigned long __count,
jpayne@69 168 const char *__rbytes, int __nrbytes)
jpayne@69 169 __THROW;
jpayne@69 170
jpayne@69 171 /* Thread-safe version of crypt_gensalt; instead of a
jpayne@69 172 statically-allocated buffer, the generated setting string is
jpayne@69 173 written to OUTPUT, which is OUTPUT_SIZE bytes long. OUTPUT_SIZE
jpayne@69 174 must be at least CRYPT_GENSALT_OUTPUT_SIZE (see above).
jpayne@69 175
jpayne@69 176 If an error occurs, this function returns a null pointer and writes
jpayne@69 177 a string that does not correspond to any valid setting into OUTPUT. */
jpayne@69 178 extern char *crypt_gensalt_rn (const char *__prefix, unsigned long __count,
jpayne@69 179 const char *__rbytes, int __nrbytes,
jpayne@69 180 char *__output, int __output_size)
jpayne@69 181 __THROW;
jpayne@69 182
jpayne@69 183 /* Kept for code compatibility with libxcrypt (v3.1.1 and earlier).
jpayne@69 184 We intentionally declare the function using a macro here, since
jpayne@69 185 we actually want to link compiled applications against the
jpayne@69 186 identical crypt_gensalt_rn function. */
jpayne@69 187 #ifndef IN_LIBCRYPT /* Defined when building libxcrypt. */
jpayne@69 188 # ifdef __REDIRECT_NTH
jpayne@69 189 extern char * __REDIRECT_NTH (crypt_gensalt_r, (const char *__prefix,
jpayne@69 190 unsigned long __count, const char *__rbytes,
jpayne@69 191 int __nrbytes, char *__output,
jpayne@69 192 int __output_size), crypt_gensalt_rn);
jpayne@69 193 # else
jpayne@69 194 # define crypt_gensalt_r crypt_gensalt_rn
jpayne@69 195 # endif
jpayne@69 196 #endif
jpayne@69 197
jpayne@69 198 /* Another thread-safe version of crypt_gensalt; the generated setting
jpayne@69 199 string is in storage allocated by malloc, and should be deallocated
jpayne@69 200 with free when it is no longer needed. */
jpayne@69 201 extern char *crypt_gensalt_ra (const char *__prefix, unsigned long __count,
jpayne@69 202 const char *__rbytes, int __nrbytes)
jpayne@69 203 __THROW;
jpayne@69 204
jpayne@69 205 /* Checks whether the given setting is a supported method.
jpayne@69 206
jpayne@69 207 The return value is 0 if there is nothing wrong with this setting.
jpayne@69 208 Otherwise, it is one of the following constants. */
jpayne@69 209 extern int crypt_checksalt (const char *__setting);
jpayne@69 210
jpayne@69 211 /* Constants for checking the return value of the
jpayne@69 212 crypt_checksalt function. */
jpayne@69 213 #define CRYPT_SALT_OK 0
jpayne@69 214 #define CRYPT_SALT_INVALID 1
jpayne@69 215 #define CRYPT_SALT_METHOD_DISABLED 2 /* NOT implemented, yet. */
jpayne@69 216 #define CRYPT_SALT_METHOD_LEGACY 3
jpayne@69 217 #define CRYPT_SALT_TOO_CHEAP 4 /* NOT implemented, yet. */
jpayne@69 218
jpayne@69 219 /* Convenience function to get the prefix of the preferred hash method,
jpayne@69 220 which is also used by the crypt_gensalt functions, if their given
jpayne@69 221 prefix parameter is NULL.
jpayne@69 222
jpayne@69 223 The return value is string that equals the prefix of the preferred
jpayne@69 224 hash method. Otherwise, it is NULL. */
jpayne@69 225 extern const char *crypt_preferred_method (void);
jpayne@69 226
jpayne@69 227 /* These macros could be checked by portable users of crypt_gensalt*
jpayne@69 228 functions to find out whether null pointers could be specified
jpayne@69 229 as PREFIX and RBYTES arguments. */
jpayne@69 230 #define CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX 1
jpayne@69 231 #define CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY 1
jpayne@69 232
jpayne@69 233 /* These macros can be checked by portable users of libxcrypt
jpayne@69 234 to find out whether the function is implemented. */
jpayne@69 235 #define CRYPT_CHECKSALT_AVAILABLE 1
jpayne@69 236 #define CRYPT_PREFERRED_METHOD_AVAILABLE 1
jpayne@69 237
jpayne@69 238 /* Version number split in single integers. */
jpayne@69 239 #define XCRYPT_VERSION_MAJOR 4
jpayne@69 240 #define XCRYPT_VERSION_MINOR 4
jpayne@69 241
jpayne@69 242 /* Version number coded into an integer. */
jpayne@69 243 #define XCRYPT_VERSION_NUM ((XCRYPT_VERSION_MAJOR << 16) | \
jpayne@69 244 XCRYPT_VERSION_MINOR)
jpayne@69 245
jpayne@69 246 /* Version number as a string constant. */
jpayne@69 247 #define XCRYPT_VERSION_STR "4.4.36"
jpayne@69 248
jpayne@69 249 __END_DECLS
jpayne@69 250
jpayne@69 251 #endif /* crypt.h */