gen/crypt.3

   1 .\" $OpenBSD: crypt.3,v 1.5 1996/12/10 09:06:09 deraadt Exp $
   2 .\"
   3 .\" FreeSec: libcrypt
   4 .\"
   5 .\" Copyright (c) 1994 David Burren
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 4. Neither the name of the author nor the names of other contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" Manual page, using -mandoc macros
  33 .\"
  34 .Dd March 9, 1994
  35 .Dt CRYPT 3
  36 .Os "FreeSec 1.0"
  37 .Sh NAME
  38 .Nm crypt ,
  39 .Nm encrypt ,
  40 .Nm setkey
  41 .Nd DES encryption
  42 .Sh SYNOPSIS
  43 .Fd #include <unistd.h>
  44 .Ft char *
  45 .Fo crypt
  46 .Fa "const char *key"
  47 .Fa "const char *salt"
  48 .Fc
  49 .Ft void
  50 .Fo encrypt
  51 .Fa "char *block"
  52 .Fa "int edflag"
  53 .Fc
  54 .Fd #include <stdlib.h>
  55 .Ft void
  56 .Fo setkey
  57 .Fa "const char *key"
  58 .Fc
  59 .Sh DESCRIPTION
  60 The
  61 .Fn crypt
  62 function performs password encryption, based on the
  63 .Tn NBS
  64 Data Encryption Standard (DES).
  65 Additional code has been added to deter key search attempts.
  66 The first argument to
  67 .Fn crypt
  68 is a
  69 .Dv null Ns -terminated
  70 string, typically a user's typed password.
  71 The second is in one of two forms:
  72 if it begins with an underscore (``_''), an extended format is used
  73 in interpreting both the key and the salt value, as outlined below.
  74 .Ss Extended crypt:
  75 .Pp
  76 The
  77 .Ar key
  78 is divided into groups of 8 characters (the last group is null-padded)
  79 and the low-order 7 bits of each each character (56 bits per group) are
  80 used to form the DES key as follows:
  81 the first group of 56 bits becomes the initial DES key.
  82 For each additional group, the XOR of the encryption of the current DES
  83 key with itself and the group bits becomes the next DES key.
  84 .Pp
  85 The
  86 .Ar salt
  87 is a 9-character array consisting of an underscore, followed
  88 by 4 bytes of iteration count and 4 bytes of salt.
  89 These are encoded as printable characters, 6 bits per character,
  90 least significant character first.
  91 The values 0 to 63 are encoded as ``./0-9A-Za-z''.
  92 This allows 24 bits for both
  93 .Fa count
  94 and
  95 .Fa salt .
  96 .Ss "Traditional" crypt:
  97 .Pp
  98 The first 8 bytes of the key are null-padded, and the low-order 7 bits of
  99 each character is used to form the 56-bit
 100 .Tn DES
 101 key.
 102 .Pp
 103 The
 104 .Fa salt
 105 is a 2-character array of the ASCII-encoded salt.
 106 Thus, only 12 bits of salt are used.
 107 .Fa count
 108 is set to 25.
 109 .Ss Algorithm:
 110 .Pp
 111 The
 112 .Fa salt
 113 introduces disorder in the
 114 .Tn DES
 115 algorithm in one of 16777216 or 4096 possible ways
 116 (ie. with 24 or 12 bits: if bit
 117 .Em i
 118 of the
 119 .Ar salt
 120 is set, then bits
 121 .Em i
 122 and
 123 .Em i+24
 124 are swapped in the
 125 .Tn DES
 126 E-box output).
 127 .Pp
 128 The DES key is used to encrypt a 64-bit constant, using
 129 .Ar count
 130 iterations of
 131 .Tn DES .
 132 The value returned is a
 133 .Dv null Ns -terminated
 134 string, 20 or 13 bytes (plus null) in length, consisting of the
 135 .Ar salt ,
 136 followed by the encoded 64-bit encryption.
 137 .Pp
 138 The functions,
 139 .Fn encrypt
 140 and
 141 .Fn setkey
 142 provide access to the
 143 .Tn DES
 144 algorithm itself.
 145 .Fn setkey
 146 is passed a 64-byte array of binary values (numeric 0 or 1).
 147 A 56-bit key is extracted from this array by dividing the
 148 array into groups of 8 and ignoring the last bit in each group.
 149 That bit is reserved for a byte parity check by DES, but is ignored
 150 by these functions.
 151 .Pp
 152 The
 153 .Fa block
 154 argument to
 155 .Fn encrypt
 156 is also a 64-byte array of binary values.
 157 If the value of
 158 .Fa edflag
 159 is 0,
 160 .Fa block
 161 is encrypted; otherwise, it is decrypted.
 162 The result is returned in the original array
 163 .Fa block ,
 164 after using the key specified by
 165 .Fn setkey
 166 to process it.
 167 .Pp
 168 The function
 169 .Fn crypt
 170 returns a pointer to the encrypted value on success, and NULL on failure.
 171 .Pp
 172 The
 173 .Fn crypt
 174 and
 175 .Fn setkey
 176 functions all manipulate the same key space.
 177 .Sh SEE ALSO
 178 .Xr login 1 ,
 179 .Xr passwd 1 ,
 180 .Xr getpass 3 ,
 181 .Xr compat 5 ,
 182 .Xr passwd 5
 183 .Sh LEGACY SYNOPSIS
 184 .Fd #include <unistd.h>
 185 .Pp
 186 .Ft int
 187 .br
 188 .Fo encrypt
 189 .Fa "char *block"
 190 .Fa "int edflag"
 191 .Fc ;
 192 .Pp
 193 The function
 194 .Fn encrypt
 195 returns 0 on success and 1 on failure.
 196 .Pp
 197 .Ft void
 198 .br
 199 .Fo setkey
 200 .Fa "const char *key"
 201 .Fc ;
 202 .Pp
 203 The include file
 204 .In unistd.h
 205 is necessary and sufficient for the
 206 .Fn setkey
 207 function.
 208 .Sh BUGS
 209 The
 210 .Fn crypt
 211 function returns a pointer to static data, and subsequent calls to
 212 .Fn crypt
 213 will modify the same object.
 214 .Sh HISTORY
 215 A rotor-based
 216 .Fn crypt
 217 function appeared in
 218 .At v6 .
 219 The current style
 220 .Fn crypt
 221 first appeared in
 222 .At v7 .
 223 .Pp
 224 This library (FreeSec 1.0) was developed outside the United States of America
 225 as an unencumbered replacement for the U.S.-only libcrypt encryption
 226 library.
 227 Programs linked against the
 228 .Fn crypt
 229 interface may be exported from the U.S.A. only if they use
 230 .Fn crypt
 231 solely for authentication purposes and avoid use of
 232 the other programmer interfaces listed above. Special care has been taken
 233 in the library so that programs which only use the
 234 .Fn crypt
 235 interface do not pull in the other components.
 236 .Sh AUTHOR
 237 David Burren <davidb@werj.com.au>