Fincer
/
openntpd-openbsd
mirror of https://github.com/Fincer/openntpd-openbsd


.\" $OpenBSD: crypt.3,v 1.39 2014/11/17 16:47:28 tedu Exp $

.\"

.\" FreeSec: libcrypt

.\"

.\" Copyright (c) 1994 David Burren

.\" All rights reserved.

.\"

.\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions

.\" are met:

.\" 1. Redistributions of source code must retain the above copyright

.\"    notice, this list of conditions and the following disclaimer.

.\" 2. Redistributions in binary form must reproduce the above copyright

.\"    notice, this list of conditions and the following disclaimer in the

.\"    documentation and/or other materials provided with the distribution.

.\" 4. Neither the name of the author nor the names of other contributors

.\"    may be used to endorse or promote products derived from this software

.\"    without specific prior written permission.

.\"

.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND

.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE

.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

.\" 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

.\" SUCH DAMAGE.

.\"

.\" Manual page, using -mandoc macros

.\"

.Dd $Mdocdate: November 17 2014 $

.Dt CRYPT 3

.Os

.Sh NAME

.Nm crypt ,

.Nm crypt_checkpass ,

.Nm setkey ,

.Nm encrypt ,

.Nm des_setkey ,

.Nm des_cipher ,

.Nm bcrypt_gensalt ,

.Nm bcrypt

.Nd password hashing

.Sh SYNOPSIS

.In stdlib.h

.Ft int

.Fn setkey "const char *key"

.Pp

.In unistd.h

.Ft char *

.Fn crypt "const char *key" "const char *setting"

.Ft int

.Fn crypt_checkpass "const char *password" "const char *hash"

.Ft int

.Fn crypt_newhash "const char *password" "login_cap_t *lc" "char *hash" "size_t hashsize"

.Ft int

.Fn encrypt "char *block" "int flag"

.Ft int

.Fn des_setkey "const char *key"

.Ft int

.Fn des_cipher "const char *in" "char *out" "int32_t salt" "int count"

.In pwd.h

.Ft char *

.Fn bcrypt_gensalt "u_int8_t log_rounds"

.Ft char *

.Fn bcrypt "const char *key" "const char *salt"

.Sh DESCRIPTION

The

.Fn crypt

function performs password hashing based on the

.Tn NBS

Data Encryption Standard (DES).

Additional code has been added to deter key search attempts and to use

stronger hashing algorithms.

.Pp

The first argument to

.Fn crypt

is a

.Dv NUL Ns -terminated

string, typically a user's typed password.

The second is in one of three forms:

if it begins with an underscore

.Pq Ql _

then an extended format is used

in interpreting both the key and the setting, as outlined below.

If it begins

with a string character

.Pq Ql $

and a number then a different algorithm is used depending on the number.

At the moment

.Ql $2

chooses Blowfish hashing; see below for more information.

.Pp

The

.Fn crypt_checkpass

function is provided to simplify checking a user's password.

If both the hash and the password are the empty string, authentication

is a success.

Otherwise, the password is hashed and compared to the provided hash.

If the hash is NULL, authentication will always fail, but a default

amount of work is performed to simulate the hashing operation.

A successful match will return 0.

A failure will return \-1 and set errno.

.Pp

The

.Fn crypt_newhash

function is provided to simplify the creation of new password hashes.

The provided

.Fa password

is randomly salted and hashed and stored in

.Fa hash .

The login class argument

.Fa lc

is used to identify the preferred hashing algorithm and parameters.

Refer to

.Xr login.conf 5 .

.Ss Extended crypt

The

.Ar key

is divided into groups of 8 characters (the last group is null-padded)

