[BACK]Return to crypt.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libcrypt

Annotation of src/lib/libcrypt/crypt.3, Revision 1.25

1.25    ! wiz         1: .\"    $NetBSD: crypt.3,v 1.24 2012/01/01 23:42:03 christos Exp $
1.2       cgd         2: .\"
                      3: .\" Copyright (c) 1989, 1991, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd         5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
1.17      agc        14: .\" 3. Neither the name of the University nor the names of its contributors
1.1       cgd        15: .\"    may be used to endorse or promote products derived from this software
                     16: .\"    without specific prior written permission.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     21: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     28: .\" SUCH DAMAGE.
                     29: .\"
1.8       thorpej    30: .\"     @(#)crypt.3    8.2 (Berkeley) 12/11/93
1.1       cgd        31: .\"
1.23      christos   32: .Dd January 1, 2012
1.1       cgd        33: .Dt CRYPT 3
                     34: .Os
                     35: .Sh NAME
                     36: .Nm crypt ,
                     37: .Nm setkey ,
                     38: .Nm encrypt ,
                     39: .Nm des_setkey ,
                     40: .Nm des_cipher
1.13      wiz        41: .Nd password encryption
1.5       perry      42: .Sh LIBRARY
                     43: .Lb libcrypt
1.1       cgd        44: .Sh SYNOPSIS
1.16      wiz        45: .In unistd.h
1.21      christos   46: .Ft "char *"
                     47: .Fn crypt "const char *key" "const char *setting"
1.1       cgd        48: .Ft int
                     49: .Fn encrypt "char *block" "int flag"
                     50: .Ft int
                     51: .Fn des_setkey "const char *key"
                     52: .Ft int
                     53: .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
1.16      wiz        54: .In stdlib.h
1.6       kleink     55: .Ft int
                     56: .Fn setkey "const char *key"
1.1       cgd        57: .Sh DESCRIPTION
                     58: The
1.4       mikel      59: .Fn crypt
1.1       cgd        60: function
1.15      wiz        61: performs password encryption.
                     62: The encryption scheme used by
1.9       ad         63: .Fn crypt
                     64: is dependent upon the contents of the
                     65: .Dv NUL Ns -terminated
                     66: string
                     67: .Ar setting .
1.14      itojun     68: If it begins
                     69: with a string character
                     70: .Pq Ql $
                     71: and a number then a different algorithm is used depending on the number.
                     72: At the moment a
                     73: .Ql $1
                     74: chooses MD5 hashing and a
                     75: .Ql $2
                     76: chooses Blowfish hashing; see below for more information.
1.9       ad         77: If
                     78: .Ar setting
                     79: begins with the ``_'' character, DES encryption with a user specified number
1.15      wiz        80: of perturbations is selected.
                     81: If
1.9       ad         82: .Ar setting
                     83: begins with any other character, DES encryption with a fixed number
                     84: of perturbations is selected.
1.12      wiz        85: .Ss DES encryption
1.9       ad         86: The DES encryption scheme is derived from the
1.1       cgd        87: .Tn NBS
                     88: Data Encryption Standard.
1.9       ad         89: Additional code has been added to deter key search attempts and to use
1.15      wiz        90: stronger hashing algorithms.
1.19      drochner   91: In the DES case, the second argument to
1.9       ad         92: .Fn crypt
                     93: is a character array, 9 bytes in length, consisting of an underscore (``_'')
                     94: followed by 4 bytes of iteration count and 4 bytes of salt.
1.1       cgd        95: Both the iteration
                     96: .Fa count
1.10      wiz        97: and the
1.1       cgd        98: .Fa salt
                     99: are encoded with 6 bits per character, least significant bits first.
                    100: The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'',
                    101: respectively.
                    102: .Pp
                    103: The
                    104: .Fa salt
                    105: is used to induce disorder in to the
                    106: .Tn DES
                    107: algorithm
                    108: in one of 16777216
                    109: possible ways
                    110: (specifically, if bit
                    111: .Em i
                    112: of the
                    113: .Ar salt
                    114: is set then bits
                    115: .Em i
                    116: and
                    117: .Em i+24
                    118: are swapped in the
                    119: .Tn DES
                    120: ``E'' box output).
                    121: The
                    122: .Ar key
                    123: is divided into groups of 8 characters (a short final group is null-padded)
1.2       cgd       124: and the low-order 7 bits of each character (56 bits per group) are
1.1       cgd       125: used to form the DES key as follows: the first group of 56 bits becomes the
                    126: initial DES key.
                    127: For each additional group, the XOR of the group bits and the encryption of
                    128: the DES key with itself becomes the next DES key.
                    129: Then the final DES key is used to perform
                    130: .Ar count
                    131: cumulative encryptions of a 64-bit constant.
                    132: The value returned is a
                    133: .Dv NUL Ns -terminated
                    134: string, 20 bytes in length, consisting
                    135: of the
                    136: .Ar setting
                    137: followed by the encoded 64-bit encryption.
                    138: .Pp
                    139: For compatibility with historical versions of
