1.\" FreeSec: libcrypt for NetBSD 2.\" 3.\" Copyright (c) 1994 David Burren 4.\" All rights reserved. 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. 14.\" 4. Neither the name of the author nor the names of other contributors 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 AUTHOR 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 AUTHOR 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.\" 30.\" $FreeBSD$ 31.\" 32.\" Manual page, using -mandoc macros 33.\" 34.Dd January 19, 1997 35.Dt CRYPT 3 36.Os "FreeSec 1.0" 37.Sh NAME 38.Nm crypt 39.Nd Trapdoor encryption 40.Sh LIBRARY 41.Lb libcrypt 42.Sh SYNOPSIS 43.Fd #include <unistd.h> 44.Ft char * 45.Fn crypt "const char *key" "const char *salt" 46.Sh DESCRIPTION 47The 48.Fn crypt 49function performs password hashing with additional code added to 50deter key search attempts. Different algorithms can be used to 51in the hash. 52.\" 53.\" NOTICE: 54.\" If you add more algorithms, make sure to update this list 55.\" and the default used for the Traditional format, below. 56.\" 57Currently these include the 58.Tn NBS 59.Tn Data Encryption Standard (DES) , 60and 61.Tn MD5 . 62The algorithm used will depend upon the format of the Salt--following 63the Modular Crypt Format (MCF)--and if 64.Tn DES 65is installed or not. 66.Pp 67The first argument to 68.Nm 69is the data to hash (usually a password), in a 70.Dv null Ns -terminated 71string. 72The second is the salt, in one of three forms: 73.Pp 74.Bl -tag -width Traditional -compact -offset indent 75.It Extended 76If it begins with an underscore 77.Pq Dq _ 78then the 79.Tn DES 80Extended Format 81is used in interpreting both the the key and the salt, as outlined below. 82.It Modular 83If it begins with the string 84.Dq $digit$ 85then the Modular Crypt Format is used, as outlined below. 86.It Traditional 87If neither of the above is true, it assumes the Traditional Format, 88using the entire string as the salt (or the first portion). 89.El 90.Pp 91All routines are designed to be time-consuming. A brief test on a 92.Tn Pentium 93166/MMX shows the 94.Tn DES 95crypt to do approximately 2640 crypts 96a CPU second and MD5 to do about 62 crypts a CPU second. 97.Ss DES Extended Format: 98.Pp 99The 100.Ar key 101is divided into groups of 8 characters (the last group is null-padded) 102and the low-order 7 bits of each each character (56 bits per group) are 103used to form the 104.Tn DES 105key as follows: 106the first group of 56 bits becomes the initial 107.Tn DES 108key. 109For each additional group, the XOR of the encryption of the current 110.Tn DES 111key with itself and the group bits becomes the next 112.Tn DES 113key. 114.Pp 115The salt is a 9-character array consisting of an underscore followed 116by 4 bytes of iteration count and 4 bytes of salt. 117These are encoded as printable characters, 6 bits per character, 118least significant character first. 119The values 0 to 63 are encoded as ``./0-9A-Za-z''. 120This allows 24 bits for both 121.Fa count 122and 123.Fa salt . 124.Pp 125The 126.Fa salt 127introduces disorder in the 128.Tn DES 129algorithm in one of 16777216 or 4096 possible ways 130(ie. with 24 or 12 bits: if bit 131.Em i 132of the 133.Ar salt 134is set, then bits 135.Em i 136and 137.Em i+24 138are swapped in the 139.Tn DES 140E-box output). 141.Pp 142The 143.Tn DES 144key is used to encrypt a 64-bit constant using 145.Ar count 146iterations of 147.Tn DES . 148The value returned is a 149.Dv null Ns -terminated 150string, 20 or 13 bytes (plus null) in length, consisting of the 151.Ar salt 152followed by the encoded 64-bit encryption. 153.Ss "Modular" crypt: 154.Pp 155If the salt begins with the string 156.Fa $digit$ 157then the Modular Crypt Format is used. The 158.Fa digit 159represents which algorithm is used in encryption. Following the token is 160the actual salt to use in the encryption. The length of the salt is limited 161to 16 characters--because the length of the returned output is also limited 162(_PASSWORD_LEN). The salt must be terminated with the end of the string 163(NULL) or a dollar sign. Any characters after the dollar sign are ignored. 164.Pp 165Currently supported algorithms are: 166.Pp 167.Bl -tag -width 012345678 -compact -offset indent 168.It 1 169MD5 170.El 171.Pp 172Other crypt formats may be easilly added. An example salt would be: 173.Bl -tag -offset indent 174.It Cm "$3$thesalt$rest" 175.El 176.Pp 177.Ss "Traditional" crypt: 178.Pp 179The algorithm used will depend upon whether 180.Tn DES 181is installed or not. If it is, 182.Tn DES 183will be used. Otherwise, the best algorithm is used, which is currently 184.\" 185.\" NOTICE: Also make sure to update this 186.\" 187MD5. 188.Pp 189How the salt is used will depend upon the algorithm for the hash. For 190best results, specify at least two characters of salt. 191.Sh RETURN VALUES 192.Pp 193.Fn crypt 194returns a pointer to the encrypted value on success, and NULL on failure. 195Note: this is not a standard behaviour, AT&T 196.Fn crypt 197will always return a pointer to a string. 198.Sh SEE ALSO 199.Xr login 1 , 200.Xr passwd 1 , 201.Xr cipher 3 , 202.Xr getpass 3 , 203.Xr passwd 5 , 204.Sh BUGS 205The 206.Fn crypt 207function returns a pointer to static data, and subsequent calls to 208.Fn crypt 209will modify the same data. 210.Sh HISTORY 211A rotor-based 212.Fn crypt 213function appeared in 214.At v6 . 215The current style 216.Fn crypt 217first appeared in 218.At v7 . 219.Pp 220The 221.Tn DES 222section of the code (FreeSec 1.0) was developed outside the United 223States of America as an unencumbered replacement for the U.S.-only 224.Nx 225libcrypt encryption library. 226Users should be aware that this code (and programs staticly linked with it) 227may not be exported from the U.S., although it apparently can be imported. 228.Sh AUTHORS 229Originally written by 230.An David Burren Aq davidb@werj.com.au , 231later additions and changes by 232.An Poul-henning Kamp , 233.An Mark R V Murray 234and 235.An Kris Kennaway . 236