and the low-order 7 bits of each character (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 setting 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 .

.Ss "Blowfish" crypt

The

.Tn Blowfish

version of crypt has 128 bits of

.Fa salt

in order to make building dictionaries of common passwords space consuming.

The initial state of the

.Tn Blowfish

cipher is expanded using the

.Fa salt

and the

.Fa password

repeating the process a variable number of rounds, which is encoded in

the password string.

The maximum password length is 72.

The final Blowfish password entry is created by encrypting the string

.Pp

.Dq OrpheanBeholderScryDoubt

.Pp

with the

.Tn Blowfish

state 64 times.

.Pp

The version number, the logarithm of the number of rounds and

the concatenation of salt and hashed password are separated by the

.Ql $

character.

An encoded

.Sq 8

would specify 256 rounds.

A valid Blowfish password looks like this:

.Pp

.Dq $2b$12$FPWWO2RJ3CK4FINTw0Hi8OiPKJcX653gzSS.jqltHFMxyDmmQ0Hqq .

.Pp

The whole Blowfish password string is passed as

.Fa setting

for interpretation.

.Ss "Traditional" crypt

The first 8 bytes of the key are null-padded, and the low-order 7 bits of

each character is used to form the 56-bit

.Tn DES

key.

.Pp

The setting is a 2-character array of the ASCII-encoded salt.

Thus only 12 bits of

.Fa salt

are used.

.Fa count

is set to 25.

.Ss DES Algorithm

The

.Fa salt

introduces disorder in the

.Tn DES

algorithm in one of 16777216 or 4096 possible ways

(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).

.Pp

The DES key is used to encrypt a 64-bit constant using

.Ar count

iterations of

.Tn DES .

The value returned is a

.Dv NUL Ns -terminated

string, 20 or 13 bytes (plus NUL) in length, consisting of the

.Ar setting

followed by the encoded 64-bit encryption.

.Pp

The functions

.Fn encrypt ,

.Fn setkey ,

.Fn des_setkey ,

and

.Fn des_cipher

provide access to the

.Tn DES

algorithm itself.

.Fn setkey

is passed a 64-byte array of binary values (numeric 0 or 1).

A 56-bit key is extracted from this array by dividing the

array into groups of 8, and ignoring the last bit in each group.

That bit is reserved for a byte parity check by DES, but is ignored

by these functions.

.Pp

The

.Fa block

argument to

.Fn encrypt

is also a 64-byte array of binary values.

If the value of

.Fa flag

is 0,

.Fa block

is encrypted otherwise it is decrypted.

The result is returned in the original array

.Fa block

after using the key specified by

.Fn setkey

to process it.

.Pp

The argument to

.Fn des_setkey

is a character array of length 8.

The least significant bit (the parity bit) in each character is ignored,

and the remaining bits are concatenated to form a 56-bit key.

The function

.Fn des_cipher

encrypts (or decrypts if

.Fa count

is negative) the 64-bits stored in the 8 characters at

.Fa in

using

.Xr abs 3

of

.Fa count

iterations of

.Tn DES

and stores the 64-bit result in the 8 characters at

.Fa out

(which may be the same as

.Fa in ) .

The

.Fa salt

specifies perturbations to the

.Tn DES

E-box output as described above.

.Pp

The

.Fn crypt ,

.Fn setkey ,

and

.Fn des_setkey

functions all manipulate the same key space.

.Sh RETURN VALUES

The function

.Fn crypt

returns a pointer to the encrypted value on success, and

.Dv NULL

on failure.

The functions

.Fn setkey ,

.Fn encrypt ,

.Fn des_setkey ,

and

.Fn des_cipher

return 0 on success and 1 on failure.

.Sh SEE ALSO

.Xr encrypt 1 ,

.Xr login 1 ,

.Xr passwd 1 ,

.Xr blowfish 3 ,

.Xr getpass 3 ,

.Xr md5 3 ,

.Xr passwd 5

.Sh HISTORY

A rotor-based

.Fn crypt

function appeared in

.At v3 .

The current style

.Fn crypt

first appeared in

.At v7 .

.Sh AUTHORS

.An David Burren Aq Mt davidb@werj.com.au

wrote the original DES functions.

.Sh BUGS

The

.Fn crypt

function returns a pointer to static data, and subsequent calls to

.Fn crypt

will modify the same object.

.Pp

With DES hashing, passwords containing the byte 0x80 use less key entropy

than other passwords.

								This is an implementation bug, not a bug in the DES cipher.