497 lines
7.4 KiB
HTML
497 lines
7.4 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of CRYPT_GENSALT</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>CRYPT_GENSALT</H1>
|
|
Section: C Library Functions (3)<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
<BR>BSD mandoc<BR>
|
|
Openwall Project
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
<B>crypt_gensalt , crypt_gensalt_rn , crypt_gensalt_ra</B>
|
|
|
|
- encode settings for passphrase hashing
|
|
|
|
<A NAME="lbAC"> </A>
|
|
<H2>LIBRARY</H2>
|
|
|
|
Lb libcrypt
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
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 <A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The
|
|
<B>crypt_gensalt</B>
|
|
|
|
|
|
<B>crypt_gensalt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_gensalt_ra</B>
|
|
|
|
functions compile a string for use as the
|
|
Fa setting
|
|
|
|
argument to
|
|
<B>crypt</B>
|
|
|
|
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
|
|
Fa prefix
|
|
|
|
selects the hashing method to use.
|
|
Fa count
|
|
|
|
controls the CPU time cost of the hash;
|
|
the valid range for
|
|
Fa count
|
|
|
|
and the exact meaning of
|
|
``CPU time cost''
|
|
|
|
depends on the hashing method,
|
|
but larger numbers correspond to more costly hashes.
|
|
Fa rbytes
|
|
|
|
should point to
|
|
Fa nrbytes
|
|
|
|
cryptographically random bytes for use as
|
|
``salt.''
|
|
|
|
<P>
|
|
|
|
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
|
|
``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.
|
|
<P>
|
|
|
|
See
|
|
<A HREF="/cgi-bin/man/man2html?5+crypt">crypt</A>(5)
|
|
|
|
|
|
for other strings that can be used as
|
|
Fa prefix ,
|
|
|
|
and valid values of
|
|
Fa count
|
|
|
|
for each.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>RETURN VALUES</H2>
|
|
|
|
<B>crypt_gensalt</B>
|
|
|
|
|
|
<B>crypt_gensalt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_gensalt_ra</B>
|
|
|
|
return a pointer to an encoded setting string.
|
|
This string will be entirely printable ASCII,
|
|
and will not contain whitespace or the characters
|
|
`<B>:</B>
|
|
|
|
'
|
|
|
|
|
|
`<B>;</B>
|
|
|
|
'
|
|
|
|
|
|
`<B>*</B>
|
|
|
|
'
|
|
|
|
|
|
`<B>!</B>
|
|
|
|
'
|
|
|
|
|
|
or
|
|
`<B>\</B>
|
|
|
|
'
|
|
|
|
|
|
See
|
|
<A HREF="/cgi-bin/man/man2html?5+crypt">crypt</A>(5)
|
|
|
|
|
|
for more detail on the format of this string.
|
|
Upon error, they return a null pointer and set
|
|
<I>errno</I>
|
|
|
|
to an appropriate error code.
|
|
<P>
|
|
|
|
<B>crypt_gensalt</B>
|
|
|
|
places its result in a static storage area,
|
|
which will be overwritten by subsequent calls to
|
|
<B>crypt_gensalt</B>
|
|
|
|
|
|
It is not safe to call
|
|
<B>crypt_gensalt</B>
|
|
|
|
from multiple threads simultaneously.
|
|
However, it
|
|
<I>is</I>
|
|
|
|
safe to pass the string returned by
|
|
<B>crypt_gensalt</B>
|
|
|
|
directly to
|
|
<B>crypt</B>
|
|
|
|
without copying it;
|
|
each function has its own static storage area.
|
|
<P>
|
|
|
|
<B>crypt_gensalt_rn</B>
|
|
|
|
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
|
|
<B>CRYPT_GENSALT_OUTPUT_SIZE</B>
|
|
|
|
|
|
<P>
|
|
|
|
<B>crypt_gensalt_ra</B>
|
|
|
|
allocates memory for its result using
|
|
<A HREF="/cgi-bin/man/man2html?3+malloc">malloc</A>(3).
|
|
|
|
|
|
It should be freed with
|
|
<A HREF="/cgi-bin/man/man2html?3+free">free</A>(3)
|
|
|
|
|
|
after use.
|
|
<P>
|
|
|
|
Upon error, in addition to returning a null pointer,
|
|
<B>crypt_gensalt</B>
|
|
|
|
and
|
|
<B>crypt_gensalt_rn</B>
|
|
|
|
will write an invalid setting string
|
|
to their output buffer, if there is enough space;
|
|
this string will begin with a
|
|
`<B>*</B>
|
|
|
|
'
|
|
|
|
and will not be equal to
|
|
Fa prefix .
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<P>
|
|
|
|
<DT id="1"><B>Er </B>EINVAL
|
|
|
|
|
|
<DD>
|
|
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 .
|
|
|
|
<DT id="2"><B>Er </B>ERANGE
|
|
|
|
|
|
<DD>
|
|
<B>crypt_gensalt_rn</B>
|
|
|
|
only:
|
|
Fa output_size
|
|
|
|
is too small to hold the compiled
|
|
Fa setting
|
|
|
|
string.
|
|
<DT id="3"><B>Er </B>ENOMEM
|
|
|
|
|
|
<DD>
|
|
Failed to allocate internal scratch memory.
|
|
<BR>
|
|
|
|
<B>crypt_gensalt_ra</B>
|
|
|
|
only:
|
|
failed to allocate memory for the compiled
|
|
Fa setting
|
|
|
|
string.
|
|
<DT id="4"><B>Er </B>ENOSYS , EACCES , EIO , <B>etc.</B>
|
|
|
|
|
|
|
|
|
|
<DD>
|
|
Obtaining random bytes from the operating system failed.
|
|
This can only happen when
|
|
Fa rbytes
|
|
|
|
is a null pointer.
|
|
</DL>
|
|
<P>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>FEATURE TEST MACROS</H2>
|
|
|
|
The following macros are defined by
|
|
In crypt.h :
|
|
|
|
<DL COMPACT>
|
|
<P>
|
|
|
|
<DT id="5"><B>CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX</B>
|
|
|
|
|
|
<DD>
|
|
A null pointer can be specified as the
|
|
Fa prefix
|
|
|
|
argument.
|
|
<DT id="6"><B>CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY</B>
|
|
|
|
|
|
<DD>
|
|
A null pointer can be specified as the
|
|
Fa rbytes
|
|
|
|
argument.
|
|
</DL>
|
|
<P>
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>PORTABILITY NOTES</H2>
|
|
|
|
The functions
|
|
<B>crypt_gensalt</B>
|
|
|
|
|
|
<B>crypt_gensalt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_gensalt_ra</B>
|
|
|
|
are not part of any standard.
|
|
They originate with the Openwall project.
|
|
A function with the name
|
|
<B>crypt_gensalt</B>
|
|
|
|
also exists on Solaris 10 and newer, but its prototype and semantics differ.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
The set of supported hashing methods varies considerably from system
|
|
to system.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>ATTRIBUTES</H2>
|
|
|
|
For an explanation of the terms used in this section, see
|
|
<A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A>(7).
|
|
|
|
|
|
<TABLE BORDER>
|
|
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>crypt_gensalt</B>
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Unsafe race:crypt_gensalt<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>crypt_gensalt_rn</B>
|
|
|
|
|
|
<B>crypt_gensalt_ra</B>
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Safe<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
<P>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<A HREF="/cgi-bin/man/man2html?3+crypt">crypt</A>(3),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?3+getpass">getpass</A>(3),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?3+getpwent">getpwent</A>(3),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?3+shadow">shadow</A>(3),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?1+login">login</A>(1),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?1+passwd">passwd</A>(1),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?5+crypt">crypt</A>(5),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?5+passwd">passwd</A>(5),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?5+shadow">shadow</A>(5),
|
|
|
|
|
|
<A HREF="/cgi-bin/man/man2html?8+pam">pam</A>(8)
|
|
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="7"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="8"><A HREF="#lbAC">LIBRARY</A><DD>
|
|
<DT id="9"><A HREF="#lbAD">SYNOPSIS</A><DD>
|
|
<DT id="10"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="11"><A HREF="#lbAF">RETURN VALUES</A><DD>
|
|
<DT id="12"><A HREF="#lbAG">ERRORS</A><DD>
|
|
<DT id="13"><A HREF="#lbAH">FEATURE TEST MACROS</A><DD>
|
|
<DT id="14"><A HREF="#lbAI">PORTABILITY NOTES</A><DD>
|
|
<DT id="15"><A HREF="#lbAJ">ATTRIBUTES</A><DD>
|
|
<DT id="16"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:38 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|