.\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.
.\" Revised by Zack Weinberg <zackw at panix.com> in 2017.
.\" Converted to mdoc format by Zack Weinberg in 2018.
.\"
.\" No copyright is claimed, and this man page is hereby placed in the public
.\" domain.  In case this attempt to disclaim copyright and place the man page
.\" in the public domain is deemed null and void, then the man page is
.\" Copyright 2000-2011 Solar Designer, 2017 Zack Weinberg, and it is
.\" hereby released to the general public under the following terms:
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted.
.\"
.\" There's ABSOLUTELY NO WARRANTY, express or implied.
.\"
.Dd March 27, 2024
.Dt CRYPT_GENSALT 3
.Os "Openwall Project"
.Sh NAME
.Nm crypt_gensalt , crypt_gensalt_rn , crypt_gensalt_ra
.Nd encode settings for passphrase hashing
.Sh LIBRARY
.Lb libcrypt
.Sh SYNOPSIS
.In crypt.h
.Ft "char *"
.Fo crypt_gensalt
.Fa "const char *prefix"
.Fa "unsigned long count"
.Fa "const char *rbytes"
.Fa "int nrbytes"
.Fc
.Ft "char *"
.Fo crypt_gensalt_rn
.Fa "const char * prefix"
.Fa "unsigned long count"
.Fa "const char *rbytes"
.Fa "int nrbytes"
.Fa "char * output"
.Fa "int output_size"
.Fc
.Ft "char *"
.Fo crypt_gensalt_ra
.Fa "const char *prefix"
.Fa "unsigned long count"
.Fa "const char *rbytes"
.Fa "int nrbytes"
.Fc
.Sh DESCRIPTION
The
.Nm crypt_gensalt ,
.Nm crypt_gensalt_rn ,
and
.Nm crypt_gensalt_ra
functions compile a string for use as the
.Fa setting
argument to
.Nm crypt ,
.Nm crypt_r ,
.Nm crypt_rn ,
and
.Nm crypt_ra .
.Fa prefix
selects the hashing method to use.
.Fa count
controls the processing cost of the hash;
the valid range and exact meaning of
.Fa count
depend on the hashing method,
but larger numbers correspond to more costly hashes
in terms of CPU time and possibly memory usage.
.Fa rbytes
should point to
.Fa nrbytes
cryptographically random bytes for use as
.Dq salt.
.Pp
If
.Fa prefix
is a null pointer, the best available hashing method will be selected.
.Po Sy CAUTION :
if
.Fa prefix
is an empty string,
the
.Dq traditional
DES-based hashing method will be selected;
this method is unacceptably weak by modern standards.
.Pc
If
.Fa count
is 0, a low default cost will be selected.
If
.Fa rbytes
is a null pointer, an appropriate number of random bytes will be
obtained from the operating system, and
.Fa nrbytes
is ignored.
.Pp
See
.Xr crypt 5
for other strings that can be used as
.Fa prefix ,
and valid values of
.Fa count
for each.
.Sh RETURN VALUES
.Nm crypt_gensalt ,
.Nm crypt_gensalt_rn ,
and
.Nm crypt_gensalt_ra
return a pointer to an encoded setting string.
This string will be entirely printable ASCII,
and will not contain whitespace or the characters
.Sq Li \&: ,
.Sq Li \&; ,
.Sq Li \&* ,
.Sq Li \&! ,
or
.Sq Li \&\e .
See
.Xr crypt 5
for more detail on the format of this string.
Upon error, they return a null pointer and set
.Va errno
to an appropriate error code.
When the functions succeed, the value of
.Va errno
is unspecified and must not be relied upon.
.Pp
.Nm crypt_gensalt
places its result in a static storage area,
which will be overwritten by subsequent calls to
.Nm crypt_gensalt .
In this version of libcrypt,
the static storage area is allocated separately for each thread,
but portable code should not call
.Nm crypt_gensalt
from multiple threads simultaneously.
It's also not recommended to use the pointer
returned as an argument for another call to
.Nm crypt_gensalt ,
as some implementations, including earlier
releases of libxcrypt, may overwrite the underlying
static output buffer before computing the setting.
However, it
.Em is
safe to pass the string returned by
.Nm crypt_gensalt
directly to
.Nm crypt
without copying it;
each function has its own static storage area.
.Pp
.Nm crypt_gensalt_rn
places its result in the supplied
.Fa output
buffer, which has
.Fa output_size
bytes of storage available.
.Fa output_size
should be greater than or equal to
.Dv CRYPT_GENSALT_OUTPUT_SIZE .
It's also not recommended to use the pointer
returned as an argument for another call to
.Nm crypt_gensalt_rn
using the same
.Fa output
buffer for subsequent calls, as some implementations,
including earlier releases of libxcrypt, may overwrite
the supplied buffer before computing the setting.
.Pp
.Nm crypt_gensalt_ra
allocates memory for its result using
.Xr malloc 3 .
It should be freed with
.Xr free 3
after use.
.Pp
Upon error, in addition to returning a null pointer,
.Nm crypt_gensalt
and
.Nm crypt_gensalt_rn
will write an invalid setting string
to their output buffer, if there is enough space;
this string will begin with a
.Sq Li \&*
and will not be equal to
.Fa prefix .
.Sh ERRORS
.Bl -tag -width Er
.It Er EINVAL
.Fa prefix
is invalid or not supported by this implementation;
.Fa count
is invalid for the requested
.Fa prefix ;
the input
.Fa nrbytes
is insufficient for the smallest valid salt with the requested
.Fa prefix .
.It Er ERANGE
.Nm crypt_gensalt_rn
only:
.Fa output_size
is too small to hold the compiled
.Fa setting
string.
.It Er ENOMEM
Failed to allocate internal scratch memory.
.br
.Nm crypt_gensalt_ra
only:
failed to allocate memory for the compiled
.Fa setting
string.
.It Er ENOSYS , EACCES , EIO , No etc.\&
Obtaining random bytes from the operating system failed.
This can only happen when
.Fa rbytes
is a null pointer.
.El
.Sh FEATURE TEST MACROS
The following macros are defined by
.In crypt.h :
.Bl -tag -width 6n
.It Dv CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX
A null pointer can be specified as the
.Fa prefix
argument.
.It Dv CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY
A null pointer can be specified as the
.Fa rbytes
argument.
.El
.Sh PORTABILITY NOTES
The functions
.Nm crypt_gensalt ,
.Nm crypt_gensalt_rn ,
and
.Nm crypt_gensalt_ra
are not part of any standard.
They originate with the Openwall project.
A function with the name
.Nm crypt_gensalt
also exists on Solaris 10 and newer, but its prototype and semantics differ.
.Pp
Some implementations of
.Nm crypt_gensalt
use a single storage area for all callers,
even in the presence of threads.
This library uses per-thread storage areas,
but portable code should avoid calling
.Nm crypt_gensalt
from multiple threads simultaneously; instead it is strongly advised to
allocate thread-specific buffers of
.Dv CRYPT_GENSALT_OUTPUT_SIZE
length from within each thread itself, and to use these buffers with the
re-entrant interface provided through
.Nm crypt_gensalt_rn ,
or
.Nm crypt_gensalt_ra .
.Pp
The default prefix and auto entropy features are available since libxcrypt
version 4.0.0.  Portable software can use feature test macros to find out
whether null pointers can be used for the
.Fa prefix
and
.Fa rbytes
arguments.
.Pp
The set of supported hashing methods varies considerably from system
to system.
.Sh ATTRIBUTES
For an explanation of the terms used in this section, see
.Xr attributes 7 .
.ad l
.TS
allbox;
lb lb lb
l l l.
Interface	Attribute	Value
T{
.Nm crypt_gensalt
T}	Thread safety	MT-Safe*
T{
.Nm crypt_gensalt_rn ,
.Nm crypt_gensalt_ra
T}	Thread safety	MT-Safe
.TE
.ad
.Pp
\&* In this implementation.
Do NOT rely on this to be portable behavior.
See
.Sx PORTABILITY NOTES .
.Sh SEE ALSO
.Xr crypt 3 ,
.Xr getpass 3 ,
.Xr getpwent 3 ,
.Xr shadow 3 ,
.Xr login 1 ,
.Xr passwd 1 ,
.Xr crypt 5 ,
.Xr passwd 5 ,
.Xr shadow 5 ,
.Xr pam 8
