.\" Portions Copyright © 2005-2006 Nokia. All rights reserved.

.\" FreeSec: libcrypt for NetBSD

.\"

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

.\"

.\" $FreeBSD: src/lib/libcrypt/crypt.3,v 1.31 2005/02/09 18:03:14 ru Exp $

.\"

.Dd January 19, 1997

.Dt CRYPT 3

.Os

.Sh NAME

.Nm crypt

.Nd password and data encryption

.Sh LIBRARY

.Lb libcrypt

.Sh SYNOPSIS

.In unistd.h

.Ft char *

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

.Sh RETURN VALUES

The

.Fn crypt

function returns a pointer to the encrypted value on success, and NULL on

failure.

.Pp

.Sh DESCRIPTION

The

.Fn crypt

function performs password hashing with additional code added to

thwart dictionary attack.

Different algorithms can be used in the hash.

.\"

.\" NOTICE:

.\" If you add more algorithms, make sure to update this list

.\" and the default used for the Traditional format, below.

.\"

Currently the implementation supports

.Tn Data Encryption Standard (DES) 

and

.Tn MD5

hash algorithms. However, the actual algorithm used during the call to

.Fn crypt

depends on the 

.Fn salt

parameter.

.Pp

The first argument to

.Fn crypt 

is the data to hash (usually a password), in a

.Dv NULL Ns -terminated

string.

The second is the salt, in one of two forms:

.Pp

.Bl -tag -width Traditional -compact -offset indent

.It Modular

If 

.Fn salt

begins with the string

.Dq $digit$

then the Modular Crypt Format is used.

.It Traditional

.Fn salt

parameter is a two-character string chosen from the set [a-zA-Z0-9./].

.El

.Pp

.Ss "Modular" crypt:

.Pp

If

.Fn salt

begins with the string

.Fa $digit$

then Modular Crypt Format is used.

The

.Fa digit

identifies the algorithm used for encryption. Currently MD5 hash is implemented. So 

.Fa digit

will be 1 and hence the second argument to this function will be a string beginning with

.Dq $1$

followed by at most 8 characters (actual salt to be used in the encryption), and optionally

terminated by 

.Dq $

.

If the optional 

.Dq $

is included then the characters following the dollar sign are ignored. 

The output of this operation will be a string

containing 34 characters in the format

.Dq $1$<string>$

.Pp

.Dq <string>

consists of the actual salt (the at most 8 characters string following 

.Dq $1$

in the 

.Fn salt),

followed by 22 bytes of data from the set [a-zA-Z0-9./].

.El

.Pp

Other crypt formats may be easily added.

An example salt would be:

.Bl -tag -offset indent

.It Cm "$4$thesalt$rest"

.El

.Pp

.Ss "Traditional" crypt:

.Pp

It is based on Data Encryption Standard algorithm (DES).

.Fn salt

is a two-character string chosen from the set [a-zA-Z0-9./]. In order to thwart the 

Dictionary Attack, the two-character 

.Fn salt

is used to perturb the algorithm in 4096 ways.

.Pp

The 56-bit key for the DES algorithm is obtained by taking the lowest 7 bits of each 

of the first eight characters of the 

.Fn key.

The key thus obtained is used to encrypt a constant string (a string containing all zeroes).

.Pp

The return value of this function is a pointer to a static buffer. So the function

is not reentrant.

.Sh Example

.Bd -literal -offset indent

#include <stdlib.h>

#include <unistd.h>

void crypt_user()

{

	char *p = NULL,

	     *q = NULL;

	/* Invoke crypt() to perform password hashing */

	p = crypt("password", "S1");	/* p contains the hash of "password"

						 * when "S1" is used as the key. DES

						 * encryption algoritm is used in this

						 * scenario

						 */

	q = crypt("password", "$1$Salt1");

						/* q contains the hash of "password"

						 * as computed by the MD5 hash algorithm

						 */

}

.Ed

.Sh SEE ALSO

.Sh BUGS

Output of 

.Fn crypt

differs from that of Linux's when NULL passed as 

.Fn salt .