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