docs: crypto: descore-readme.txt: convert to ReST format

+108 -45

2 changed files

expand all

Documentation

crypto

descore-readme.rst

index.rst

+107 -45

Documentation/crypto/descore-readme.txt Documentation/crypto/descore-readme.rst

··· 1 - Below is the original README file from the descore.shar package. 1 + .. SPDX-License-Identifier: GPL-2.0 2 + .. include:: <isonum.txt> 3 + 4 + =========================================== 5 + Fast & Portable DES encryption & decryption 6 + =========================================== 7 + 8 + .. note:: 9 + 10 + Below is the original README file from the descore.shar package, 11 + converted to ReST format. 12 + 2 13 ------------------------------------------------------------------------------ 3 14 4 15 des - fast & portable DES encryption & decryption. 5 - Copyright (C) 1992 Dana L. How 16 + 17 + Copyright |copy| 1992 Dana L. How 6 18 7 19 This program is free software; you can redistribute it and/or modify 8 20 it under the terms of the GNU Library General Public License as published by ··· 32 20 33 21 Author's address: how@isl.stanford.edu 34 22 35 - $Id: README,v 1.15 1992/05/20 00:25:32 how E $ 23 + .. README,v 1.15 1992/05/20 00:25:32 how E 36 24 37 - 38 - ==>> To compile after untarring/unsharring, just `make' <<== 39 - 25 + ==>> To compile after untarring/unsharring, just ``make`` <<== 40 26 41 27 This package was designed with the following goals: 28 + 42 29 1. Highest possible encryption/decryption PERFORMANCE. 43 30 2. PORTABILITY to any byte-addressable host with a 32bit unsigned C type 44 31 3. Plug-compatible replacement for KERBEROS's low-level routines. ··· 47 36 71755.204@compuserve.com, sparked a number of these enhancements. 48 37 49 38 To more rapidly understand the code in this package, inspect desSmallFips.i 50 - (created by typing `make') BEFORE you tackle desCode.h. The latter is set 39 + (created by typing ``make``) BEFORE you tackle desCode.h. The latter is set 51 40 up in a parameterized fashion so it can easily be modified by speed-daemon 52 41 hackers in pursuit of that last microsecond. You will find it more 53 42 illuminating to inspect one specific implementation, ··· 58 47 compile on a SPARCStation 1 (cc -O4, gcc -O2): 59 48 60 49 this code (byte-order independent): 61 - 30us per encryption (options: 64k tables, no IP/FP) 62 - 33us per encryption (options: 64k tables, FIPS standard bit ordering) 63 - 45us per encryption (options: 2k tables, no IP/FP) 64 - 48us per encryption (options: 2k tables, FIPS standard bit ordering) 65 - 275us to set a new key (uses 1k of key tables) 50 + 51 + - 30us per encryption (options: 64k tables, no IP/FP) 52 + - 33us per encryption (options: 64k tables, FIPS standard bit ordering) 53 + - 45us per encryption (options: 2k tables, no IP/FP) 54 + - 48us per encryption (options: 2k tables, FIPS standard bit ordering) 55 + - 275us to set a new key (uses 1k of key tables) 56 + 66 57 this has the quickest encryption/decryption routines i've seen. 67 58 since i was interested in fast des filters rather than crypt(3) 68 59 and password cracking, i haven't really bothered yet to speed up ··· 76 63 are highly variable because of cache effects). 77 64 78 65 kerberos des replacement from australia (version 1.95): 79 - 53us per encryption (uses 2k of tables) 80 - 96us to set a new key (uses 2.25k of key tables) 66 + 67 + - 53us per encryption (uses 2k of tables) 68 + - 96us to set a new key (uses 2.25k of key tables) 69 + 81 70 so despite the author's inclusion of some of the performance 82 71 improvements i had suggested to him, this package's 83 72 encryption/decryption is still slower on the sparc and 68000. 84 73 more specifically, 19-40% slower on the 68020 and 11-35% slower 85 74 on the sparc, depending on the compiler; 86 75 in full gory detail (ALT_ECB is a libdes variant): 76 + 77 + =============== ============== =============== ================= 87 78 compiler machine desCore libdes ALT_ECB slower by 79 + =============== ============== =============== ================= 88 80 gcc 2.1 -O2 Sun 3/110 304 uS 369.5uS 461.8uS 22% 89 81 cc -O1 Sun 3/110 336 uS 436.6uS 399.3uS 19% 90 82 cc -O2 Sun 3/110 360 uS 532.4uS 505.1uS 40% ··· 97 79 gcc 2.1 -O2 Sun 4/50 48 uS 53.4uS 57.5uS 11% 98 80 cc -O2 Sun 4/50 48 uS 64.6uS 64.7uS 35% 99 81 cc -O4 Sun 4/50 48 uS 64.7uS 64.9uS 35% 82 + =============== ============== =============== ================= 83 + 100 84 (my time measurements are not as accurate as his). 85 + 101 86 the comments in my first release of desCore on version 1.92: 102 - 68us per encryption (uses 2k of tables) 103 - 96us to set a new key (uses 2.25k of key tables) 87 + 88 + - 68us per encryption (uses 2k of tables) 89 + - 96us to set a new key (uses 2.25k of key tables) 90 + 104 91 this is a very nice package which implements the most important 105 92 of the optimizations which i did in my encryption routines. 106 93 it's a bit weak on common low-level optimizations which is why ··· 114 91 speed up the key-setting routines with impressive results. 115 92 (at some point i may do the same in my package). he also implements 116 93 the rest of the mit des library. 94 + 117 95 (code from eay@psych.psy.uq.oz.au via comp.sources.misc) 118 96 119 97 fast crypt(3) package from denmark: 98 + 120 99 the des routine here is buried inside a loop to do the 121 100 crypt function and i didn't feel like ripping it out and measuring 122 101 performance. his code takes 26 sparc instructions to compute one 123 102 des iteration; above, Quick (64k) takes 21 and Small (2k) takes 37. 124 103 he claims to use 280k of tables but the iteration calculation seems 125 104 to use only 128k. his tables and code are machine independent. 105 + 126 106 (code from glad@daimi.aau.dk via alt.sources or comp.sources.misc) 127 107 128 108 swedish reimplementation of Kerberos des library 129 - 108us per encryption (uses 34k worth of tables) 130 - 134us to set a new key (uses 32k of key tables to get this speed!) 109 + 110 + - 108us per encryption (uses 34k worth of tables) 111 + - 134us to set a new key (uses 32k of key tables to get this speed!) 112 + 131 113 the tables used seem to be machine-independent; 132 114 he seems to have included a lot of special case code 133 - so that, e.g., `long' loads can be used instead of 4 `char' loads 115 + so that, e.g., ``long`` loads can be used instead of 4 ``char`` loads 134 116 when the machine's architecture allows it. 117 + 135 118 (code obtained from chalmers.se:pub/des) 136 119 137 120 crack 3.3c package from england: 121 + 138 122 as in crypt above, the des routine is buried in a loop. it's 139 123 also very modified for crypt. his iteration code uses 16k 140 124 of tables and appears to be slow. 125 + 141 126 (code obtained from aem@aber.ac.uk via alt.sources or comp.sources.misc) 142 127 143 - ``highly optimized'' and tweaked Kerberos/Athena code (byte-order dependent): 144 - 165us per encryption (uses 6k worth of tables) 145 - 478us to set a new key (uses <1k of key tables) 128 + ``highly optimized`` and tweaked Kerberos/Athena code (byte-order dependent): 129 + 130 + - 165us per encryption (uses 6k worth of tables) 131 + - 478us to set a new key (uses <1k of key tables) 132 + 146 133 so despite the comments in this code, it was possible to get 147 134 faster code AND smaller tables, as well as making the tables 148 135 machine-independent. 149 136 (code obtained from prep.ai.mit.edu) 150 137 151 138 UC Berkeley code (depends on machine-endedness): 152 - 226us per encryption 153 - 10848us to set a new key 139 + - 226us per encryption 140 + - 10848us to set a new key 141 + 154 142 table sizes are unclear, but they don't look very small 155 143 (code obtained from wuarchive.wustl.edu) 156 144 157 145 158 146 motivation and history 147 + ====================== 159 148 160 149 a while ago i wanted some des routines and the routines documented on sun's 161 150 man pages either didn't exist or dumped core. i had heard of kerberos, ··· 177 142 advantage of the regular structure of operations such as IP, E, and FP 178 143 (i.e. the author didn't sit down and think before coding), 179 144 it was excessively slow, the author had attempted to clarify the code 180 - by adding MORE statements to make the data movement more `consistent' 145 + by adding MORE statements to make the data movement more ``consistent`` 181 146 instead of simplifying his implementation and cutting down on all data 182 147 movement (in particular, his use of L1, R1, L2, R2), and it was full of 183 - idiotic `tweaks' for particular machines which failed to deliver significant 148 + idiotic ``tweaks`` for particular machines which failed to deliver significant 184 149 speedups but which did obfuscate everything. so i took the test data 185 150 from his verification program and rewrote everything else. 186 151 ··· 202 167 203 168 204 169 porting notes 170 + ============= 205 171 206 172 one thing i did not want to do was write an enormous mess 207 173 which depended on endedness and other machine quirks, 208 174 and which necessarily produced different code and different lookup tables 209 175 for different machines. see the kerberos code for an example 210 - of what i didn't want to do; all their endedness-specific `optimizations' 176 + of what i didn't want to do; all their endedness-specific ``optimizations`` 211 177 obfuscate the code and in the end were slower than a simpler machine 212 178 independent approach. however, there are always some portability 213 179 considerations of some kind, and i have included some options ··· 220 184 i assume word pointers can be freely cast to and from char pointers. 221 185 note that 99% of C programs make these assumptions. 222 186 i always use unsigned char's if the high bit could be set. 223 - 2) the typedef `word' means a 32 bit unsigned integral type. 224 - if `unsigned long' is not 32 bits, change the typedef in desCore.h. 187 + 2) the typedef ``word`` means a 32 bit unsigned integral type. 188 + if ``unsigned long`` is not 32 bits, change the typedef in desCore.h. 225 189 i assume sizeof(word) == 4 EVERYWHERE. 226 190 227 191 the (worst-case) cost of my NOT doing endedness-specific optimizations ··· 231 195 232 196 233 197 OPTIONAL performance optimizations 198 + ================================== 234 199 235 - 1) you should define one of `i386,' `vax,' `mc68000,' or `sparc,' 200 + 1) you should define one of ``i386,`` ``vax,`` ``mc68000,`` or ``sparc,`` 236 201 whichever one is closest to the capabilities of your machine. 237 202 see the start of desCode.h to see exactly what this selection implies. 238 203 note that if you select the wrong one, the des code will still work; 239 204 these are just performance tweaks. 240 - 2) for those with functional `asm' keywords: you should change the 205 + 2) for those with functional ``asm`` keywords: you should change the 241 206 ROR and ROL macros to use machine rotate instructions if you have them. 242 207 this will save 2 instructions and a temporary per use, 243 208 or about 32 to 40 instructions per en/decryption. 209 + 244 210 note that gcc is smart enough to translate the ROL/R macros into 245 211 machine rotates! 246 212 247 213 these optimizations are all rather persnickety, yet with them you should 248 214 be able to get performance equal to assembly-coding, except that: 215 + 249 216 1) with the lack of a bit rotate operator in C, rotates have to be synthesized 250 - from shifts. so access to `asm' will speed things up if your machine 217 + from shifts. so access to ``asm`` will speed things up if your machine 251 218 has rotates, as explained above in (3) (not necessary if you use gcc). 252 219 2) if your machine has less than 12 32-bit registers i doubt your compiler will 253 220 generate good code. 254 - `i386' tries to configure the code for a 386 by only declaring 3 registers 221 + 222 + ``i386`` tries to configure the code for a 386 by only declaring 3 registers 255 223 (it appears that gcc can use ebx, esi and edi to hold register variables). 256 224 however, if you like assembly coding, the 386 does have 7 32-bit registers, 257 - and if you use ALL of them, use `scaled by 8' address modes with displacement 225 + and if you use ALL of them, use ``scaled by 8`` address modes with displacement 258 226 and other tricks, you can get reasonable routines for DesQuickCore... with 259 227 about 250 instructions apiece. For DesSmall... it will help to rearrange 260 228 des_keymap, i.e., now the sbox # is the high part of the index and 261 229 the 6 bits of data is the low part; it helps to exchange these. 230 + 262 231 since i have no way to conveniently test it i have not provided my 263 232 shoehorned 386 version. note that with this release of desCore, gcc is able 264 233 to put everything in registers(!), and generate about 370 instructions apiece 265 234 for the DesQuickCore... routines! 266 235 267 236 coding notes 237 + ============ 268 238 269 239 the en/decryption routines each use 6 necessary register variables, 270 240 with 4 being actively used at once during the inner iterations. ··· 278 236 up to 8 more registers are used to hold constants in some configurations. 279 237 280 238 i assume that the use of a constant is more expensive than using a register: 239 + 281 240 a) additionally, i have tried to put the larger constants in registers. 282 241 registering priority was by the following: 283 - anything more than 12 bits (bad for RISC and CISC) 284 - greater than 127 in value (can't use movq or byte immediate on CISC) 285 - 9-127 (may not be able to use CISC shift immediate or add/sub quick), 286 - 1-8 were never registered, being the cheapest constants. 242 + 243 + - anything more than 12 bits (bad for RISC and CISC) 244 + - greater than 127 in value (can't use movq or byte immediate on CISC) 245 + - 9-127 (may not be able to use CISC shift immediate or add/sub quick), 246 + - 1-8 were never registered, being the cheapest constants. 247 + 287 248 b) the compiler may be too stupid to realize table and table+256 should 288 249 be assigned to different constant registers and instead repetitively 289 - do the arithmetic, so i assign these to explicit `m' register variables 250 + do the arithmetic, so i assign these to explicit ``m`` register variables 290 251 when possible and helpful. 291 252 292 253 i assume that indexing is cheaper or equivalent to auto increment/decrement, ··· 298 253 299 254 i assume that addresses can be cheaply formed from two registers, 300 255 or from a register and a small constant. 301 - for the 68000, the `two registers and small offset' form is used sparingly. 256 + for the 68000, the ``two registers and small offset`` form is used sparingly. 302 257 all index scaling is done explicitly - no hidden shifts by log2(sizeof). 303 258 304 259 the code is written so that even a dumb compiler 305 260 should never need more than one hidden temporary, 306 261 increasing the chance that everything will fit in the registers. 307 262 KEEP THIS MORE SUBTLE POINT IN MIND IF YOU REWRITE ANYTHING. 263 + 308 264 (actually, there are some code fragments now which do require two temps, 309 265 but fixing it would either break the structure of the macros or 310 266 require declaring another temporary). 311 267 312 268 313 269 special efficient data format 270 + ============================== 314 271 315 - bits are manipulated in this arrangement most of the time (S7 S5 S3 S1): 272 + bits are manipulated in this arrangement most of the time (S7 S5 S3 S1):: 273 + 316 274 003130292827xxxx242322212019xxxx161514131211xxxx080706050403xxxx 275 + 317 276 (the x bits are still there, i'm just emphasizing where the S boxes are). 318 - bits are rotated left 4 when computing S6 S4 S2 S0: 277 + bits are rotated left 4 when computing S6 S4 S2 S0:: 278 + 319 279 282726252423xxxx201918171615xxxx121110090807xxxx040302010031xxxx 280 + 320 281 the rightmost two bits are usually cleared so the lower byte can be used 321 282 as an index into an sbox mapping table. the next two x'd bits are set 322 283 to various values to access different parts of the tables. ··· 339 288 must be long-aligned. 340 289 341 290 DesQuickInit() 342 - call this before using any other routine with `Quick' in its name. 291 + call this before using any other routine with ``Quick`` in its name. 343 292 it generates the special 64k table these routines need. 344 293 DesQuickDone() 345 294 frees this table ··· 349 298 which must have odd parity (or -1 is returned) and which must 350 299 not be a (semi-)weak key (or -2 is returned). 351 300 normally DesMethod() returns 0. 301 + 352 302 m is filled in from k so that when one of the routines below 353 303 is called with m, the routine will act like standard des 354 304 en/decryption with the key k. if you use DesMethod, ··· 360 308 will be set to magic constants which speed up the encryption/decryption 361 309 on some machines. and yes, each byte controls 362 310 a specific sbox during a specific iteration. 311 + 363 312 you really shouldn't use the 768bit format directly; i should 364 313 provide a routine that converts 128 6-bit bytes (specified in 365 314 S-box mapping order or something) into the right format for you. 366 315 this would entail some byte concatenation and rotation. 367 316 368 317 Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s) 369 - performs des on the 8 bytes at s into the 8 bytes at d. (d,s: char *). 318 + performs des on the 8 bytes at s into the 8 bytes at 319 + ``d. (d,s: char *)``. 320 + 370 321 uses m as a 768bit key as explained above. 322 + 371 323 the Encrypt|Decrypt choice is obvious. 324 + 372 325 Fips|Core determines whether a completely standard FIPS initial 373 326 and final permutation is done; if not, then the data is loaded 374 327 and stored in a nonstandard bit order (FIPS w/o IP/FP). 328 + 375 329 Fips slows down Quick by 10%, Small by 9%. 330 + 376 331 Small|Quick determines whether you use the normal routine 377 332 or the crazy quick one which gobbles up 64k more of memory. 378 333 Small is 50% slower then Quick, but Quick needs 32 times as much ··· 388 329 389 330 390 331 Getting it to compile on your machine 332 + ===================================== 391 333 392 334 there are no machine-dependencies in the code (see porting), 393 - except perhaps the `now()' macro in desTest.c. 335 + except perhaps the ``now()`` macro in desTest.c. 394 336 ALL generated tables are machine independent. 395 337 you should edit the Makefile with the appropriate optimization flags 396 338 for your compiler (MAX optimization). 397 339 398 340 399 341 Speeding up kerberos (and/or its des library) 342 + ============================================= 400 343 401 344 note that i have included a kerberos-compatible interface in desUtil.c 402 345 through the functions des_key_sched() and des_ecb_encrypt(). ··· 408 347 file provided with the kerberos library. 409 348 410 349 Other uses 350 + ========== 411 351 412 352 the macros in desCode.h would be very useful for putting inline des 413 353 functions in more complicated encryption routines.

Documentation/crypto/index.rst

··· 27 27 crypto_engine 28 28 api 29 29 api-samples 30 + descore-readme

Configure Feed

Configure Feed