Changeset View
Standalone View
lib/libcrypt/crypt.3
.\" FreeSec: libcrypt for NetBSD | .\" FreeSec: libcrypt for NetBSD | ||||
.\" | .\" | ||||
.\" Copyright (c) 1994 David Burren | .\" Copyright (c) 1994 David Burren | ||||
.\" Copyright (c) 2015 Derek Marcotte | |||||
.\" All rights reserved. | .\" All rights reserved. | ||||
.\" | .\" | ||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||
.\" are met: | .\" are met: | ||||
.\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | ||||
.\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer in the | .\" notice, this list of conditions and the following disclaimer in the | ||||
.\" documentation and/or other materials provided with the distribution. | .\" documentation and/or other materials provided with the distribution. | ||||
.\" 3. Neither the name of the author nor the names of other contributors | .\" 3. Neither the name of the author nor the names of other contributors | ||||
.\" may be used to endorse or promote products derived from this software | .\" may be used to endorse or promote products derived from this software | ||||
.\" without specific prior written permission. | .\" without specific prior written permission. | ||||
.\" | .\" | ||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND | ||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE | ||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd August 10, 2016 | .Dd August 16, 2018 | ||||
.Dt CRYPT 3 | .Dt CRYPT 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm crypt | .Nm crypt , | ||||
.Nd Trapdoor encryption | .Nm crypt_makesalt , | ||||
.Nm crypt_get_format , | |||||
.Nm crypt_set_format | |||||
.Nd "library for password hashing" | |||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libcrypt | .Lb libcrypt | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In unistd.h | .In unistd.h | ||||
.Ft char * | .Ft "char *" | ||||
.Fn crypt "const char *key" "const char *salt" | .Fn crypt "const char *key" "const char *salt" | ||||
.Ft char * | .Ft char * | ||||
jmg: why was previous char * enclosed in quotes, but not this one? | |||||
.Fn crypt_r "const char *key" "const char *salt" "struct crypt_data *data" | .Fn crypt_r "const char *key" "const char *salt" "struct crypt_data *data" | ||||
.Ft const char * | .Ft "int" | ||||
.Fn crypt_makesalt "char *output" "const char *format" "size_t *out_len" | |||||
.Ft "const char *" | |||||
.Fn crypt_get_format "void" | .Fn crypt_get_format "void" | ||||
.Ft int | .Ft "int" | ||||
.Fn crypt_set_format "const char *string" | .Fn crypt_set_format "const char *string" | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn crypt | .Nm libcrypt | ||||
function performs password hashing with additional code added to | library covers functions related to password hashing. | ||||
deter key search attempts. | .Pp | ||||
Different algorithms can be used to | Password hashing is different than a standard one way hash function. | ||||
in the hash. | Password hashing tries to make it difficult to recover a low-entropy key | ||||
jmgUnsubmitted Not Done Inline ActionsI'd combine these two statements, into: jmg: I'd combine these two statements, into:
Password hashing is different than a standard one way… | |||||
.\" | .Pq e.g., a typed password | ||||
.\" NOTICE: | from the resultant output hash. | ||||
.\" If you add more algorithms, make sure to update this list | Offline recovery by exhaustive key search | ||||
.\" and the default used for the Traditional format, below. | .Pq brute-force and dictionary attacks | ||||
.\" | is stymied by the password hashing being one-way, and often computationally expensive. | ||||
Currently these include the | Different algorithms can be selected to produce the password hash, with varying ability to effectively deter key search attempts. | ||||
.Tn NBS | .Pp | ||||
.Tn Data Encryption Standard (DES) , | The hashing algorithm to be used for an invocation of crypt is chosen by supplying a salt parameter of a particular format. | ||||
.Tn MD5 | The algorithms currently supported are: | ||||
hash, | .Sx bcrypt , | ||||
.Tn NT-Hash | .Sx sha512-crypt , | ||||
.Pq compatible with Microsoft's NT scheme | .Sx sha256-crypt , | ||||
.Sx md5-crypt , | |||||
.Sx DES Extended Format , | |||||
.Sx Traditional DES Format , | |||||
and | and | ||||
.Tn Blowfish . | .Sx NT-Hash . | ||||
The algorithm used will depend upon the format of the Salt | |||||
.Po | |||||
following | |||||
the Modular Crypt Format | |||||
.Pq MCF | |||||
.Pc , | |||||
if | |||||
.Tn DES | |||||
and/or | |||||
.Tn Blowfish | |||||
is installed or not, and whether | |||||
.Fn crypt_set_format | |||||
has been called to change the default. | |||||
.Pp | .Pp | ||||
Current computational capabilities make all but the bcrypt and sha-crypt families known to be susceptible to exhaustive key searches. | |||||
The tune-able work factor of the bcrypt and sha-crypt families has allowed them to be set to be more computationally intensive over time. | |||||
The use of the other families is not recommended at this time, but are maintained for legacy compatibility. | |||||
.Pp | |||||
The first argument to | The first argument to | ||||
.Nm | .Fn crypt | ||||
is the data to hash | is the | ||||
.Fa key | |||||
to hash | |||||
.Pq usually a password , | .Pq usually a password , | ||||
in a | as a NUL-terminated string. | ||||
.Dv NUL Ns -terminated | The second is the | ||||
string. | .Fa salt . | ||||
The second is the salt, in one of three forms: | A salt is a random value that assists in complicating offline recovery. | ||||
The length and format of the salt, and how it will be used is algorithm dependent. | |||||
For best results, specify at least sixteen characters of salt. | |||||
.Pp | .Pp | ||||
.Bl -tag -width Traditional -compact -offset indent | If the salt begins with the string | ||||
.It Extended | .Qq $digit , | ||||
then the | |||||
.Sx Modular Crypt Format | |||||
is used. | |||||
If it begins with an underscore | If it begins with an underscore | ||||
.Pq Dq _ | .Qq _ , | ||||
then the | then the | ||||
.Tn DES | .Sx DES Extended Format | ||||
Extended Format | is used. | ||||
is used in interpreting both the key and the salt, as outlined below. | If the salt is 2 or 13 characters and includes only 0-9, a-z, A-Z a dot . or a slash /, then | ||||
.It Modular | .Sx Traditional DES Format | ||||
If it begins with the string | is used. | ||||
.Dq $digit$ | If none of these conditions are true, crypt will use the default hash function set by crypt_set_format, | ||||
then the Modular Crypt Format is used, as outlined below. | .Pq or Traditional DES Format if no default has been set, for systems with DES support . | ||||
.It Traditional | |||||
If neither of the above is true, it assumes the Traditional Format, | |||||
using the entire string as the salt | |||||
.Pq or the first portion . | |||||
.El | |||||
.Pp | .Pp | ||||
All routines are designed to be time-consuming. | |||||
.Ss DES Extended Format: | |||||
The | The | ||||
.Ar key | .Fn crypt_makesalt | ||||
is divided into groups of 8 characters | function populates an | ||||
.Pq the last group is NUL-padded | .Fa output | ||||
and the low-order 7 bits of each character | buffer with a newly generated salt for the specified valid | ||||
.Pq 56 bits per group | .Fa format . | ||||
are used to form the | The size of the pre-allocated buffer is passed via | ||||
.Tn DES | .Fa out_len . | ||||
key as follows: | If the output buffer is too small, the required size is set in | ||||
the first group of 56 bits becomes the initial | .Fa out_len . | ||||
.Tn DES | |||||
key. | |||||
For each additional group, the XOR of the encryption of the current | |||||
.Tn DES | |||||
key with itself and the group bits becomes the next | |||||
.Tn DES | |||||
key. | |||||
.Pp | .Pp | ||||
The salt is a 9-character array consisting of an underscore followed | |||||
by 4 bytes of iteration count and 4 bytes of salt. | |||||
These are encoded as printable characters, 6 bits per character, | |||||
least significant character first. | |||||
The values 0 to 63 are encoded as | |||||
.Dq ./0-9A-Za-z . | |||||
This allows 24 bits for both | |||||
.Fa count | |||||
and | |||||
.Fa salt . | |||||
.Pp | |||||
The | The | ||||
.Fa salt | .Fn crypt_get_format | ||||
introduces disorder in the | function returns a constant string that represents the name of the algorithm set as the default. | ||||
.Tn DES | Its use is deprecated. | ||||
jmgUnsubmitted Not Done Inline ActionsWhat should be used instead? jmg: What should be used instead? | |||||
algorithm in one of 16777216 or 4096 possible ways | |||||
.Po | |||||
i.e., with 24 or 12 bits: if bit | |||||
.Em i | |||||
of the | |||||
.Ar salt | |||||
is set, then bits | |||||
.Em i | |||||
and | |||||
.Em i+24 | |||||
are swapped in the | |||||
.Tn DES | |||||
E-box output | |||||
.Pc . | |||||
.Pp | .Pp | ||||
The | The | ||||
.Tn DES | .Fn crypt_set_format | ||||
key is used to encrypt a 64-bit constant using | function sets the default encoding | ||||
.Ar count | .Fa format | ||||
iterations of | according to the supplied string. | ||||
.Tn DES . | Its use is deprecated. | ||||
The value returned is a | |||||
.Dv NUL Ns -terminated | |||||
string, 20 or 13 bytes | |||||
.Pq plus NUL | |||||
in length, consisting of the | |||||
.Ar salt | |||||
followed by the encoded 64-bit encryption. | |||||
.Ss Modular crypt: | |||||
If the salt begins with the string | |||||
.Fa $digit$ | |||||
then the Modular Crypt Format is used. | |||||
The | |||||
.Fa digit | |||||
represents which algorithm is used in encryption. | |||||
Following the token is | |||||
the actual salt to use in the encryption. | |||||
The maximum length of the salt used depends upon the module. | |||||
The salt must be terminated with the end of the string character | |||||
.Pq NUL | |||||
or a dollar sign. | |||||
Any characters after the dollar sign are ignored. | |||||
.Pp | .Pp | ||||
Currently supported algorithms are: | The salts, formats, and algorithms are outlined below. | ||||
.Sh Modular Crypt Format | |||||
Modular Crypt Format is the current standard way to describe which algorithm and parameters to use for a particular crypt invocation. | |||||
Salts that are prefixed with $digit are using the modular crypt format. | |||||
jmgUnsubmitted Not Done Inline Actionsconcerted that it's not listed as $digit$ or $digit[variant]$, because this means that we cannot have more than 10 variants.. as $11$ will match md5-crypt per this spec. We are already up to 6... jmg: concerted that it's not listed as $digit$ or $digit[variant]$, because this means that we… | |||||
The prefix selects the algorithm to use. | |||||
Valid prefixes are: | |||||
.Bl -column -offset indent ".Sy Prefix" ".Sy Algorithm" | |||||
.It Sy Prefix Ta Sy Algorithm | |||||
.It Li $1$ Ta | |||||
.Sx md5-crypt | |||||
.It Li $2 Ta | |||||
.Sx bcrypt | |||||
.It Li $3$ Ta | |||||
.Sx NT-Hash | |||||
.It Li $5$ Ta | |||||
.Sx sha256-crypt | |||||
.It Li $6$ Ta | |||||
.Sx sha512-crypt | |||||
.El | |||||
.Pp | .Pp | ||||
.Bl -enum -compact -offset indent | Everything following the prefix in the salt parameter is algorithm dependent, but includes things like work factor, and an actual salt | ||||
.It | .Pq random value for that particular invocation . | ||||
MD5 | .Ss md5-crypt | ||||
.It | .Bl -column ".Sy Output Hash Example:" ".Sy 8 characters from the set [a-zA-Z0-9./]" | ||||
Blowfish | .It Li Format Strings : Ta $1$, md5 | ||||
.It | .It Li Salt Format : Ta 8 characters from the set [a-zA-Z0-9./] | ||||
NT-Hash | .It Li Full Salt Example : Ta $1$deadbeef$ | ||||
.It | .It Li Output Hash Example : Ta $1$deadbeef$0Huu6KHrKLVWfqa4WljDE0 | ||||
(unused) | |||||
.It | |||||
SHA-256 | |||||
.It | |||||
SHA-512 | |||||
.El | .El | ||||
.Pp | .Pp | ||||
Other crypt formats may be easily added. | md5-crypt was the default crypt format in | ||||
Done Inline ActionsThis line renders wrong for David's name. imp: This line renders wrong for David's name.
| |||||
An example salt would be: | .Fx for many years, developed by Poul-Henning Kamp. | ||||
.Bl -tag -width 6n -offset indent | .Pp | ||||
jmgUnsubmitted Not Done Inline Actionsthis should probably be removed, as the next paragraph's It is unclear. jmg: this should probably be removed, as the next paragraph's It is unclear. | |||||
.It Cm "$4$thesalt$rest" | It has seen widespread use in many commercial products, and for a long time was good enough. | ||||
It has a fixed work factor, which means that as computers became faster, the ability to attack it has increased proportionally. | |||||
.Pp | |||||
jmgUnsubmitted Not Done Inline Actionsagain, next paragraph It isn't clear. jmg: again, next paragraph It isn't clear. | |||||
Its use is no longer recommended. | |||||
.Ss bcrypt | |||||
.Bl -column ".Sy Output Hash Example:" ".Sy $2b$08$CCCCCCCCCCCCCCCCCCCCC.HB0zhI4CA576EzokBu6usBUNIQZK6KS" | |||||
.It Li Format Strings : Ta $2$[rounds]$, $2a$[rounds]$, $2b$[rounds]$, blf | |||||
.It Li Salt Format : Ta 16 bytes then base-64 encoded from the set [a-zA-Z0-9./] | |||||
.It Li Full Salt Example : Ta $2b$08$CCCCCCCCCCCCCCCCCCCCC. | |||||
.It Li Output Hash Example : Ta $2b$08$CCCCCCCCCCCCCCCCCCCCC.HB0zhI4CA576EzokBu6usBUNIQZK6KS | |||||
.El | .El | ||||
.Ss Traditional crypt: | |||||
The algorithm used will depend upon whether | |||||
.Fn crypt_set_format | |||||
has been called and whether a global default format has been specified. | |||||
Unless a global default has been specified or | |||||
.Fn crypt_set_format | |||||
has set the format to something else, the built-in default format is | |||||
used. | |||||
This is currently | |||||
.\" | |||||
.\" NOTICE: Also make sure to update this | |||||
.\" | |||||
DES | |||||
if it is available, or MD5 if not. | |||||
.Pp | .Pp | ||||
How the salt is used will depend upon the algorithm for the hash. | bcrypt is the first algorithm to support a tuneable work factor. | ||||
For | It was initially introduced in | ||||
best results, specify at least eight characters of salt. | .Ox , by Niels Provos, based on the Usenix paper "A Future-Adaptable Password Scheme" by Niels Provos and David Mazi\(`eres. | ||||
.Pp | .Pp | ||||
The | There are three variations supported, each with minor bug fixes. | ||||
.Fn crypt_get_format | 2b is the recommended variation. | ||||
function returns a constant string that represents the name of the | |||||
algorithm currently used. | |||||
Valid values are | |||||
.\" | |||||
.\" NOTICE: Also make sure to update this, too, as well | |||||
.\" | |||||
.Ql des , | |||||
.Ql blf , | |||||
.Ql md5 , | |||||
.Ql sha256 , | |||||
.Ql sha512 | |||||
and | |||||
.Ql nth . | |||||
.Pp | .Pp | ||||
The | The work factor is specified by the rounds parameter in the format string. | ||||
These rounds are logarithmic. | |||||
That is, | |||||
.Qq $2b$08$ | |||||
will take approximately twice as long as | |||||
.Qq $2b$07$ | |||||
for the same salt and key. | |||||
04 is the lowest supported work factor, and 31 is the highest. | |||||
.Pp | |||||
When the format string | |||||
.Qq blf | |||||
is specified, it is equivalent to specifying | |||||
.Qq $2b$04$ . | |||||
.Ss NT-Hash | |||||
.Bl -column ".Sy Output Hash Example:" ".Sy $3$sdlksjfdlksjdlfk" | |||||
.It Li Format Strings : Ta $3$, nth | |||||
.It Li Salt Format : Ta no salt | |||||
.It Li Full Salt Example : Ta $3$ | |||||
.It Li Output Hash Example : Ta $3$$cc0fb8a290eebbfe74e7207f2ace5927 | |||||
.El | |||||
.Pp | |||||
nt-hash is supported for compatibility reasons only. | |||||
It is strongly discouraged for any production uses. | |||||
.Ss sha256-crypt | |||||
.Bl -column ".Sy Output Hash Example:" ".Sy $5$saltstring$5B8vYYiY.CVt1RlTTf8KbXBH3hsxY/GNooZaBBGWEc5, $5$rounds=10000$saltstringsaltst$3xv.VbSHBb41AL9AvLeujZkZRBAwqFMz2.opqey6IcA " | |||||
.It Li Format Strings : Ta $5$, $5$rounds=[rounds]$, sha256 | |||||
.It Li Salt Format : Ta 16 characters from the set [a-zA-Z0-9./] | |||||
.It Li Full Salt Examples : Ta $5$saltstring$, $5$rounds=10000$saltstringsaltst$ | |||||
.It Li Output Hash Examples : Ta $5$saltstring$5B8vYYiY.CVt1RlTTf8KbXBH3hsxY/GNooZaBBGWEc5, $5$rounds=10000$saltstringsaltst$3xv.VbSHBb41AL9AvLeujZkZRBAwqFMz2.opqey6IcA | |||||
.El | |||||
.Pp | |||||
sha256 supports a tunable work factor. | |||||
It was developed by Ulrich Drepper of Red Hat, and is detailed in | |||||
.Qq Unix crypt using SHA-256 and SHA-512 . | |||||
.Pp | |||||
From that document: | |||||
.Pp | |||||
.Qo | |||||
Security departments in companies are trying to phase out all uses of MD5. | |||||
They demand a method which is officially sanctioned. | |||||
For US-based users this means tested by the NIST. | |||||
.Pp | |||||
This rules out the use of another already implemented method with limited spread: the use of the Blowfish encryption method. | |||||
The choice comes down to tested encryption | |||||
.Pq 3DES, AES | |||||
jmgUnsubmitted Not Done Inline Actionsspace between 3DES and comma. jmg: space between 3DES and comma. | |||||
or hash sums | |||||
.Pq the SHA family . | |||||
.Qc | |||||
.Pp | |||||
The prepositions in the above statement are misleading. | |||||
Blowfish as a primitive, like 3DES or AES, has stood up to years of scrutinty by the cryptographic communinty. | |||||
bcrypt, the password hashing function, is ubiquitous. | |||||
It also currently provides greater resilience against pipe-lined or GPU-based attacks for the approximate same CPU workload as the sha-crypt family, based on its limited memory requirements. | |||||
This is not expected to remain true with future improvements to GPUs. | |||||
An additional subtle difference between bcrypt and the sha families is that bcrypt's salt is 2^128 bits, while the sha family is 2^96 bits. | |||||
.Pp | |||||
If you require a algorithm that includes NIST sanctioned primitives, choose one of the sha-crypt methods. | |||||
.Pp | |||||
The work factor is specified by the rounds parameter in the format string. | |||||
These rounds are linear. | |||||
That is, | |||||
.Qq $5$rounds=20000$ | |||||
will take approximately twice as long as | |||||
.Qq $5$rounds=10000$ | |||||
for the same salt and key. | |||||
1000 is the minimum number of rounds, 999999999 is the maximum. | |||||
.Pp | |||||
When the format string | |||||
.Qq sha256 , | |||||
or | |||||
.Qq $5$ | |||||
is specified, it is equivalent to specifying | |||||
.Qq $5$rounds=5000$ . | |||||
.Ss sha512-crypt | |||||
.Bl -column ".Sy Output Hash Example:" ".Sy $6$saltstring$svn8UoSVapNtMuq1ukKS4tPQd8iKwSMHWjl/O817G3uBnIFNjnQJuesI68u4OTLiBFdcbYEdFCoEOfaS35inz1, $6$rounds=10000$saltstringsaltst$OW1/O6BYHV6BcXZu8QVeXbDWra3Oeqh0sbHbbMCVNSnCM/UrjmM0Dp8vOuZeHBy/YTBmSK6H9qs/y3RnOaw5v." | |||||
.It Li Format Strings : Ta $6$, $6$rounds=[rounds]$, sha512 | |||||
.It Li Salt Format : Ta 16 characters from the set [a-zA-Z0-9./] | |||||
.It Li Full Salt Examples : Ta $6$saltstring$, $6$rounds=10000$saltstringsaltst$ | |||||
.It Li Output Hash Examples : Ta $6$saltstring$svn8UoSVapNtMuq1ukKS4tPQd8iKwSMHWjl/O817G3uBnIFNjnQJuesI68u4OTLiBFdcbYEdFCoEOfaS35inz1, $6$rounds=10000$saltstringsaltst$OW1/O6BYHV6BcXZu8QVeXbDWra3Oeqh0sbHbbMCVNSnCM/UrjmM0Dp8vOuZeHBy/YTBmSK6H9qs/y3RnOaw5v. | |||||
.El | |||||
sha512 is nearly equivalent to sha256, except that it uses SHA512 as a primitive. | |||||
See Unix crypt using SHA-256 and SHA-512 for more details. | |||||
The details provided in sha256 apply here as well. | |||||
When the format string | |||||
.Qq sha512 , | |||||
or | |||||
.Qq $6$ | |||||
is specified, it is equivalent to specifying | |||||
.Qq $6$rounds=5000$ . | |||||
.Sh DES Extended Format | |||||
The key is divided into groups of 8 characters | |||||
.Pq the last group is NUL-padded | |||||
and the low-order 7 bits of each character | |||||
.Pq 56 bits per group | |||||
are used to form the DES key as follows: the first group of 56 bits becomes the initial DES key. | |||||
For each additional group, the XOR of the encryption of the current DES key with itself and the group bits becomes the next DES key. | |||||
.Pp | |||||
The salt is a 9-character array consisting of an underscore followed by 4 bytes of iteration count and 4 bytes of salt. | |||||
These are encoded as printable characters, 6 bits per character, least significant character first. | |||||
The values 0 to 63 are encoded as | |||||
.Qq ./0-9A-Za-z . | |||||
This allows 24 bits for both count and salt. | |||||
.Pp | |||||
The salt introduces disorder in the DES algorithm in one of 16777216 or 4096 possible ways | |||||
.Pq i.e., with 24 or 12 bits: if bit i of the salt is set, then bits i and i+24 are swapped in the DES E-box output . | |||||
.Pp | |||||
The DES key is used to encrypt a 64-bit constant using count iterations of DES. | |||||
The value returned is a NUL-terminated string, 20 or 13 bytes | |||||
.Pq plus NUL | |||||
in length, consisting of the salt followed by the encoded 64-bit encryption. | |||||
.Sh Traditional DES Format | |||||
The algorithm used will depend upon whether | |||||
.Fn crypt_set_format | .Fn crypt_set_format | ||||
function sets the default encoding format according to the supplied | function sets the default encoding format according to the supplied | ||||
.Fa string . | .Fa string . | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn crypt_r | .Fn crypt_r | ||||
function behaves identically to | function behaves identically to | ||||
.Fn crypt , | .Fn crypt , | ||||
except that the resulting string is stored in | except that the resulting string is stored in | ||||
.Fa data , | .Fa data , | ||||
making it thread-safe. | making it thread-safe. | ||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
The | The | ||||
.Fn crypt | .Fn crypt | ||||
and | and | ||||
.Fn crypt_r | .Fn crypt_r | ||||
functions return a pointer to the encrypted value on success, and NULL on | functions return a pointer to the encrypted value on success, and NULL on | ||||
failure. | failure. | ||||
Note: this is not a standard behaviour, AT&T | Note: this is not a standard behavior, AT&T | ||||
.Fn crypt | .Fn crypt | ||||
will always return a pointer to a string. | will always return a pointer to a string. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn crypt_makesalt | |||||
function will return a 0 on success, or non-zero on failure. | |||||
It may fail in one of two ways. | |||||
If | |||||
.Fa out_len | |||||
Done Inline ActionsPlease use C99 or newer standard for definition instead of K&R main(). delphij: Please use C99 or newer standard for definition instead of K&R main(). | |||||
has changed, the | |||||
.Fa output | |||||
Done Inline ActionsThis is self-inflicted wound. Use crypt_r instead and drop all the locking (crypt is a non-thread safe wrapper of crypt_r). delphij: This is self-inflicted wound. Use crypt_r instead and drop all the locking (crypt is a non… | |||||
Done Inline ActionsThank you for taking the time to review. This has been updated. In fairness, this example pre-dates the crypt_r in FreeBSD by 4+ years. 482254ac_razorfever.net: Thank you for taking the time to review. This has been updated. In fairness, this example pre… | |||||
buffer was not large enough to store the salt. | |||||
The required size will be stored in | |||||
.Fa out_len . | |||||
If | |||||
.Fa out_len | |||||
has not changed, then the | |||||
.Fa format | |||||
passed was invalid. | |||||
Done Inline ActionsSee above. delphij: See above. | |||||
.Pp | |||||
The | |||||
.Fn crypt_set_format | .Fn crypt_set_format | ||||
function will return 1 if the supplied encoding format was valid. | function will return 1 if the supplied encoding format was valid. | ||||
Otherwise, a value of 0 is returned. | Otherwise, a value of 0 is returned. | ||||
.Sh EXAMPLES | |||||
.Bd -literal | |||||
#include <stdio.h> | |||||
#include <string.h> | |||||
#include <unistd.h> | |||||
int main(void) | |||||
{ | |||||
struct crypt_data buf1, buf2; | |||||
char *hash, *check; | |||||
char salt[256]; | |||||
size_t salt_sz; | |||||
salt_sz = sizeof(salt); | |||||
/* Generate a new salt for a crypt format specification. */ | |||||
if (crypt_makesalt(salt, "$2b$08$", &salt_sz)) { | |||||
if (salt_sz != sizeof(salt)) { | |||||
printf("Buffer too small for format salt.\\n"); | |||||
return (1); | |||||
} | |||||
printf("Invalid format specified.\\n"); | |||||
return (2); | |||||
} | |||||
printf("crypt_makesalt result: %s\\n", salt); | |||||
/* | |||||
* Generate a crypt for storage, using salt as the algorithm selection | |||||
* and parameters. | |||||
*/ | |||||
hash = crypt_r("Initial example password.", salt, &buf1); | |||||
if (hash == NULL) { | |||||
printf("crypt_r (hash) failed.\\n"); | |||||
return (3); | |||||
} | |||||
printf("crypt_r (hash) result: %s\\n", hash); | |||||
/* Generate a crypt of a known value using the salt of a stored hash. */ | |||||
check = crypt_r("Password provided at a later time.", hash, &buf2); | |||||
if (check == NULL) { | |||||
printf("crypt_r (check) failed.\\n"); | |||||
return (4); | |||||
} | |||||
printf("crypt_r (check) result: %s\\n", check); | |||||
/* | |||||
* Do not leak anything about the original hash when comparing. Timing | |||||
* safe comparison is prudent. | |||||
*/ | |||||
if (timingsafe_bcmp(hash, check, strlen(hash))) { | |||||
printf("The two passwords do not match.\\n"); | |||||
return (5); | |||||
} | |||||
printf("The two passwords match.\\n"); | |||||
return (0); | |||||
} | |||||
.Ed | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr login 1 , | .Xr login 1 , | ||||
.Xr passwd 1 , | .Xr passwd 1 , | ||||
.Xr getpass 3 , | .Xr getpass 3 , | ||||
.Xr login_getcapstr 3 , | |||||
.Xr passwd 5 | .Xr passwd 5 | ||||
.Sh HISTORY | .Sh HISTORY | ||||
A rotor-based | A rotor-based | ||||
.Fn crypt | .Fn crypt | ||||
function appeared in | function appeared in Version 6 AT&T UNIX. | ||||
.At v6 . | |||||
The current style | The current style | ||||
.Fn crypt | .Fn crypt | ||||
first appeared in | first appeared in Version 7 AT&T UNIX. | ||||
.At v7 . | |||||
.Pp | .Pp | ||||
The | The DES section of the code (FreeSec 1.0) was developed outside the United | ||||
.Tn DES | |||||
section of the code (FreeSec 1.0) was developed outside the United | |||||
States of America as an unencumbered replacement for the U.S.-only | States of America as an unencumbered replacement for the U.S.-only | ||||
.Nx | .Nx | ||||
libcrypt encryption library. | libcrypt encryption library. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn crypt_r | .Fn crypt_r | ||||
function was added in | function was added in | ||||
.Fx 12.0 . | .Fx 12.0 . | ||||
.Sh AUTHORS | .Sh AUTHORS | ||||
.An -nosplit | |||||
Originally written by | Originally written by | ||||
.An David Burren Aq Mt davidb@werj.com.au , | .An -nosplit | ||||
later additions and changes by | .An David Burren Aq Mt davidb@werj.com.au | ||||
, later additions and changes by | |||||
.An Poul-Henning Kamp , | .An Poul-Henning Kamp , | ||||
.An Mark R V Murray , | .An Mark R V Murray , | ||||
.An Michael Bretterklieber , | .An Michael Bretterklieber , | ||||
.An Kris Kennaway , | .An Kris Kennaway , | ||||
.An Brian Feldman , | .An Brian Feldman , | ||||
.An Paul Herman | .An Paul Herman , | ||||
and | .An Niels Provos , and | ||||
.An Niels Provos . | .An Derek Marcotte . | ||||
.Sh BUGS | .Sh BUGS | ||||
The | The | ||||
.Fn crypt | .Fn crypt | ||||
function returns a pointer to static data, and subsequent calls to | function returns a pointer to static data, and subsequent | ||||
calls to | |||||
.Fn crypt | .Fn crypt | ||||
will modify the same data. | will modify the same data. | ||||
Likewise, | Likewise, | ||||
.Fn crypt_set_format | .Fn crypt_set_format | ||||
modifies static data. | modifies static data. | ||||
.Sh SECURITY CONSIDERATIONS | |||||
The following algorithms are considered insecure, and are not recommended | |||||
for new implementations: | |||||
.Sx md5-crypt , | |||||
.Sx DES Extended Format , | |||||
.Sx Traditional DES Format , | |||||
and | |||||
.Sx NT-Hash . | |||||
.Pp | .Pp | ||||
The NT-hash scheme does not use a salt, | .Sx bcrypt | ||||
and is not hard | is preferred over | ||||
for a competent attacker | .Sx sha512-crypt , | ||||
to break. | or | ||||
Its use is not recommended. | .Sx sha256-crypt , | ||||
because of | |||||
its resiliance to pipelined, and GPU based attacks - unless having a | |||||
NIST-approved algorithm is a requirement. |
why was previous char * enclosed in quotes, but not this one?