crypto/heimdal-0.6.3/lib/des/des_crypt.cat3

   1
   2
   3
   4 DES_CRYPT(3)                                                     DES_CRYPT(3)
   5
   6
   7
   8 NAME
   9   des_read_password, des_string_to_key, des_random_key, des_set_key,
  10   des_ecb_encrypt, des_cbc_encrypt, des_pcbc_encrypt, des_cbc_cksum,
  11   des_quad_cksum, - (new) DES encryption
  12
  13 SYNOPSIS
  14   #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<d\bde\bes\bs.\b.h\bh>\b>
  15
  16   i\bin\bnt\bt d\bde\bes\bs_\b_r\bre\bea\bad\bd_\b_p\bpa\bas\bss\bsw\bwo\bor\brd\bd(\b(k\bke\bey\by,\b,p\bpr\bro\bom\bmp\bpt\bt,\b,v\bve\ber\bri\bif\bfy\by)\b)
  17   des_cblock *key;
  18   char *prompt;
  19   int verify;
  20
  21   i\bin\bnt\bt d\bde\bes\bs_\b_s\bst\btr\bri\bin\bng\bg_\b_t\bto\bo_\b_k\bke\bey\by(\b(s\bst\btr\br,\b,k\bke\bey\by)\b)
  22   c\bch\bha\bar\br *\b*s\bst\btr\br;\b;
  23   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk k\bke\bey\by;\b;
  24
  25   i\bin\bnt\bt d\bde\bes\bs_\b_r\bra\ban\bnd\bdo\bom\bm_\b_k\bke\bey\by(\b(k\bke\bey\by)\b)
  26   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*k\bke\bey\by;\b;
  27
  28   i\bin\bnt\bt d\bde\bes\bs_\b_s\bse\bet\bt_\b_k\bke\bey\by(\b(k\bke\bey\by,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be)\b)
  29   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*k\bke\bey\by;\b;
  30   d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
  31
  32   i\bin\bnt\bt d\bde\bes\bs_\b_e\bec\bcb\bb_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
  33   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
  34   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
  35   d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
  36   i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;
  37
  38   i\bin\bnt\bt d\bde\bes\bs_\b_c\bcb\bbc\bc_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
  39   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
  40   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
  41   l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
  42   d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
  43   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;
  44   i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;
  45
  46   i\bin\bnt\bt d\bde\bes\bs_\b_p\bpc\bcb\bbc\bc_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
  47   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
  48   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
  49   l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
  50   d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
  51   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;
  52   i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;
  53
  54   u\bun\bns\bsi\big\bgn\bne\bed\bd l\blo\bon\bng\bg d\bde\bes\bs_\b_c\bcb\bbc\bc_\b_c\bck\bks\bsu\bum\bm(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc)\b)
  55   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
  56   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
  57   l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
  58   d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
  59   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;
  60
  61   u\bun\bns\bsi\big\bgn\bne\bed\bd l\blo\bon\bng\bg q\bqu\bua\bad\bd_\b_c\bck\bks\bsu\bum\bm(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,o\bou\but\bt_\b_c\bco\bou\bun\bnt\bt,\b,s\bse\bee\bed\bd)\b)
  62   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
  63   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
  64   l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
  65   i\bin\bnt\bt o\bou\but\bt_\b_c\bco\bou\bun\bnt\bt;\b;
  66   d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*s\bse\bee\bed\bd;\b;
  67
  68 DESCRIPTION
  69   This library supports various DES encryption related operations. It differs
  70   from the _\bc_\br_\by_\bp_\bt_\b, _\bs_\be_\bt_\bk_\be_\by_\b, _\ba_\bn_\bd _\be_\bn_\bc_\br_\by_\bp_\bt library routines in that it provides a
  71   true DES encryption, without modifying the algorithm, and executes much
  72   faster.
  73
  74   For each key that may be simultaneously active, create a d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be
  75   struct, defined in "des.h". Next, create key schedules (from the 8-byte
  76   keys) as needed, via _\bd_\be_\bs_\b__\bs_\be_\bt_\b__\bk_\be_\by_\b, prior to using the encryption or checksum
  77   routines. Then setup the input and output areas.  Make sure to note the
  78   restrictions on lengths being multiples of eight bytes. Finally, invoke the
  79   encryption/decryption routines, _\bd_\be_\bs_\b__\be_\bc_\bb_\b__\be_\bn_\bc_\br_\by_\bp_\bt or _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt or
  80   _\bd_\be_\bs_\b__\bp_\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt_\b, or, to generate a cryptographic checksum, use _\bq_\bu_\ba_\bd_\b__\bc_\bk_\bs_\bu_\bm
  81   (fast) or _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\bc_\bk_\bs_\bu_\bm (slow).
  82
  83   A _\bd_\be_\bs_\b__\bc_\bb_\bl_\bo_\bc_\bk struct is an 8 byte block used as the fundamental unit for DES
  84   data and keys, and is defined as:
  85
  86   t\bty\byp\bpe\bed\bde\bef\bf u\bun\bns\bsi\big\bgn\bne\bed\bd c\bch\bha\bar\br d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk[\b[8\b8]\b];\b;
  87
  88   and a _\bd_\be_\bs_\b__\bk_\be_\by_\b__\bs_\bc_\bh_\be_\bd_\bu_\bl_\be_\b, is defined as:
  89
  90   t\bty\byp\bpe\bed\bde\bef\bf s\bst\btr\bru\buc\bct\bt d\bde\bes\bs_\b_k\bks\bs_\b_s\bst\btr\bru\buc\bct\bt {\b{d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk _\b_;\b;}\b} d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be[\b[1\b16\b6]\b];\b;
  91
  92   _\bd_\be_\bs_\b__\br_\be_\ba_\bd_\b__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd writes the string specified by _\bp_\br_\bo_\bm_\bp_\bt to the standard
  93   output, turns off echo (if possible) and reads an input string from stan-
  94   dard input until terminated with a newline.  If _\bv_\be_\br_\bi_\bf_\by is non-zero, it
  95   prompts and reads input again, for use in applications such as changing a
  96   password; both versions are compared, and the input is requested repeatedly
  97   until they match.  Then _\bd_\be_\bs_\b__\br_\be_\ba_\bd_\b__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd converts the input string into a
  98   valid DES key, internally using the _\bd_\be_\bs_\b__\bs_\bt_\br_\bi_\bn_\bg_\b__\bt_\bo_\b__\bk_\be_\by routine.  The newly
  99   created key is copied to the area pointed to by the _\bk_\be_\by argument.
 100   _\bd_\be_\bs_\b__\br_\be_\ba_\bd_\b__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd returns a zero if no errors occurred, or a -1 indicating
 101   that an error occurred trying to manipulate the terminal echo.
 102
 103   _\bd_\be_\bs_\b__\bs_\bt_\br_\bi_\bn_\bg_\b__\bt_\bo_\b__\bk_\be_\by converts an arbitrary length null-terminated string to an
 104   8 byte DES key, with odd byte parity, per FIPS specification.  A one-way
 105   function is used to convert the string to a key, making it very difficult
 106   to reconstruct the string from the key.  The _\bs_\bt_\br argument is a pointer to
 107   the string, and _\bk_\be_\by should point to a _\bd_\be_\bs_\b__\bc_\bb_\bl_\bo_\bc_\bk supplied by the caller to
 108   receive the generated key.  No meaningful value is returned. Void is not
 109   used for compatibility with other compilers.
 110
 111   _\bd_\be_\bs_\b__\br_\ba_\bn_\bd_\bo_\bm_\b__\bk_\be_\by generates a random DES encryption key (eight bytes), set to
 112   odd parity per FIPS specifications.  This routine uses the current time,
 113   process id, and a counter as a seed for the random number generator.  The
 114   caller must  supply space for the output key, pointed to by argument _\bk_\be_\by_\b,
 115   then after calling _\bd_\be_\bs_\b__\br_\ba_\bn_\bd_\bo_\bm_\b__\bk_\be_\by should call the _\bd_\be_\bs_\b__\bs_\be_\bt_\b__\bk_\be_\by routine when
 116   needed.  No meaningful value is returned.  Void is not used for compatibil-
 117   ity with other compilers.
 118
 119   _\bd_\be_\bs_\b__\bs_\be_\bt_\b__\bk_\be_\by calculates a key schedule from all eight bytes of the input
 120   key, pointed to by the _\bk_\be_\by argument, and outputs the schedule into the
 121   _\bd_\be_\bs_\b__\bk_\be_\by_\b__\bs_\bc_\bh_\be_\bd_\bu_\bl_\be indicated by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument. Make sure to pass a
 122   valid eight byte key; no padding is done.  The key schedule may then be
 123   used in subsequent encryption/decryption/checksum operations.  Many key
 124   schedules may be cached for later use.  The user is responsible to clear
 125   keys and schedules as soon as no longer needed, to prevent their disclo-
 126   sure.  The routine also checks the key parity, and returns a zero if the
 127   key parity is correct (odd), a -1 indicating a key parity error, or a -2
 128   indicating use of an illegal weak key. If an error is returned, the key
 129   schedule was not created.
 130
 131   _\bd_\be_\bs_\b__\be_\bc_\bb_\b__\be_\bn_\bc_\br_\by_\bp_\bt is the basic DES encryption routine that encrypts or
 132   decrypts a single 8-byte block in e\bel\ble\bec\bct\btr\bro\bon\bni\bic\bc c\bco\bod\bde\be b\bbo\boo\bok\bk mode.  It always
 133   transforms the input data, pointed to by _\bi_\bn_\bp_\bu_\bt_\b, into the output data,
 134   pointed to by the _\bo_\bu_\bt_\bp_\bu_\bt argument.
 135
 136   If the _\be_\bn_\bc_\br_\by_\bp_\bt argument is non-zero, the _\bi_\bn_\bp_\bu_\bt (cleartext) is encrypted
 137   into the _\bo_\bu_\bt_\bp_\bu_\bt (ciphertext) using the key_schedule specified by the _\bs_\bc_\bh_\be_\bd_\b-
 138   _\bu_\bl_\be argument, previously set via _\bd_\be_\bs_\b__\bs_\be_\bt_\b__\bk_\be_\by
 139
 140   If encrypt is zero, the _\bi_\bn_\bp_\bu_\bt (now ciphertext) is decrypted into the _\bo_\bu_\bt_\bp_\bu_\bt
 141   (now cleartext).
 142
 143   Input and output may overlap.
 144
 145   No meaningful value is returned.  Void is not used for compatibility with
 146   other compilers.
 147
 148   _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt encrypts/decrypts using the c\bci\bip\bph\bhe\ber\br-\b-b\bbl\blo\boc\bck\bk-\b-c\bch\bha\bai\bin\bni\bin\bng\bg m\bmo\bod\bde\be o\bof\bf
 149   D\bDE\bES\bS.\b.  If the _\be_\bn_\bc_\br_\by_\bp_\bt argument is non-zero, the routine cipher-block-chain
 150   encrypts the cleartext data pointed to by the _\bi_\bn_\bp_\bu_\bt argument into the
 151   ciphertext pointed to by the _\bo_\bu_\bt_\bp_\bu_\bt argument, using the key schedule pro-
 152   vided by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument, and initialization vector provided by the
 153   _\bi_\bv_\be_\bc argument.  If the _\bl_\be_\bn_\bg_\bt_\bh argument is not an integral multiple of eight
 154   bytes, the last block is copied to a temp and zero filled (highest
 155   addresses).  The output is ALWAYS an integral multiple of eight bytes.
 156
 157   If _\be_\bn_\bc_\br_\by_\bp_\bt is zero, the routine cipher-block chain decrypts the (now)
 158   ciphertext data pointed to by the _\bi_\bn_\bp_\bu_\bt argument into (now) cleartext
 159   pointed to by the _\bo_\bu_\bt_\bp_\bu_\bt argument using the key schedule provided by the
 160   _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument, and initialization vector provided by the _\bi_\bv_\be_\bc argument.
 161   Decryption ALWAYS operates on integral multiples of 8 bytes, so it will
 162   round the _\bl_\be_\bn_\bg_\bt_\bh provided up to the appropriate multiple. Consequently, it
 163   will always produce the rounded-up number of bytes of output cleartext. The
 164   application must determine if the output cleartext was zero-padded due to
 165   original cleartext lengths that were not integral multiples of 8.
 166
 167   No errors or meaningful values are returned.  Void is not used for compati-
 168   bility with other compilers.
 169
 170   A characteristic of cbc mode is that changing a single bit of the cleart-
 171   ext, then encrypting using cbc mode, affects ALL the subsequent ciphertext.
 172   This makes cryptanalysis much more difficult. However, modifying a single
 173   bit of the ciphertext, then decrypting, only affects the resulting cleart-
 174   ext from the modified block and the succeeding block.  Therefore,
 175   _\bd_\be_\bs_\b__\bp_\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt is STRONGLY recommended for applications where indefinite
 176   propagation of errors is required in order to detect modifications.
 177
 178   _\bd_\be_\bs_\b__\bp_\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt encrypts/decrypts using a modified block chaining mode.
 179   Its calling sequence is identical to _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt_\b.  It differs in its
 180   error propagation characteristics.
 181
 182   _\bd_\be_\bs_\b__\bp_\bc_\bb_\bc_\b__\be_\bn_\bc_\br_\by_\bp_\bt is highly recommended for most encryption purposes, in
 183   that modification of a single bit of the ciphertext will affect ALL the
 184   subsequent (decrypted) cleartext. Similarly, modifying a single bit of the
 185   cleartext will affect ALL the subsequent (encrypted) ciphertext.  "PCBC"
 186   mode, on encryption, "xors" both the cleartext of block N and the cipher-
 187   text resulting from block N with the cleartext for block N+1 prior to
 188   encrypting block N+1.
 189
 190   _\bd_\be_\bs_\b__\bc_\bb_\bc_\b__\bc_\bk_\bs_\bu_\bm produces an 8 byte cryptographic checksum by cipher-block-
 191   chain encrypting the cleartext data pointed to by the _\bi_\bn_\bp_\bu_\bt argument. All
 192   of the ciphertext output is discarded, except the last 8-byte ciphertext
 193   block, which is written into the area pointed to by the _\bo_\bu_\bt_\bp_\bu_\bt argument.
 194   It uses the key schedule, provided by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument and initializa-
 195   tion vector provided by the _\bi_\bv_\be_\bc argument.  If the _\bl_\be_\bn_\bg_\bt_\bh argument is not
 196   an integral multiple of eight bytes, the last cleartext block is copied to
 197   a temp and zero filled (highest addresses).  The output is ALWAYS eight
 198   bytes.
 199
 200   The routine also returns an unsigned long, which is the last (highest
 201   address) half of the 8 byte checksum computed.
 202
 203   _\bq_\bu_\ba_\bd_\b__\bc_\bk_\bs_\bu_\bm produces a checksum by chaining quadratic operations on the
 204   cleartext data pointed to by the _\bi_\bn_\bp_\bu_\bt argument. The _\bl_\be_\bn_\bg_\bt_\bh argument speci-
 205   fies the length of the input -- only exactly that many bytes are included
 206   for the checksum, without any padding.
 207
 208   The algorithm may be iterated over the same input data, if the _\bo_\bu_\bt_\b__\bc_\bo_\bu_\bn_\bt
 209   argument is 2, 3 or 4, and the optional _\bo_\bu_\bt_\bp_\bu_\bt argument is a non-null
 210   pointer .  The default is one iteration, and it will not run more than 4
 211   times. Multiple iterations run slower, but provide a longer checksum if
 212   desired. The _\bs_\be_\be_\bd argument provides an 8-byte seed for the first iteration.
 213   If multiple iterations are requested, the results of one iteration are
 214   automatically used as the seed for the next iteration.
 215
 216   It returns both an unsigned long checksum value, and if the _\bo_\bu_\bt_\bp_\bu_\bt argument
 217   is not a null pointer, up to 16 bytes of the computed checksum are written
 218   into the output.
 219
 220 FILES
 221   /usr/include/des.h
 222   /usr/lib/libdes.a
 223
 224 SEE ALSO
 225
 226 DIAGNOSTICS
 227
 228 BUGS
 229   This software has not yet been compiled or tested on machines other than
 230   the VAX and the IBM PC.
 231
 232 AUTHORS
 233   Steve Miller, MIT Project Athena/Digital Equipment Corporation
 234
 235 RESTRICTIONS
 236   COPYRIGHT 1985,1986 Massachusetts Institute of Technology
 237
 238   This software may not be exported outside of the US without a special
 239   license from the US Dept of Commerce. It may be replaced by any secret key
 240   block cipher with block length and key length of 8 bytes, as long as the
 241   interface is the same as described here.
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264