/* High-level libcrypt interfaces.

[0] Fix | Delete

[1] Fix | Delete

Copyright (C) 1991-2017 Free Software Foundation, Inc.

[2] Fix | Delete

[3] Fix | Delete

This library is free software; you can redistribute it and/or

[4] Fix | Delete

modify it under the terms of the GNU Lesser General Public License

[5] Fix | Delete

as published by the Free Software Foundation; either version 2.1 of

[6] Fix | Delete

the License, or (at your option) any later version.

[7] Fix | Delete

[8] Fix | Delete

This library is distributed in the hope that it will be useful,

[9] Fix | Delete

but WITHOUT ANY WARRANTY; without even the implied warranty of

[10] Fix | Delete

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

[11] Fix | Delete

GNU Lesser General Public License for more details.

[12] Fix | Delete

[13] Fix | Delete

You should have received a copy of the GNU Lesser General Public

[14] Fix | Delete

License along with this library; if not, see

[15] Fix | Delete

<https://www.gnu.org/licenses/>. */

[16] Fix | Delete

[17] Fix | Delete

#ifndef _CRYPT_H

[18] Fix | Delete

#define _CRYPT_H 1

[19] Fix | Delete

[20] Fix | Delete

#include <sys/cdefs.h>

[21] Fix | Delete

[22] Fix | Delete

__BEGIN_DECLS

[23] Fix | Delete

[24] Fix | Delete

/* The strings returned by crypt, crypt_r, crypt_rn, and crypt_ra will

[25] Fix | Delete

be no longer than this, counting the terminating NUL. (Existing

[26] Fix | Delete

algorithms all produce much shorter strings, but we have reserved

[27] Fix | Delete

generous space for future expansion.) This is NOT the appropriate

[28] Fix | Delete

size to use in allocating the buffer supplied to crypt_rn; use

[29] Fix | Delete

sizeof (struct crypt_data) instead. */

[30] Fix | Delete

#define CRYPT_OUTPUT_SIZE 384

[31] Fix | Delete

[32] Fix | Delete

/* Passphrases longer than this (counting the terminating NUL) are not

[33] Fix | Delete

supported. Note that some hash algorithms have lower limits. */

[34] Fix | Delete

#define CRYPT_MAX_PASSPHRASE_SIZE 512

[35] Fix | Delete

[36] Fix | Delete

/* The strings returned by crypt_gensalt, crypt_gensalt_rn, and

[37] Fix | Delete

crypt_gensalt_ra will be no longer than this. This IS the

[38] Fix | Delete

appropriate size to use when allocating the buffer supplied to

[39] Fix | Delete

crypt_gensalt_rn. (Again, existing algorithms all produce

[40] Fix | Delete

much shorter strings, but we have reserved generous space for

[41] Fix | Delete

future expansion.) */

[42] Fix | Delete

#define CRYPT_GENSALT_OUTPUT_SIZE 192

[43] Fix | Delete

[44] Fix | Delete

/* One-way hash the passphrase PHRASE as specified by SETTING, and

[45] Fix | Delete

return a string suitable for storage in a Unix-style "passwd" file.

[46] Fix | Delete

[47] Fix | Delete

If SETTING is a previously hashed passphrase, the string returned

[48] Fix | Delete

will be equal to SETTING if and only if PHRASE is the same as the

[49] Fix | Delete

passphrase that was previously hashed. See the documentation for

[50] Fix | Delete

other ways to use this function.

[51] Fix | Delete

[52] Fix | Delete

The string returned by this function is stored in a statically-

[53] Fix | Delete

allocated buffer, and will be overwritten if the function is called

[54] Fix | Delete

again. It is not safe to call this function from multiple threads

[55] Fix | Delete

concurrently.

[56] Fix | Delete

[57] Fix | Delete

If an error occurs (such as SETTING being nonsense or unsupported)

[58] Fix | Delete

the string returned will begin with '*', and will not be equal to

[59] Fix | Delete

SETTING nor to any valid hashed passphrase. Otherwise, the string

[60] Fix | Delete

will not begin with '*'. */

[61] Fix | Delete

extern char *crypt (const char *__phrase, const char *__setting)

[62] Fix | Delete

__THROW __nonnull ((1, 2));

[63] Fix | Delete

[64] Fix | Delete

/* These sizes are chosen to make sizeof (struct crypt_data) add up to

[65] Fix | Delete

exactly 32768 bytes. */

[66] Fix | Delete

#define CRYPT_DATA_RESERVED_SIZE 767

