822 lines
12 KiB
HTML
822 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of CRYPT</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>CRYPT</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 , crypt_r , crypt_rn , crypt_ra</B>
|
|
|
|
- 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
|
|
|
|
Fa const char *phrase
|
|
|
|
Fa const char *setting
|
|
|
|
Fc Ft char *
|
|
|
|
|
|
|
|
Fo crypt_r
|
|
|
|
Fa const char *phrase
|
|
|
|
Fa const char *setting
|
|
|
|
Fa struct crypt_data *data
|
|
|
|
Fc Ft char *
|
|
|
|
|
|
|
|
Fo crypt_rn
|
|
|
|
Fa const char *phrase
|
|
|
|
Fa const char *setting
|
|
|
|
Fa struct crypt_data *data
|
|
|
|
Fa int size
|
|
|
|
Fc Ft char *
|
|
|
|
|
|
|
|
Fo crypt_ra
|
|
|
|
Fa const char *phrase
|
|
|
|
Fa const char *setting
|
|
|
|
Fa void **data
|
|
|
|
Fa int *size
|
|
|
|
Fc <A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The
|
|
<B>crypt</B>
|
|
|
|
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
functions irreversibly
|
|
``hash''
|
|
|
|
Fa phrase
|
|
|
|
for storage in the system password database
|
|
(<A HREF="/cgi-bin/man/man2html?5+shadow">shadow</A>(5)
|
|
|
|
)
|
|
|
|
using a cryptographic
|
|
``hashing method.''
|
|
|
|
The result of this operation is called a
|
|
``hashed passphrase''
|
|
|
|
or just a
|
|
``hash.''
|
|
|
|
Hashing methods are described in
|
|
<A HREF="/cgi-bin/man/man2html?5+crypt">crypt</A>(5).
|
|
|
|
|
|
<P>
|
|
|
|
Fa setting
|
|
|
|
controls which hashing method to use,
|
|
and also supplies various parameters to the chosen method,
|
|
most importantly a random
|
|
``salt''
|
|
|
|
which ensures that no two stored hashes are the same,
|
|
even if the
|
|
Fa phrase
|
|
|
|
strings are the same.
|
|
<P>
|
|
|
|
The
|
|
Fa data
|
|
|
|
argument to
|
|
<B>crypt_r</B>
|
|
|
|
is a structure of type
|
|
Vt struct crypt_data .
|
|
|
|
It has at least these fields:
|
|
|
|
<BLOCKQUOTE>
|
|
<PRE>
|
|
struct crypt_data {
|
|
char output[CRYPT_OUTPUT_SIZE];
|
|
char setting[CRYPT_OUTPUT_SIZE];
|
|
char phrase[CRYPT_MAX_PASSPHRASE_SIZE];
|
|
char initialized;
|
|
};
|
|
</PRE>
|
|
</BLOCKQUOTE>
|
|
|
|
<P>
|
|
|
|
Upon a successful return from
|
|
<B>crypt_r</B>
|
|
|
|
|
|
the hashed passphrase will be stored in
|
|
Fa output .
|
|
|
|
Applications are encouraged, but not required, to use the
|
|
Fa phrase
|
|
|
|
and
|
|
Fa setting
|
|
|
|
fields to store the strings that they will pass as
|
|
Fa phrase
|
|
|
|
and
|
|
Fa setting
|
|
|
|
to
|
|
<B>crypt_r</B>
|
|
|
|
|
|
This will make it easier to erase all sensitive data
|
|
after it is no longer needed.
|
|
<P>
|
|
|
|
The
|
|
Fa initialized
|
|
|
|
field must be set to zero before the first time a
|
|
Vt struct crypt_data
|
|
|
|
object is first used in a call to
|
|
Fn crypt_r .
|
|
|
|
We recommend zeroing the entire object,
|
|
not just
|
|
Fa initialized
|
|
|
|
and not just the documented fields,
|
|
before the first use.
|
|
(Of course, do this before storing anything in
|
|
Fa setting
|
|
|
|
and
|
|
Fa phrase . )
|
|
|
|
<P>
|
|
|
|
The
|
|
Fa data
|
|
|
|
argument to
|
|
<B>crypt_rn</B>
|
|
|
|
should also point to a
|
|
Vt struct crypt_data
|
|
|
|
object, and
|
|
Fa size
|
|
|
|
should be the size of that object, cast to
|
|
Vt int .
|
|
|
|
When used with
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
the entire
|
|
Fa data
|
|
|
|
object (except for the
|
|
Fa phrase
|
|
|
|
and
|
|
Fa setting
|
|
|
|
fields) must be zeroed before its first use;
|
|
this is not just a recommendation, as it is for
|
|
<B>crypt_r</B>
|
|
|
|
|
|
Otherwise, the fields of the object have the same uses that they do for
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<P>
|
|
|
|
On the first call to
|
|
<B>crypt_ra</B>
|
|
|
|
|
|
Fa data
|
|
|
|
should be the address of a
|
|
Vt void *
|
|
|
|
variable set to NULL, and
|
|
Fa size
|
|
|
|
should be the address of an
|
|
Vt int
|
|
|
|
variable set to zero.
|
|
<B>crypt_ra</B>
|
|
|
|
will allocate and initialize a
|
|
Vt struct crypt_data
|
|
|
|
object, using
|
|
<A HREF="/cgi-bin/man/man2html?3+malloc">malloc</A>(3),
|
|
|
|
|
|
and write its address and size into the variables pointed to by
|
|
Fa data
|
|
|
|
and
|
|
Fa size .
|
|
|
|
These can be reused in subsequent calls.
|
|
After the application is done hashing passphrases,
|
|
it should deallocate the
|
|
Vt struct crypt_data
|
|
|
|
object using
|
|
<A HREF="/cgi-bin/man/man2html?3+free">free</A>(3).
|
|
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H2>RETURN VALUES</H2>
|
|
|
|
Upon successful completion,
|
|
<B>crypt</B>
|
|
|
|
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
return a pointer to a string which encodes both the hashed passphrase,
|
|
and the settings that were used to encode it.
|
|
This string is directly usable as
|
|
Fa setting
|
|
|
|
in other calls to
|
|
<B>crypt</B>
|
|
|
|
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
|
|
and as
|
|
Fa prefix
|
|
|
|
in calls to
|
|
<B>crypt_gensalt</B>
|
|
|
|
|
|
<B>crypt_gensalt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_gensalt_ra</B>
|
|
|
|
|
|
It 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 hashed passphrases.
|
|
<P>
|
|
|
|
<B>crypt</B>
|
|
|
|
places its result in a static storage area,
|
|
which will be overwritten by subsequent calls to
|
|
<B>crypt</B>
|
|
|
|
|
|
It is not safe to call
|
|
<B>crypt</B>
|
|
|
|
from multiple threads simultaneously.
|
|
<P>
|
|
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
place their result in the
|
|
Fa output
|
|
|
|
field of their
|
|
Fa data
|
|
|
|
argument.
|
|
It is safe to call them from multiple threads simultaneously,
|
|
as long as a separate
|
|
Fa data
|
|
|
|
object is used for each thread.
|
|
<P>
|
|
|
|
Upon error,
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
write an
|
|
<I>invalid</I>
|
|
|
|
hashed passphrase to the
|
|
Fa output
|
|
|
|
field of their
|
|
Fa data
|
|
|
|
argument, and
|
|
<B>crypt</B>
|
|
|
|
writes an invalid hash to its static storage area.
|
|
This string will be shorter than 13 characters,
|
|
will begin with a
|
|
`<B>*</B>
|
|
|
|
'
|
|
|
|
|
|
and will not compare equal to
|
|
Fa setting .
|
|
|
|
<P>
|
|
|
|
Upon error,
|
|
<B>crypt_rn</B>
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
return a null pointer.
|
|
<B>crypt_r</B>
|
|
|
|
and
|
|
<B>crypt</B>
|
|
|
|
may also return a null pointer,
|
|
or they may return a pointer to the invalid hash,
|
|
depending on how libcrypt was configured.
|
|
(The option to return the invalid hash is for compatibility
|
|
with old applications that assume that
|
|
<B>crypt</B>
|
|
|
|
cannot return a null pointer.
|
|
See
|
|
Sx PORTABILITY NOTES
|
|
|
|
below.)
|
|
<P>
|
|
|
|
All four functions set
|
|
<I>errno</I>
|
|
|
|
when they fail.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<P>
|
|
|
|
<DT id="1"><B>Er </B>EINVAL
|
|
|
|
|
|
<DD>
|
|
Fa setting
|
|
|
|
is invalid, or requests a hashing method that is not supported.
|
|
<DT id="2"><B>Er </B>ERANGE
|
|
|
|
|
|
<DD>
|
|
Fa phrase
|
|
|
|
is too long
|
|
(more than
|
|
<B>CRYPT_MAX_PASSPHRASE_SIZE</B>
|
|
|
|
characters; some hashing methods may have lower limits).
|
|
<BR>
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
only:
|
|
Fa size
|
|
|
|
is too small for the hashing method requested by
|
|
Fa setting .
|
|
|
|
<DT id="3"><B>Er </B>ENOMEM
|
|
|
|
|
|
<DD>
|
|
Failed to allocate internal scratch memory.
|
|
<BR>
|
|
|
|
<B>crypt_ra</B>
|
|
|
|
only: failed to allocate memory for
|
|
Fa data .
|
|
|
|
<DT id="4"><B>Er </B>ENOSYS <B>or Er </B>EOPNOTSUPP
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<DD>
|
|
Hashing passphrases is not supported at all on this installation,
|
|
or the hashing method requested by
|
|
Fa setting
|
|
|
|
is not supported.
|
|
These error codes are not used by this version of libcrypt,
|
|
but may be encountered on other systems.
|
|
</DL>
|
|
<P>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>PORTABILITY NOTES</H2>
|
|
|
|
<B>crypt</B>
|
|
|
|
is included in POSIX, but
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
are not part of any standard.
|
|
<P>
|
|
|
|
POSIX does not specify any hashing methods,
|
|
and does not require hashed passphrases to be portable between systems.
|
|
In practice, hashed passphrases are portable
|
|
as long as both systems support the hashing method that was used.
|
|
However, the set of supported hashing methods
|
|
varies considerably from system to system.
|
|
<P>
|
|
|
|
The behavior of
|
|
<B>crypt</B>
|
|
|
|
on errors isn't well standardized.
|
|
Some implementations simply can't fail
|
|
(except by crashing the program),
|
|
others return a null pointer or a fixed string.
|
|
Most implementations don't set
|
|
<I>errno</I>
|
|
|
|
|
|
but some do.
|
|
POSIX specifies returning a null pointer and setting
|
|
<I>errno</I>
|
|
|
|
|
|
but it defines only one possible error,
|
|
Er ENOSYS ,
|
|
|
|
in the case where
|
|
<B>crypt</B>
|
|
|
|
is not supported at all.
|
|
Some older applications are not prepared to handle null pointers
|
|
returned by
|
|
<B>crypt</B>
|
|
|
|
|
|
The behavior described above for this implementation,
|
|
setting
|
|
<I>errno</I>
|
|
|
|
and returning an invalid hashed passphrase different from
|
|
Fa setting ,
|
|
|
|
is chosen to make these applications fail closed when an error occurs.
|
|
<P>
|
|
|
|
Due to historical restrictions
|
|
on the export of cryptographic software from the USA,
|
|
<B>crypt</B>
|
|
|
|
is an optional POSIX component.
|
|
Applications should therefore be prepared for
|
|
<B>crypt</B>
|
|
|
|
not to be available,
|
|
or to always fail (setting
|
|
<I>errno</I>
|
|
|
|
to
|
|
Er ENOSYS )
|
|
|
|
at runtime.
|
|
<P>
|
|
|
|
POSIX specifies that
|
|
<B>crypt</B>
|
|
|
|
is declared in
|
|
In unistd.h ,
|
|
|
|
but only if the macro
|
|
<B>_XOPEN_CRYPT</B>
|
|
|
|
is defined and has a value greater than or equal to zero.
|
|
Since libcrypt does not provide
|
|
In unistd.h ,
|
|
|
|
it declares
|
|
<B>crypt</B>
|
|
|
|
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
in
|
|
In crypt.h
|
|
|
|
instead.
|
|
<P>
|
|
|
|
On a minority of systems (notably recent versions of Solaris),
|
|
<B>crypt</B>
|
|
|
|
uses a thread-specific static storage buffer,
|
|
which makes it safe to call from multiple threads simultaneously,
|
|
but does not prevent each call within a thread
|
|
from overwriting the results of the previous one.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
Some implementations of
|
|
<B>crypt</B>
|
|
|
|
|
|
upon error,
|
|
return an invalid hash that is stored in a read-only location
|
|
or only initialized once,
|
|
which means that it is only safe to erase the buffer pointed to by the
|
|
<B>crypt</B>
|
|
|
|
return value if an error did not occur.
|
|
<P>
|
|
|
|
Vt struct crypt_data
|
|
|
|
may be quite large (32kB in this implementation of libcrypt;
|
|
over 128kB in some other implementations).
|
|
This is large enough that it may be unwise to allocate it on the stack.
|
|
<P>
|
|
|
|
Some recently designed hashing methods need even more scratch memory,
|
|
but the
|
|
<B>crypt_r</B>
|
|
|
|
interface makes it impossible to change the size of
|
|
Vt struct crypt_data
|
|
|
|
without breaking binary compatibility.
|
|
The
|
|
<B>crypt_rn</B>
|
|
|
|
interface could accommodate larger allocations for specific hashing methods,
|
|
but the caller of
|
|
<B>crypt_rn</B>
|
|
|
|
has no way of knowing how much memory to allocate.
|
|
<B>crypt_ra</B>
|
|
|
|
does the allocation itself,
|
|
but can only make a single call to
|
|
<A HREF="/cgi-bin/man/man2html?3+malloc">malloc</A>(3).
|
|
|
|
|
|
<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</B>
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Unsafe race:crypt<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>crypt_r</B>
|
|
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
|
|
<B>crypt_ra</B>
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Safe<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
<P>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>HISTORY</H2>
|
|
|
|
A rotor-based
|
|
<B>crypt</B>
|
|
|
|
function appeared in
|
|
AT&T System
|
|
v6 .
|
|
The
|
|
``traditional''
|
|
|
|
DES-based
|
|
<B>crypt</B>
|
|
|
|
first appeared in
|
|
AT&T System
|
|
v7 .
|
|
<P>
|
|
|
|
<B>crypt_r</B>
|
|
|
|
originates with the GNU C Library.
|
|
There's also a
|
|
<B>crypt_r</B>
|
|
|
|
function on HP-UX and MKS Toolkit, but the prototypes and semantics
|
|
differ.
|
|
<P>
|
|
|
|
<B>crypt_rn</B>
|
|
|
|
and
|
|
<B>crypt_ra</B>
|
|
|
|
originate with the Openwall project.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
crypt_gensalt3,
|
|
|
|
|
|
<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="5"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="6"><A HREF="#lbAC">LIBRARY</A><DD>
|
|
<DT id="7"><A HREF="#lbAD">SYNOPSIS</A><DD>
|
|
<DT id="8"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="9"><A HREF="#lbAF">RETURN VALUES</A><DD>
|
|
<DT id="10"><A HREF="#lbAG">ERRORS</A><DD>
|
|
<DT id="11"><A HREF="#lbAH">PORTABILITY NOTES</A><DD>
|
|
<DT id="12"><A HREF="#lbAI">BUGS</A><DD>
|
|
<DT id="13"><A HREF="#lbAJ">ATTRIBUTES</A><DD>
|
|
<DT id="14"><A HREF="#lbAK">HISTORY</A><DD>
|
|
<DT id="15"><A HREF="#lbAL">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>
|