1 files changed, 314 insertions, 0 deletions

diff --git a/src/lib/libc/crypt/crypt.3 b/src/lib/libc/crypt/crypt.3
new file mode 100644
index 0000000000..5f0f1cdba8
--- /dev/null
+++ b/src/lib/libc/crypt/crypt.3
@@ -0,0 +1,314 @@
+.\" $OpenBSD: crypt.3,v 1.19 2002/01/24 20:33:45 mickey 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 March 9, 1994
+.Dt CRYPT 3
+.Os
+.Sh NAME
+.Nm crypt ,
+.Nm setkey ,
+.Nm encrypt ,
+.Nm des_setkey ,
+.Nm des_cipher
+.Nd DES encryption
+.Sh SYNOPSIS
+.Fd #include <unistd.h>
+.Ft char *
+.Fn crypt "const char *key" "const char *setting"
+.Ft int
+.Fn setkey "char *key"
+.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"
+.Sh DESCRIPTION
+The
+.Fn crypt
+function performs password encryption 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 null 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 a
+.Ql $1
+chooses MD5 hashing and a
+.Ql $2
+chooses Blowfish hashing; see below for more information.
+.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 "MD5" crypt
+For
+.Tn MD5
+crypt the version number,
+.Fa salt
+and the hashed password are separated by the
+.Ql $
+character.
+The maximum length of a password is limited by
+the length counter of the MD5 context, which is about
+2**64.
+A valid MD5 password entry looks like this:
+.Pp
+.Dq $1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1 .
+.Pp
+The whole MD5 password string is passed as
+.Fa setting
+for interpretation.
+.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 $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
+.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 null Ns -terminated
+string, 20 or 13 bytes (plus null) 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 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.
+.Pp
+The
+.Fn crypt ,
+.Fn setkey ,
+and
+.Fn des_setkey
+functions all manipulate the same key space.
+.Sh SEE ALSO
+.Xr login 1 ,
+.Xr passwd 1 ,
+.Xr blowfish 3 ,
+.Xr getpass 3 ,
+.Xr md5 3 ,
+.Xr passwd 5
+.Sh AUTHORS
+David Burren <davidb@werj.com.au>
+.Sh HISTORY
+A rotor-based
+.Fn crypt
+function appeared in
+.At v3 .
+The current style
+.Fn crypt
+first appeared in
+.At v7 .
+.Pp
+This library (FreeSec 1.0) was developed outside the United States of America
+as an unencumbered replacement for the U.S.-only libcrypt encryption
+library.
+Programs linked against the
+.Fn crypt
+interface may be exported from the U.S.A. only if they use
+.Fn crypt
+solely for authentication purposes and avoid use of
+the other programmer interfaces listed above.
+Special care has been taken
+in the library so that programs which only use the
+.Fn crypt
+interface do not pull in the other components.
+.Sh BUGS
+The
+.Fn crypt
+function returns a pointer to static data, and subsequent calls to
+.Fn crypt
+will modify the same object.