1.22      wiz       140: .Fn crypt ,
1.1       cgd       141: the
                    142: .Ar setting
                    143: may consist of 2 bytes of salt, encoded as above, in which case an
                    144: iteration
                    145: .Ar count
                    146: of 25 is used, fewer perturbations of
                    147: .Tn DES
                    148: are available, at most 8
                    149: characters of
                    150: .Ar key
                    151: are used, and the returned value is a
                    152: .Dv NUL Ns -terminated
                    153: string 13 bytes in length.
                    154: .Pp
                    155: The
1.4       mikel     156: functions
1.1       cgd       157: .Fn encrypt ,
                    158: .Fn setkey ,
                    159: .Fn des_setkey
                    160: and
                    161: .Fn des_cipher
                    162: allow limited access to the
                    163: .Tn DES
                    164: algorithm itself.
                    165: The
                    166: .Ar key
                    167: argument to
                    168: .Fn setkey
                    169: is a 64 character array of
                    170: binary values (numeric 0 or 1).
                    171: A 56-bit key is derived from this array by dividing the array
                    172: into groups of 8 and ignoring the last bit in each group.
                    173: .Pp
                    174: The
                    175: .Fn encrypt
                    176: argument
                    177: .Fa block
                    178: is also a 64 character array of
                    179: binary values.
                    180: If the value of
                    181: .Fa flag
                    182: is 0,
                    183: the argument
                    184: .Fa block
1.8       thorpej   185: is encrypted, otherwise it
                    186: is decrypted.
                    187: The encryption or decryption is returned in the original
1.1       cgd       188: array
                    189: .Fa block
                    190: after using the
                    191: key specified
                    192: by
                    193: .Fn setkey
                    194: to process it.
                    195: .Pp
                    196: The
                    197: .Fn des_setkey
                    198: and
                    199: .Fn des_cipher
                    200: functions are faster but less portable than
                    201: .Fn setkey
                    202: and
                    203: .Fn encrypt .
                    204: The argument to
                    205: .Fn des_setkey
                    206: is a character array of length 8.
                    207: The
                    208: .Em least
                    209: significant bit in each character is ignored and the next 7 bits of each
                    210: character are concatenated to yield a 56-bit key.
                    211: The function
                    212: .Fn des_cipher
1.8       thorpej   213: encrypts (or decrypts if
                    214: .Fa count
                    215: is negative) the 64-bits stored in the 8 characters at
1.1       cgd       216: .Fa in
                    217: using
                    218: .Xr abs 3
                    219: of
                    220: .Fa count
                    221: iterations of
                    222: .Tn DES
                    223: and stores the 64-bit result in the 8 characters at
                    224: .Fa out .
                    225: The
                    226: .Fa salt
                    227: specifies perturbations to
                    228: .Tn DES
                    229: as described above.
1.12      wiz       230: .Ss MD5 encryption
1.9       ad        231: For the
1.10      wiz       232: .Tn MD5
1.9       ad        233: encryption scheme, the version number (in this case ``1''),
                    234: .Fa salt
                    235: and the hashed password are separated
1.15      wiz       236: by the ``$'' character.
                    237: A valid password looks like this:
1.9       ad        238: .Pp
                    239: ``$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H.''.
1.1       cgd       240: .Pp
1.10      wiz       241: The entire password string is passed as
1.14      itojun    242: .Fa setting
                    243: for interpretation.
                    244: .Ss "Blowfish" crypt
                    245: The
                    246: .Tn Blowfish
1.25    ! wiz       247: version of
1.24      christos  248: .Fn crypt
                    249: has 128 bits of
1.14      itojun    250: .Fa salt
                    251: in order to make building dictionaries of common passwords space consuming.
                    252: The initial state of the
                    253: .Tn Blowfish
                    254: cipher is expanded using the
                    255: .Fa salt
                    256: and the
                    257: .Fa password
                    258: repeating the process a variable number of rounds, which is encoded in
                    259: the password string.
                    260: The maximum password length is 72.
                    261: The final Blowfish password entry is created by encrypting the string
                    262: .Pp
                    263: .Dq OrpheanBeholderScryDoubt
                    264: .Pp
                    265: with the
                    266: .Tn Blowfish
                    267: state 64 times.
                    268: .Pp
                    269: The version number, the logarithm of the number of rounds and
                    270: the concatenation of salt and hashed password are separated by the
                    271: .Ql $
                    272: character.
                    273: An encoded
                    274: .Sq 8
                    275: would specify 256 rounds.
                    276: A valid Blowfish password looks like this:
                    277: .Pp
                    278: .Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
                    279: .Pp
                    280: The whole Blowfish password string is passed as
