|
Packit |
13e0ca |
/* High-level libcrypt interfaces.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
Copyright (C) 1991-2017 Free Software Foundation, Inc.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
This library is free software; you can redistribute it and/or
|
|
Packit |
13e0ca |
modify it under the terms of the GNU Lesser General Public License
|
|
Packit |
13e0ca |
as published by the Free Software Foundation; either version 2.1 of
|
|
Packit |
13e0ca |
the License, or (at your option) any later version.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
This library is distributed in the hope that it will be useful,
|
|
Packit |
13e0ca |
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit |
13e0ca |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
Packit |
13e0ca |
GNU Lesser General Public License for more details.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
You should have received a copy of the GNU Lesser General Public
|
|
Packit |
13e0ca |
License along with this library; if not, see
|
|
Packit |
13e0ca |
<https://www.gnu.org/licenses/>. */
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
#ifndef _CRYPT_H
|
|
Packit |
13e0ca |
#define _CRYPT_H 1
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/*HEADER*/
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* The strings returned by crypt, crypt_r, crypt_rn, and crypt_ra will
|
|
Packit |
13e0ca |
be no longer than this, counting the terminating NUL. (Existing
|
|
Packit |
13e0ca |
algorithms all produce much shorter strings, but we have reserved
|
|
Packit |
13e0ca |
generous space for future expansion.) This is NOT the appropriate
|
|
Packit |
13e0ca |
size to use in allocating the buffer supplied to crypt_rn; use
|
|
Packit |
13e0ca |
sizeof (struct crypt_data) instead. */
|
|
Packit |
13e0ca |
#define CRYPT_OUTPUT_SIZE 384
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Passphrases longer than this (counting the terminating NUL) are not
|
|
Packit |
13e0ca |
supported. Note that some hash algorithms have lower limits. */
|
|
Packit |
13e0ca |
#define CRYPT_MAX_PASSPHRASE_SIZE 512
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* The strings returned by crypt_gensalt, crypt_gensalt_rn, and
|
|
Packit |
13e0ca |
crypt_gensalt_ra will be no longer than this. This IS the
|
|
Packit |
13e0ca |
appropriate size to use when allocating the buffer supplied to
|
|
Packit |
13e0ca |
crypt_gensalt_rn. (Again, existing algorithms all produce
|
|
Packit |
13e0ca |
much shorter strings, but we have reserved generous space for
|
|
Packit |
13e0ca |
future expansion.) */
|
|
Packit |
13e0ca |
#define CRYPT_GENSALT_OUTPUT_SIZE 192
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* One-way hash the passphrase PHRASE as specified by SETTING, and
|
|
Packit |
13e0ca |
return a string suitable for storage in a Unix-style "passwd" file.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
If SETTING is a previously hashed passphrase, the string returned
|
|
Packit |
13e0ca |
will be equal to SETTING if and only if PHRASE is the same as the
|
|
Packit |
13e0ca |
passphrase that was previously hashed. See the documentation for
|
|
Packit |
13e0ca |
other ways to use this function.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
The string returned by this function is stored in a statically-
|
|
Packit |
13e0ca |
allocated buffer, and will be overwritten if the function is called
|
|
Packit |
13e0ca |
again. It is not safe to call this function from multiple threads
|
|
Packit |
13e0ca |
concurrently.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
If an error occurs (such as SETTING being nonsense or unsupported)
|
|
Packit |
13e0ca |
the string returned will begin with '*', and will not be equal to
|
|
Packit |
13e0ca |
SETTING nor to any valid hashed passphrase. Otherwise, the string
|
|
Packit |
13e0ca |
will not begin with '*'. */
|
|
Packit |
13e0ca |
extern char *crypt (const char *__phrase, const char *__setting)
|
|
Packit |
13e0ca |
__THROW __nonnull ((1, 2));
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* These sizes are chosen to make sizeof (struct crypt_data) add up to
|
|
Packit |
13e0ca |
exactly 32768 bytes. */
|
|
Packit |
13e0ca |
#define CRYPT_DATA_RESERVED_SIZE 767
|
|
Packit |
13e0ca |
#define CRYPT_DATA_INTERNAL_SIZE 30720
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Memory area used by crypt_r. */
|
|
Packit |
13e0ca |
struct crypt_data
|
|
Packit |
13e0ca |
{
|
|
Packit |
13e0ca |
/* crypt_r writes the hashed password to this field of its 'data'
|
|
Packit |
13e0ca |
argument. crypt_rn and crypt_ra do the same, treating the
|
|
Packit |
13e0ca |
untyped data area they are supplied with as this struct. */
|
|
Packit |
13e0ca |
char output[CRYPT_OUTPUT_SIZE];
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Applications are encouraged, but not required, to use this field
|
|
Packit |
13e0ca |
to store the "setting" string that must be passed to crypt_*.
|
|
Packit |
13e0ca |
Future extensions to the API may make this more ergonomic.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
A valid "setting" is either previously hashed password or the
|
|
Packit |
13e0ca |
string produced by one of the crypt_gensalt functions; see the
|
|
Packit |
13e0ca |
crypt_gensalt documentation for further details. */
|
|
Packit |
13e0ca |
char setting[CRYPT_OUTPUT_SIZE];
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Applications are encouraged, but not required, to use this field
|
|
Packit |
13e0ca |
to store the unhashed passphrase they will pass to crypt_*.
|
|
Packit |
13e0ca |
Future extensions to the API may make this more ergonomic. */
|
|
Packit |
13e0ca |
char input[CRYPT_MAX_PASSPHRASE_SIZE];
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Reserved for future application-visible fields. For maximum
|
|
Packit |
13e0ca |
forward compatibility, applications should set this field to all
|
|
Packit |
13e0ca |
bytes zero before calling crypt_r, crypt_rn, or crypt_ra for the
|
|
Packit |
13e0ca |
first time with a just-allocated 'struct crypt_data'. Future
|
|
Packit |
13e0ca |
extensions to the API may make this more ergonomic. */
|
|
Packit |
13e0ca |
char reserved[CRYPT_DATA_RESERVED_SIZE];
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* This field should be set to 0 before calling crypt_r, crypt_rn,
|
|
Packit |
13e0ca |
or crypt_ra for the first time with a just-allocated
|
|
Packit |
13e0ca |
'struct crypt_data'. This is not required if crypt_ra is allowed
|
|
Packit |
13e0ca |
to do the allocation itself (i.e. if the *DATA argument is a null
|
|
Packit |
13e0ca |
pointer). Future extensions to the API may make this more ergonomic. */
|
|
Packit |
13e0ca |
char initialized;
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Scratch space used internally. Applications should not read or
|
|
Packit |
13e0ca |
write this field. All data written to this area is erased before
|
|
Packit |
13e0ca |
returning from the library. */
|
|
Packit |
13e0ca |
char internal[CRYPT_DATA_INTERNAL_SIZE];
|
|
Packit |
13e0ca |
};
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Thread-safe version of crypt. Instead of writing to a static
|
|
Packit |
13e0ca |
storage area, the string returned by this function will be within
|
|
Packit |
13e0ca |
DATA->output. Otherwise, behaves exactly the same as crypt. */
|
|
Packit |
13e0ca |
extern char *crypt_r (const char *__phrase, const char *__setting,
|
|
Packit |
13e0ca |
struct crypt_data *__restrict __data)
|
|
Packit |
13e0ca |
__THROW __nonnull ((1, 2, 3));
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Another thread-safe version of crypt. Instead of writing to a
|
|
Packit |
13e0ca |
static storage area, the string returned by this function will be
|
|
Packit |
13e0ca |
somewhere within the space provided at DATA, which is of length SIZE
|
|
Packit |
13e0ca |
bytes. SIZE must be at least sizeof (struct crypt_data).
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
Also, if an error occurs, this function returns a null pointer,
|
|
Packit |
13e0ca |
not a special string. (However, the string returned on success
|
|
Packit |
13e0ca |
still will never begin with '*'.) */
|
|
Packit |
13e0ca |
extern char *crypt_rn (const char *__phrase, const char *__setting,
|
|
Packit |
13e0ca |
void *__data, int __size)
|
|
Packit |
13e0ca |
__THROW __nonnull ((1, 2, 3));
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Yet a third thread-safe version of crypt; this one works like
|
|
Packit |
13e0ca |
getline(3). *DATA must be either 0 or a pointer to memory
|
|
Packit |
13e0ca |
allocated by malloc, and *SIZE must be the size of the allocation.
|
|
Packit |
13e0ca |
This space will be allocated or reallocated as necessary and the
|
|
Packit |
13e0ca |
values updated. The string returned by this function will be
|
|
Packit |
13e0ca |
somewhere within the space at *DATA. It is safe to deallocate
|
|
Packit |
13e0ca |
this space with free when it is no longer needed.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
Like crypt_rn, this function returns a null pointer on failure, not
|
|
Packit |
13e0ca |
a special string. */
|
|
Packit |
13e0ca |
extern char *crypt_ra (const char *__phrase, const char *__setting,
|
|
Packit |
13e0ca |
void **__data, int *__size)
|
|
Packit |
13e0ca |
__THROW __nonnull ((1, 2, 3, 4));
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Generate a string suitable for use as the setting when hashing a
|
|
Packit |
13e0ca |
new passphrase. PREFIX controls which hash function will be used,
|
|
Packit |
13e0ca |
COUNT controls the computational cost of the hash (for functions
|
|
Packit |
13e0ca |
where this is tunable), and RBYTES should point to NRBYTES bytes of
|
|
Packit |
13e0ca |
random data. If PREFIX is a null pointer, the current best default
|
|
Packit |
13e0ca |
is used; if RBYTES is a null pointer, random data will be retrieved
|
|
Packit |
13e0ca |
from the operating system if possible. (Caution: setting PREFIX to
|
|
Packit |
13e0ca |
an *empty string* selects the use of the oldest and least secure
|
|
Packit |
13e0ca |
hash in the library. Don't do that.)
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
The string returned is stored in a statically-allocated buffer, and
|
|
Packit |
13e0ca |
will be overwritten if the function is called again. It is not
|
|
Packit |
13e0ca |
safe to call this function from multiple threads concurrently.
|
|
Packit |
13e0ca |
However, within a single thread, it is safe to pass the string as
|
|
Packit |
13e0ca |
the SETTING argument to crypt without copying it first; the two
|
|
Packit |
13e0ca |
functions use separate buffers.
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
If an error occurs (e.g. a prefix that does not correspond to a
|
|
Packit |
13e0ca |
supported hash function, or an inadequate amount of random data),
|
|
Packit |
13e0ca |
this function returns a null pointer. */
|
|
Packit |
13e0ca |
extern char *crypt_gensalt (const char *__prefix, unsigned long __count,
|
|
Packit |
13e0ca |
const char *__rbytes, int __nrbytes)
|
|
Packit |
13e0ca |
__THROW;
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Thread-safe version of crypt_gensalt; instead of a
|
|
Packit |
13e0ca |
statically-allocated buffer, the generated setting string is
|
|
Packit |
13e0ca |
written to OUTPUT, which is OUTPUT_SIZE bytes long. OUTPUT_SIZE
|
|
Packit |
13e0ca |
must be at least CRYPT_GENSALT_OUTPUT_SIZE (see above).
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
If an error occurs, this function returns a null pointer and writes
|
|
Packit |
13e0ca |
a string that does not correspond to any valid setting into OUTPUT. */
|
|
Packit |
13e0ca |
extern char *crypt_gensalt_rn (const char *__prefix, unsigned long __count,
|
|
Packit |
13e0ca |
const char *__rbytes, int __nrbytes,
|
|
Packit |
13e0ca |
char *__output, int __output_size)
|
|
Packit |
13e0ca |
__THROW __nonnull ((5));
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* Another thread-safe version of crypt_gensalt; the generated setting
|
|
Packit |
13e0ca |
string is in storage allocated by malloc, and should be deallocated
|
|
Packit |
13e0ca |
with free when it is no longer needed. */
|
|
Packit |
13e0ca |
extern char *crypt_gensalt_ra (const char *__prefix, unsigned long __count,
|
|
Packit |
13e0ca |
const char *__rbytes, int __nrbytes)
|
|
Packit |
13e0ca |
__THROW;
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/* These macros could be checked by portable users of crypt_gensalt*
|
|
Packit |
13e0ca |
functions to find out whether null pointers could be specified
|
|
Packit |
13e0ca |
as PREFIX and RBYTES arguments. */
|
|
Packit |
13e0ca |
#define CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX 1
|
|
Packit |
13e0ca |
#define CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY 1
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
/*TRAILER*/
|
|
Packit |
13e0ca |
|
|
Packit |
13e0ca |
#endif /* crypt.h */
|