[67] Fix | Delete

#define CRYPT_DATA_INTERNAL_SIZE 30720

[68] Fix | Delete

[69] Fix | Delete

/* Memory area used by crypt_r. */

[70] Fix | Delete

struct crypt_data

[71] Fix | Delete

{

[72] Fix | Delete

/* crypt_r writes the hashed password to this field of its 'data'

[73] Fix | Delete

argument. crypt_rn and crypt_ra do the same, treating the

[74] Fix | Delete

untyped data area they are supplied with as this struct. */

[75] Fix | Delete

char output[CRYPT_OUTPUT_SIZE];

[76] Fix | Delete

[77] Fix | Delete

/* Applications are encouraged, but not required, to use this field

[78] Fix | Delete

to store the "setting" string that must be passed to crypt_*.

[79] Fix | Delete

Future extensions to the API may make this more ergonomic.

[80] Fix | Delete

[81] Fix | Delete

A valid "setting" is either previously hashed password or the

[82] Fix | Delete

string produced by one of the crypt_gensalt functions; see the

[83] Fix | Delete

crypt_gensalt documentation for further details. */

[84] Fix | Delete

char setting[CRYPT_OUTPUT_SIZE];

[85] Fix | Delete

[86] Fix | Delete

/* Applications are encouraged, but not required, to use this field

[87] Fix | Delete

to store the unhashed passphrase they will pass to crypt_*.

[88] Fix | Delete

Future extensions to the API may make this more ergonomic. */

[89] Fix | Delete

char input[CRYPT_MAX_PASSPHRASE_SIZE];

[90] Fix | Delete

[91] Fix | Delete

/* Reserved for future application-visible fields. For maximum

[92] Fix | Delete

forward compatibility, applications should set this field to all

[93] Fix | Delete

bytes zero before calling crypt_r, crypt_rn, or crypt_ra for the

[94] Fix | Delete

first time with a just-allocated 'struct crypt_data'. Future

[95] Fix | Delete

extensions to the API may make this more ergonomic. */

[96] Fix | Delete

char reserved[CRYPT_DATA_RESERVED_SIZE];

[97] Fix | Delete

[98] Fix | Delete

/* This field should be set to 0 before calling crypt_r, crypt_rn,

[99] Fix | Delete

or crypt_ra for the first time with a just-allocated

[100] Fix | Delete

'struct crypt_data'. This is not required if crypt_ra is allowed

[101] Fix | Delete

to do the allocation itself (i.e. if the *DATA argument is a null

[102] Fix | Delete

pointer). Future extensions to the API may make this more ergonomic. */

[103] Fix | Delete

char initialized;

[104] Fix | Delete

[105] Fix | Delete

/* Scratch space used internally. Applications should not read or

[106] Fix | Delete

write this field. All data written to this area is erased before

[107] Fix | Delete

returning from the library. */

[108] Fix | Delete

char internal[CRYPT_DATA_INTERNAL_SIZE];

[109] Fix | Delete

};

[110] Fix | Delete

[111] Fix | Delete

/* Thread-safe version of crypt. Instead of writing to a static

[112] Fix | Delete

storage area, the string returned by this function will be within

[113] Fix | Delete

DATA->output. Otherwise, behaves exactly the same as crypt. */

[114] Fix | Delete

extern char *crypt_r (const char *__phrase, const char *__setting,

[115] Fix | Delete

struct crypt_data *__restrict __data)

[116] Fix | Delete

__THROW __nonnull ((1, 2, 3));

[117] Fix | Delete

[118] Fix | Delete

/* Another thread-safe version of crypt. Instead of writing to a

[119] Fix | Delete

static storage area, the string returned by this function will be

[120] Fix | Delete

somewhere within the space provided at DATA, which is of length SIZE

[121] Fix | Delete

bytes. SIZE must be at least sizeof (struct crypt_data).

[122] Fix | Delete

[123] Fix | Delete

Also, if an error occurs, this function returns a null pointer,

[124] Fix | Delete

not a special string. (However, the string returned on success

[125] Fix | Delete

still will never begin with '*'.) */

[126] Fix | Delete

extern char *crypt_rn (const char *__phrase, const char *__setting,

[127] Fix | Delete

void *__data, int __size)

[128] Fix | Delete

__THROW __nonnull ((1, 2, 3));

[129] Fix | Delete

[130] Fix | Delete