1.9       ad        281: .Fa setting
                    282: for interpretation.
                    283: .Sh RETURN VALUES
1.1       cgd       284: The function
                    285: .Fn crypt
1.23      christos  286: returns a pointer to the encrypted value on success.
                    287: .Pp
                    288: The behavior of
                    289: .Fn crypt
                    290: on errors isn't well standardized.
                    291: Some implementations simply can't fail (unless the process dies, in which
                    292: case they obviously can't return), others return
                    293: .Dv NULL
                    294: or a fixed string.
                    295: Most implementations don't set
                    296: .Va errno ,
                    297: but some do.
                    298: .St -susv2
                    299: specifies
                    300: only returning
                    301: .Dv NULL
                    302: and setting
                    303: .Va errno
                    304: as a valid behavior, and defines
                    305: only one possible error
                    306: .Er ( ENOSYS ,
                    307: .Dq "The functionality is not supported on this implementation." )
                    308: Unfortunately, most existing applications aren't prepared to handle
                    309: .Dv NULL
                    310: returns from
                    311: .Fn crypt .
1.24      christos  312: The description below corresponds to this implementation of
                    313: .Fn crypt
                    314: only.
1.23      christos  315: The behavior may change to match standards, other implementations or existing
                    316: applications.
                    317: .Pp
                    318: .Fn crypt
                    319: may only fail (and return) when passed an invalid or unsupported
                    320: .Fa setting ,
                    321: in which case it returns a pointer to a magic string that is shorter than 13
1.24      christos  322: characters and is guaranteed to differ from
1.23      christos  323: .Fa setting .
1.24      christos  324: This behavior is safe for older applications which assume that
                    325: .Fn crypt
                    326: can't fail, when both setting new passwords and authenticating against
                    327: existing password hashes.
1.23      christos  328: .Pp
1.1       cgd       329: The functions
                    330: .Fn setkey ,
                    331: .Fn encrypt ,
                    332: .Fn des_setkey ,
                    333: and
                    334: .Fn des_cipher
                    335: return 0 on success and 1 on failure.
                    336: Historically, the functions
                    337: .Fn setkey
                    338: and
                    339: .Fn encrypt
                    340: did not return any value.
                    341: They have been provided return values primarily to distinguish
                    342: implementations where hardware support is provided but not
                    343: available or where the DES encryption is not available due to the
                    344: usual political silliness.
                    345: .Sh SEE ALSO
                    346: .Xr login 1 ,
                    347: .Xr passwd 1 ,
1.20      hubertf   348: .Xr pwhash 1 ,
1.1       cgd       349: .Xr getpass 3 ,
1.9       ad        350: .Xr md5 3 ,
                    351: .Xr passwd 5 ,
                    352: .Xr passwd.conf 5
1.1       cgd       353: .Rs
                    354: .%T "Mathematical Cryptology for Computer Scientists and Mathematicians"
                    355: .%A Wayne Patterson
                    356: .%D 1987
                    357: .%N ISBN 0-8476-7438-X
                    358: .Re
                    359: .Rs
                    360: .%T "Password Security: A Case History"
                    361: .%A R. Morris
                    362: .%A Ken Thompson
                    363: .%J "Communications of the ACM"
                    364: .%V vol. 22
                    365: .%P pp. 594-597
                    366: .%D Nov. 1979
                    367: .Re
                    368: .Rs
                    369: .%T "DES will be Totally Insecure within Ten Years"
                    370: .%A M.E. Hellman
                    371: .%J "IEEE Spectrum"
                    372: .%V vol. 16
                    373: .%P pp. 32-39
                    374: .%D July 1979
                    375: .Re
                    376: .Sh HISTORY
                    377: A rotor-based
                    378: .Fn crypt
                    379: function appeared in
                    380: .At v6 .
                    381: The current style
                    382: .Fn crypt
                    383: first appeared in
                    384: .At v7 .
                    385: .Sh BUGS
                    386: Dropping the
                    387: .Em least
                    388: significant bit in each character of the argument to
                    389: .Fn des_setkey
                    390: is ridiculous.
                    391: .Pp
                    392: The
                    393: .Fn crypt
                    394: function leaves its result in an internal static object and returns
                    395: a pointer to that object.
                    396: Subsequent calls to
                    397: .Fn crypt
                    398: will modify the same object.
1.21      christos  399: .Pp
                    400: Before
                    401: .Nx 6
                    402: .Fn crypt
                    403: returned either
                    404: .Dv NULL
                    405: or
                    406: .Dv :
                    407: on error.

CVSweb <webmaster@jp.NetBSD.org>