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