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