Debian Codegraph @

lib/crypt.h.in

raw
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 */