/* Yet a third thread-safe version of crypt; this one works like

[131] Fix | Delete

getline(3). *DATA must be either 0 or a pointer to memory

[132] Fix | Delete

allocated by malloc, and *SIZE must be the size of the allocation.

[133] Fix | Delete

This space will be allocated or reallocated as necessary and the

[134] Fix | Delete

values updated. The string returned by this function will be

[135] Fix | Delete

somewhere within the space at *DATA. It is safe to deallocate

[136] Fix | Delete

this space with free when it is no longer needed.

[137] Fix | Delete

[138] Fix | Delete

Like crypt_rn, this function returns a null pointer on failure, not

[139] Fix | Delete

a special string. */

[140] Fix | Delete

extern char *crypt_ra (const char *__phrase, const char *__setting,

[141] Fix | Delete

void **__data, int *__size)

[142] Fix | Delete

__THROW __nonnull ((1, 2, 3, 4));

[143] Fix | Delete

[144] Fix | Delete

[145] Fix | Delete

/* Generate a string suitable for use as the setting when hashing a

[146] Fix | Delete

new passphrase. PREFIX controls which hash function will be used,

[147] Fix | Delete

COUNT controls the computational cost of the hash (for functions

[148] Fix | Delete

where this is tunable), and RBYTES should point to NRBYTES bytes of

[149] Fix | Delete

random data. If PREFIX is a null pointer, the current best default

[150] Fix | Delete

is used; if RBYTES is a null pointer, random data will be retrieved

[151] Fix | Delete

from the operating system if possible. (Caution: setting PREFIX to

[152] Fix | Delete

an *empty string* selects the use of the oldest and least secure

[153] Fix | Delete

hash in the library. Don't do that.)

[154] Fix | Delete

[155] Fix | Delete

The string returned is stored in a statically-allocated buffer, and

[156] Fix | Delete

will be overwritten if the function is called again. It is not

[157] Fix | Delete

safe to call this function from multiple threads concurrently.

[158] Fix | Delete

However, within a single thread, it is safe to pass the string as

[159] Fix | Delete

the SETTING argument to crypt without copying it first; the two

[160] Fix | Delete

functions use separate buffers.

[161] Fix | Delete

[162] Fix | Delete

If an error occurs (e.g. a prefix that does not correspond to a

[163] Fix | Delete

supported hash function, or an inadequate amount of random data),

[164] Fix | Delete

this function returns a null pointer. */

[165] Fix | Delete

extern char *crypt_gensalt (const char *__prefix, unsigned long __count,

[166] Fix | Delete

const char *__rbytes, int __nrbytes)

[167] Fix | Delete

__THROW;

[168] Fix | Delete

[169] Fix | Delete

/* Thread-safe version of crypt_gensalt; instead of a

[170] Fix | Delete

statically-allocated buffer, the generated setting string is

[171] Fix | Delete

written to OUTPUT, which is OUTPUT_SIZE bytes long. OUTPUT_SIZE

[172] Fix | Delete

must be at least CRYPT_GENSALT_OUTPUT_SIZE (see above).

[173] Fix | Delete

[174] Fix | Delete

If an error occurs, this function returns a null pointer and writes

[175] Fix | Delete

a string that does not correspond to any valid setting into OUTPUT. */

[176] Fix | Delete

extern char *crypt_gensalt_rn (const char *__prefix, unsigned long __count,

[177] Fix | Delete

const char *__rbytes, int __nrbytes,

[178] Fix | Delete

char *__output, int __output_size)

[179] Fix | Delete

__THROW __nonnull ((5));

[180] Fix | Delete

[181] Fix | Delete

/* Another thread-safe version of crypt_gensalt; the generated setting

[182] Fix | Delete

string is in storage allocated by malloc, and should be deallocated

[183] Fix | Delete

with free when it is no longer needed. */

[184] Fix | Delete

extern char *crypt_gensalt_ra (const char *__prefix, unsigned long __count,

[185] Fix | Delete

const char *__rbytes, int __nrbytes)

[186] Fix | Delete

__THROW;

[187] Fix | Delete

[188] Fix | Delete

/* These macros could be checked by portable users of crypt_gensalt*

[189] Fix | Delete

functions to find out whether null pointers could be specified

[190] Fix | Delete

as PREFIX and RBYTES arguments. */

[191] Fix | Delete

#define CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX 1

[192] Fix | Delete

#define CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY 1

[193] Fix | Delete

[194] Fix | Delete

__END_DECLS

[195] Fix | Delete

[196] Fix | Delete

#endif /* crypt.h */

[197] Fix | Delete

[198] Fix | Delete