path: root/src/library/bcrypt/crypt.3

.\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.
.\" 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 (c) 2000-2011 Solar Designer 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.
.\"
.\" This manual page in its current form is intended for use on systems
.\" based on the GNU C Library with crypt_blowfish patched into libcrypt.
.\"
.TH CRYPT 3 "July 16, 2011" "Openwall Project" "Library functions"
.ad l
.\" No macros in NAME to keep makewhatis happy.
.SH NAME
\fBcrypt\fR, \fBcrypt_r\fR, \fBcrypt_rn\fR, \fBcrypt_ra\fR,
\fBcrypt_gensalt\fR, \fBcrypt_gensalt_rn\fR, \fBcrypt_gensalt_ra\fR
\- password hashing
.SH SYNOPSIS
.B #define _XOPEN_SOURCE
.br
.B #include <unistd.h>
.sp
.in +8
.ti -8
.BI "char *crypt(const char *" key ", const char *" setting );
.in -8
.sp
.B #define _GNU_SOURCE
.br
.B #include <crypt.h>
.sp
.in +8
.ti -8
.BI "char *crypt_r(const char *" key ", const char *" setting ", struct crypt_data *" data );
.in -8
.sp
.B #define _OW_SOURCE
.br
.B #include <crypt.h>
.sp
.in +8
.ti -8
.BI "char *crypt_rn(const char *" key ", const char *" setting ", void *" data ", int " size );
.ti -8
.BI "char *crypt_ra(const char *" key ", const char *" setting ", void **" data ", int *" size );
.ti -8
.BI "char *crypt_gensalt(const char *" prefix ", unsigned long " count ", const char *" input ", int " size );
.ti -8
.BI "char *crypt_gensalt_rn(const char *" prefix ", unsigned long " count ", const char *" input ", int " size ", char *" output ", int " output_size );
.ti -8
.BI "char *crypt_gensalt_ra(const char *" prefix ", unsigned long " count ", const char *" input ", int " size );
.ad b
.de crypt
.BR crypt ,
.BR crypt_r ,
.BR crypt_rn ", \\$1"
.ie "\\$2"" .B crypt_ra
.el .BR crypt_ra "\\$2"
..
.de crypt_gensalt
.BR crypt_gensalt ,
.BR crypt_gensalt_rn ", \\$1"
.ie "\\$2"" .B crypt_gensalt_ra
.el .BR crypt_gensalt_ra "\\$2"
..
.SH DESCRIPTION
The
.crypt and
functions calculate a cryptographic hash function of
.I key
with one of a number of supported methods as requested with
.IR setting ,
which is also used to pass a salt and possibly other parameters to
the chosen method.
The hashing methods are explained below.
.PP
Unlike
.BR crypt ,
the functions
.BR crypt_r ,
.BR crypt_rn " and"
.B crypt_ra
are reentrant.
They place their result and possibly their private data in a
.I data
area of
.I size
bytes as passed to them by an application and/or in memory they
allocate dynamically.  Some hashing algorithms may use the data area to
cache precomputed intermediate values across calls.  Thus, applications
must properly initialize the data area before its first use.
.B crypt_r
requires that only
.I data->initialized
be reset to zero;
.BR crypt_rn " and " crypt_ra
require that either the entire data area is zeroed or, in the case of
.BR crypt_ra ,
.I *data
is NULL.  When called with a NULL
.I *data
or insufficient
.I *size
for the requested hashing algorithm,
.B crypt_ra
uses
.BR realloc (3)
to allocate the required amount of memory dynamically.  Thus,
.B crypt_ra
has the additional requirement that
.IR *data ,
when non-NULL, must point to an area allocated either with a previous
call to
.B crypt_ra
or with a
.BR malloc (3)
family call.
The memory allocated by
.B crypt_ra
should be freed with
.BR free "(3)."
.PP
The
.crypt_gensalt and
functions compile a string for use as
.I setting
\- with the given
.I prefix
(used to choose a hashing method), the iteration
.I count
(if supported by the chosen method) and up to
.I size
cryptographically random
.I input
bytes for use as the actual salt.
If
.I count
is 0, a low default will be picked.
The random bytes may be obtained from
.BR /dev/urandom .
Unlike
.BR crypt_gensalt ,
the functions
.BR crypt_gensalt_rn " and " crypt_gensalt_ra
are reentrant.
.B crypt_gensalt_rn
places its result in the
.I output
buffer of
.I output_size
bytes.
.B crypt_gensalt_ra
allocates memory for its result dynamically.  The memory should be
freed with
.BR free "(3)."
.SH RETURN VALUE
Upon successful completion, the functions
.crypt and
return a pointer to a string containing the setting that was actually used
and a printable encoding of the hash function value.
The entire string is directly usable as
.I setting
with other calls to
.crypt and
and as
.I prefix
with calls to
.crypt_gensalt and .
.PP
The behavior of
.B crypt
on errors isn't well standardized.  Some implementations simply can't fail
(unless the process dies, in which case they obviously can't return),
others return NULL or a fixed string.  Most implementations don't set
.IR errno ,
but some do.  SUSv2 specifies only returning NULL and setting
.I errno
as a valid behavior, and defines only one possible error
.RB "(" ENOSYS ,
"The functionality is not supported on this implementation.")
Unfortunately, most existing applications aren't prepared to handle
NULL returns from
.BR crypt .
The description below corresponds to this implementation of
.BR crypt " and " crypt_r
only, and to
.BR crypt_rn " and " crypt_ra .
The behavior may change to match standards, other implementations or
existing applications.
.PP
.BR crypt " and " crypt_r
may only fail (and return) when passed an invalid or unsupported
.IR setting ,
in which case they return a pointer to a magic string that is
shorter than 13 characters and is guaranteed to differ from
.IR setting .
This behavior is safe for older applications which assume that
.B crypt
can't fail, when both setting new passwords and authenticating against
existing password hashes.
.BR crypt_rn " and " crypt_ra
return NULL to indicate failure.  All four functions set
.I errno
when they fail.
.PP
The functions
.crypt_gensalt and
return a pointer to the compiled string for
.IR setting ,
or NULL on error in which case
.I errno
is set.
.SH ERRORS
.TP
.B EINVAL
.crypt "" :
.I setting
is invalid or not supported by this implementation;
.sp
.crypt_gensalt "" :
.I prefix
is invalid or not supported by this implementation;
.I count
is invalid for the requested
.IR prefix ;
the input
.I size
is insufficient for the smallest valid salt with the requested
.IR prefix ;
.I input
is NULL.
.TP
.B ERANGE
.BR crypt_rn :
the provided data area
.I size
is insufficient for the requested hashing algorithm;
.sp
.BR crypt_gensalt_rn :
.I output_size
is too small to hold the compiled
.I setting
string.
.TP
.B ENOMEM
.B crypt
(original glibc only):
failed to allocate memory for the output buffer (which subsequent calls
would re-use);
.sp
.BR crypt_ra :
.I *data
is NULL or
.I *size
is insufficient for the requested hashing algorithm and
.BR realloc (3)
failed;
.sp
.BR crypt_gensalt_ra :
failed to allocate memory for the compiled
.I setting
string.
.TP
.B ENOSYS
.B crypt
(SUSv2):
the functionality is not supported on this implementation;
.sp
.BR crypt ,
.B crypt_r
(glibc 2.0 to 2.0.1 only):
.de no-crypt-add-on
the crypt add-on is not compiled in and
.I setting
requests something other than the MD5-based algorithm.
..
.no-crypt-add-on
.TP
.B EOPNOTSUPP
.BR crypt ,
.B crypt_r
(glibc 2.0.2 to 2.1.3 only):
.no-crypt-add-on
.SH HASHING METHODS
The implemented hashing methods are intended specifically for processing
user passwords for storage and authentication;
they are at best inefficient for most other purposes.
.PP
It is important to understand that password hashing is not a replacement
for strong passwords.
It is always possible for an attacker with access to password hashes
to try guessing candidate passwords against the hashes.
There are, however, certain properties a password hashing method may have
which make these key search attacks somewhat harder.
.PP
All of the hashing methods use salts such that the same
.I key
may produce many possible hashes.
Proper use of salts may defeat a number of attacks, including:
.TP
1.
The ability to try candidate passwords against multiple hashes at the
price of one.
.TP
2.
The use of pre-hashed lists of candidate passwords.
.TP
3.
The ability to determine whether two users (or two accounts of one user)
have the same or different passwords without actually having to guess
one of the passwords.
.PP
The key search attacks depend on computing hashes of large numbers of
candidate passwords.
Thus, the computational cost of a good password hashing method must be
high \- but of course not too high to render it impractical.
.PP
All hashing methods implemented within the
.crypt and
interfaces use multiple iterations of an underlying cryptographic
primitive specifically in order to increase the cost of trying a
candidate password.
Unfortunately, due to hardware improvements, the hashing methods which
have a fixed cost become increasingly less secure over time.
.PP
In addition to salts, modern password hashing methods accept a variable
iteration
.IR count .
This makes it possible to adapt their cost to the hardware improvements
while still maintaining compatibility.
.PP
The following hashing methods are or may be implemented within the
described interfaces:
.PP
.de hash
.ad l
.TP
.I prefix
.ie "\\$1"" \{\
"" (empty string);
.br
a string matching ^[./0-9A-Za-z]{2} (see
.BR regex (7))
.\}
.el "\\$1"
.TP
.B Encoding syntax
\\$2
.TP
.B Maximum password length
\\$3 (uses \\$4-bit characters)
.TP
.B Effective key size
.ie "\\$5"" limited by the hash size only
.el up to \\$5 bits
.TP
.B Hash size
\\$6 bits
.TP
.B Salt size
\\$7 bits
.TP
.B Iteration count
\\$8
.ad b
..
.ti -2
.B Traditional DES-based
.br
This method is supported by almost all implementations of
.BR crypt .
Unfortunately, it no longer offers adequate security because of its many
limitations.
Thus, it should not be used for new passwords unless you absolutely have
to be able to migrate the password hashes to other systems.
.hash "" "[./0-9A-Za-z]{13}" 8 7 56 64 12 25
.PP
.ti -2
.B Extended BSDI-style DES-based
.br
This method is used on BSDI and is also available on at least NetBSD,
OpenBSD, and FreeBSD due to the use of David Burren's FreeSec library.
.hash _ "_[./0-9A-Za-z]{19}" unlimited 7 56 64 24 "1 to 2**24-1 (must be odd)"
.PP
.ti -2
.B FreeBSD-style MD5-based
.br
This is Poul-Henning Kamp's MD5-based password hashing method originally
developed for FreeBSD.
It is currently supported on many free Unix-like systems, on Solaris 10,
and it is a part of the official glibc.
Its main disadvantage is the fixed iteration count, which is already
too low for the currently available hardware.
.hash "$1$" "\e$1\e$[^$]{1,8}\e$[./0-9A-Za-z]{22}" unlimited 8 "" 128 "6 to 48" 1000
.PP
.ti -2
.BR "OpenBSD-style Blowfish-based" " (" bcrypt )
.br
.B bcrypt
was originally developed by Niels Provos and David Mazieres for OpenBSD
and is also supported on recent versions of FreeBSD and NetBSD,
on Solaris 10, and on several GNU/*/Linux distributions.
It is, however, not a part of the official glibc.
.PP
While both
.B bcrypt
and the BSDI-style DES-based hashing offer a variable iteration count,
.B bcrypt
may scale to even faster hardware, doesn't allow for certain optimizations
specific to password cracking only, doesn't have the effective key size
limitation, and uses 8-bit characters in passwords.
.hash "$2y$" "\e$2[axy]\e$[0-9]{2}\e$[./A-Za-z0-9]{53}" 72 8 "" 184 128 "2**4 to 2**99 (current implementations are limited to 2**31 iterations)"
.PP
With
.BR bcrypt ,
the
.I count
passed to
.crypt_gensalt and
is the base-2 logarithm of the actual iteration count.
.PP
.B bcrypt
hashes used the "$2a$" prefix since 1997.
However, in 2011 an implementation bug was discovered in crypt_blowfish
(versions up to 1.0.4 inclusive) affecting handling of password characters with
the 8th bit set.
Besides fixing the bug,
to provide for upgrade strategies for existing systems, two new prefixes were
introduced: "$2x$", which fully re-introduces the bug, and "$2y$", which
guarantees correct handling of both 7- and 8-bit characters (same as OpenBSD's
"$2a$").
Unfortunately, the behavior of "$2a$" on password characters with the 8th bit
set has to be considered system-specific.
When generating new password hashes, the "$2y$" prefix should be used.
(If such hashes ever need to be migrated to a system that does not yet support
this new prefix, the prefix in migrated copies of the already-generated hashes
may be changed to "$2a$".)
.PP
.crypt_gensalt and
support the "$2y$" and "$2a$" prefixes (the latter for legacy programs or
configurations), but not "$2x$" (which must not be used for new hashes).
.crypt and
support all three of these prefixes.
.SH PORTABILITY NOTES
Programs using any of these functions on a glibc 2.x system must be
linked against
.BR libcrypt .
However, many Unix-like operating systems and older versions of the
GNU C Library include the
.BR crypt " function in " libc .
.PP
The
.BR crypt_r ,
.BR crypt_rn ,
.BR crypt_ra ,
.crypt_gensalt and
functions are very non-portable.
.PP
The set of supported hashing methods is implementation-dependent.
.SH CONFORMING TO
The
.B crypt
function conforms to SVID, X/OPEN, and is available on BSD 4.3.
The strings returned by
.B crypt
are not required to be portable among conformant systems.
.PP
.B crypt_r
is a GNU extension.
There's also a
.B crypt_r
function on HP-UX and MKS Toolkit, but the prototypes and semantics differ.
.PP
.B crypt_gensalt
is an Openwall extension.
There's also a
.B crypt_gensalt
function on Solaris 10, but the prototypes and semantics differ.
.PP
.BR crypt_rn ,
.BR crypt_ra ,
.BR crypt_gensalt_rn ,
and
.B crypt_gensalt_ra
are Openwall extensions.
.SH HISTORY
A rotor-based
.B crypt
function appeared in Version 6 AT&T UNIX.
The "traditional"
.B crypt
first appeared in Version 7 AT&T UNIX.
.PP
The
.B crypt_r
function was introduced during glibc 2.0 development.
.SH BUGS
The return values of
.BR crypt " and " crypt_gensalt
point to static buffers that are overwritten by subsequent calls.
These functions are not thread-safe.
.RB ( crypt
on recent versions of Solaris uses thread-specific data and actually is
thread-safe.)
.PP
The strings returned by certain other implementations of
.B crypt
on error may be stored in read-only locations or only initialized once,
which makes it unsafe to always attempt to zero out the buffer normally
pointed to by the
.B crypt
return value as it would otherwise be preferable for security reasons.
The problem could be avoided with the use of
.BR crypt_r ,
.BR crypt_rn ,
or
.B crypt_ra
where the application has full control over output buffers of these functions
(and often over some of their private data as well).
Unfortunately, the functions aren't (yet?) available on platforms where
.B crypt
has this undesired property.
.PP
Applications using the thread-safe
.B crypt_r
need to allocate address space for the large (over 128 KB)
.I struct crypt_data
structure.  Each thread needs a separate instance of the structure.  The
.B crypt_r
interface makes it impossible to implement a hashing algorithm which
would need to keep an even larger amount of private data, without breaking
binary compatibility.
.B crypt_ra
allows for dynamically increasing the allocation size as required by the
hashing algorithm that is actually used.  Unfortunately,
.B crypt_ra
is even more non-portable than
.BR crypt_r .
.PP
Multi-threaded applications or library functions which are meant to be
thread-safe should use
.BR crypt_gensalt_rn " or " crypt_gensalt_ra
rather than
.BR crypt_gensalt .
.SH SEE ALSO
.BR login (1),
.BR passwd (1),
.BR crypto (3),
.BR encrypt (3),
.BR free (3),
.BR getpass (3),
.BR getpwent (3),
.BR malloc (3),
.BR realloc (3),
.BR shadow (3),
.BR passwd (5),
.BR shadow (5),
.BR regex (7),
.BR pam (8)
.sp
Niels Provos and David Mazieres.  A Future-Adaptable Password Scheme.
Proceedings of the 1999 USENIX Annual Technical Conference, June 1999.
.br
http://www.usenix.org/events/usenix99/provos.html
.sp
Robert Morris and Ken Thompson.  Password Security: A Case History.
Unix Seventh Edition Manual, Volume 2, April 1978.
.br
http://plan9.bell-labs.com/7thEdMan/vol2/password