Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CRYPT(3)		 BSD Library Functions Manual		      CRYPT(3)

NAME
     crypt, setkey, encrypt, des_setkey, des_cipher -- password	encryption

LIBRARY
     Crypt Library (libcrypt, -lcrypt)

SYNOPSIS
     #include <unistd.h>

     char *
     crypt(const char *key, const char *setting);

     int
     encrypt(char *block, int flag);

     int
     des_setkey(const char *key);

     int
     des_cipher(const char *in,	char *out, long	salt, int count);

     #include <stdlib.h>

     int
     setkey(const char *key);

DESCRIPTION
     The crypt() function performs password encryption.	 The encryption	scheme
     used by crypt() is	dependent upon the contents of the NUL-terminated
     string setting.  If it begins with	a string character (`$') and a number
     then a different algorithm	is used	depending on the number.  At the mo-
     ment a `$1' chooses MD5 hashing and a `$2'	chooses	Blowfish hashing; see
     below for more information.  If setting begins with the ``_'' character,
     DES encryption with a user	specified number of perturbations is selected.
     If	setting	begins with any	other character, DES encryption	with a fixed
     number of perturbations is	selected.

   DES encryption
     The DES encryption	scheme is derived from the NBS Data Encryption Stan-
     dard.  Additional code has	been added to deter key	search attempts	and to
     use stronger hashing algorithms.  In the DES case,	the second argument to
     crypt() is	a character array, 9 bytes in length, consisting of an under-
     score (``_'') followed by 4 bytes of iteration count and 4	bytes of salt.
     Both the iteration	count and the salt are encoded with 6 bits per charac-
     ter, least	significant bits first.	 The values 0 to 63 are	encoded	by the
     characters	``./0-9A-Za-z'', respectively.

     The salt is used to induce	disorder in to the DES algorithm in one	of
     16777216 possible ways (specifically, if bit i of the salt	is set then
     bits i and	i+24 are swapped in the	DES ``E'' box output).	The key	is di-
     vided into	groups of 8 characters (a short	final 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 group bits
     and the encryption	of the DES key with itself becomes the next DES	key.
     Then the final DES	key is used to perform count cumulative	encryptions of
     a 64-bit constant.	 The value returned is a NUL-terminated	string,	20
     bytes in length, consisting of the	setting	followed by the	encoded	64-bit
     encryption.

     For compatibility with historical versions	of crypt(), the	setting	may
     consist of	2 bytes	of salt, encoded as above, in which case an iteration
     count of 25 is used, fewer	perturbations of DES are available, at most 8
     characters	of key are used, and the returned value	is a NUL-terminated
     string 13 bytes in	length.

     The functions encrypt(), setkey(),	des_setkey() and des_cipher() allow
     limited access to the DES algorithm itself.  The key argument to setkey()
     is	a 64 character array of	binary values (numeric 0 or 1).	 A 56-bit key
     is	derived	from this array	by dividing the	array into groups of 8 and ig-
     noring the	last bit in each group.

     The encrypt() argument block is also a 64 character array of binary val-
     ues.  If the value	of flag	is 0, the argument block is encrypted, other-
     wise it is	decrypted.  The	encryption or decryption is returned in	the
     original array block after	using the key specified	by setkey() to process
     it.

     The des_setkey() and des_cipher() functions are faster but	less portable
     than setkey() and encrypt().  The argument	to des_setkey()	is a character
     array of length 8.	 The least significant bit in each character is	ig-
     nored and the next	7 bits of each character are concatenated to yield a
     56-bit key.  The function des_cipher() encrypts (or decrypts if count is
     negative) the 64-bits stored in the 8 characters at in using abs(3) of
     count iterations of DES and stores	the 64-bit result in the 8 characters
     at	out.  The salt specifies perturbations to DES as described above.

   MD5 encryption
     For the MD5 encryption scheme, the	version	number (in this	case ``1''),
     salt and the hashed password are separated	by the ``$'' character.	 A
     valid password looks like this:

     ``$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H.''.

     The entire	password string	is passed as setting for interpretation.

   Blowfish crypt
     The Blowfish version of crypt() has 128 bits of salt in order to make
     building dictionaries of common passwords space consuming.	 The initial
     state of the Blowfish cipher is expanded using the	salt and the password
     repeating the process a variable number of	rounds,	which is encoded in
     the password string.  The maximum password	length is 72.  The final Blow-
     fish password entry is created by encrypting the string

     "OrpheanBeholderScryDoubt"

     with the Blowfish state 64	times.

     The version number, the logarithm of the number of	rounds and the con-
     catenation	of salt	and hashed password are	separated by the `$' charac-
     ter.  An encoded `8' would	specify	256 rounds.  A valid Blowfish password
     looks like	this:

     "$2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC".

     The whole Blowfish	password string	is passed as setting for interpreta-
     tion.

RETURN VALUES
     The function crypt() returns a pointer to the encrypted value on success.

     The behavior of crypt() on	errors isn't well standardized.	 Some imple-
     mentations	simply can't fail (unless the process dies, in which case they
     obviously can't return), others return NULL or a fixed string.  Most im-
     plementations don't set errno, but	some do.  Version 2 of the Single UNIX
     Specification ("SUSv2") specifies only returning NULL and setting errno
     as	a valid	behavior, and defines only one possible	error (ENOSYS, "The
     functionality is not supported on this implementation.") Unfortunately,
     most existing applications	aren't prepared	to handle NULL returns from
     crypt().  The description below corresponds to this implementation	of
     crypt() only.  The	behavior may change to match standards,	other imple-
     mentations	or existing applications.

     crypt() may only fail (and	return)	when passed an invalid or unsupported
     setting, in which case it returns a pointer to a magic string that	is
     shorter than 13 characters	and is guaranteed to differ from setting.
     This behavior is safe for older applications which	assume that crypt()
     can't fail, when both setting new passwords and authenticating against
     existing password hashes.

     The functions setkey(), encrypt(),	des_setkey(), and des_cipher() return
     0 on success and 1	on failure.  Historically, the functions setkey() and
     encrypt() did not return any value.  They have been provided return val-
     ues primarily to distinguish implementations where	hardware support is
     provided but not available	or where the DES encryption is not available
     due to the	usual political	silliness.

SEE ALSO
     login(1), passwd(1), pwhash(1), getpass(3), md5(3), passwd(5),
     passwd.conf(5)

     Wayne Patterson, Mathematical Cryptology for Computer Scientists and
     Mathematicians, ISBN 0-8476-7438-X, 1987.

     R.	Morris and Ken Thompson, "Password Security: A Case History",
     Communications of the ACM,	vol. 22, pp. 594-597, Nov. 1979.

     M.E. Hellman, "DES	will be	Totally	Insecure within	Ten Years", IEEE
     Spectrum, vol. 16,	pp. 32-39, July	1979.

HISTORY
     A rotor-based crypt() function appeared in	Version	6 AT&T UNIX.  The cur-
     rent style	crypt()	first appeared in Version 7 AT&T UNIX.

BUGS
     Dropping the least	significant bit	in each	character of the argument to
     des_setkey() is ridiculous.

     The crypt() function leaves its result in an internal static object and
     returns a pointer to that object.	Subsequent calls to crypt() will mod-
     ify the same object.

     Before NetBSD 6 crypt() returned either NULL or : on error.

BSD				January	1, 2012				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=crypt&sektion=3&manpath=NetBSD+6.0>

home | help