Documentation/crypto/descore-readme.rst

1 .. SPDX-License-Identifier: GPL-2.0
13 ------------------------------------------------------------------------------
15 des - fast & portable DES encryption & decryption.
42 2.	PORTABILITY to any byte-addressable host with a 32bit unsigned C type
43 3.	Plug-compatible replacement for KERBEROS's low-level routines.
46 register-starved machines.  My discussions with Richard Outerbridge,
49 To more rapidly understand the code in this package, inspect desSmallFips.i
51 up in a parameterized fashion so it can easily be modified by speed-daemon
57 performance comparison to other available des code which i could
58 compile on a SPARCStation 1 (cc -O4, gcc -O2):
60 this code (byte-order independent):
62   - 30us per encryption (options: 64k tables, no IP/FP)
63   - 33us per encryption (options: 64k tables, FIPS standard bit ordering)
64   - 45us per encryption (options:  2k tables, no IP/FP)
65   - 48us per encryption (options:  2k tables, FIPS standard bit ordering)
66   - 275us to set a new key (uses 1k of key tables)
71 	the key setting routine. also, i have no interest in re-implementing
74 	used as drop-in replacements with mit's code or any of the mit-
80   - 53us per encryption (uses 2k of tables)
81   - 96us to set a new key (uses 2.25k of key tables)
86 	more specifically, 19-40% slower on the 68020 and 11-35% slower
93 	gcc 2.1 -O2	Sun 3/110	304  uS	369.5uS	461.8uS	 22%
94 	cc      -O1	Sun 3/110	336  uS	436.6uS	399.3uS	 19%
95 	cc      -O2	Sun 3/110	360  uS	532.4uS	505.1uS	 40%
96 	cc      -O4	Sun 3/110	365  uS	532.3uS	505.3uS	 38%
97 	gcc 2.1 -O2	Sun 4/50	 48  uS	 53.4uS	 57.5uS	 11%
98 	cc      -O2	Sun 4/50	 48  uS	 64.6uS	 64.7uS	 35%
99 	cc      -O4	Sun 4/50	 48  uS	 64.7uS	 64.9uS	 35%
106    - 68us per encryption (uses 2k of tables)
107    - 96us to set a new key (uses 2.25k of key tables)
111 	it's a bit weak on common low-level optimizations which is why
112 	it's 39%-106% slower.  because he was interested in fast crypt(3) and
113 	password-cracking applications,  he also used the same ideas to
114 	speed up the key-setting routines with impressive results.
118 	(code from eay@psych.psy.uq.oz.au via comp.sources.misc)
124 	performance. his code takes 26 sparc instructions to compute one
127 	to use only 128k.  his tables and code are machine independent.
129 	(code from glad@daimi.aau.dk via alt.sources or comp.sources.misc)
133   - 108us per encryption (uses 34k worth of tables)
134   - 134us to set a new key (uses 32k of key tables to get this speed!)
136 	the tables used seem to be machine-independent;
137 	he seems to have included a lot of special case code
141 	(code obtained from chalmers.se:pub/des)
146 	also very modified for crypt.  his iteration code uses 16k
149 	(code obtained from aem@aber.ac.uk via alt.sources or comp.sources.misc)
151 ``highly optimized`` and tweaked Kerberos/Athena code (byte-order dependent):
153   - 165us per encryption (uses 6k worth of tables)
154   - 478us to set a new key (uses <1k of key tables)
156 	so despite the comments in this code, it was possible to get
157 	faster code AND smaller tables, as well as making the tables
158 	machine-independent.
159 	(code obtained from prep.ai.mit.edu)
161 UC Berkeley code (depends on machine-endedness):
162   -  226us per encryption
163   - 10848us to set a new key
166 	(code obtained from wuarchive.wustl.edu)
175 i got it and looked at the code,  it really set off a lot of pet peeves -
176 it was too convoluted, the code had been written without taking
179 it was excessively slow,  the author had attempted to clarify the code
190 do the same - it was a trivial change from which i had been scared away
197 to crypt(3) in his tables - i didn't check.
201 than versions hand-written in assembly for the sparc!
209 and which necessarily produced different code and different lookup tables
210 for different machines.  see the kerberos code for an example
211 of what i didn't want to do; all their endedness-specific ``optimizations``
212 obfuscate the code and in the end were slower than a simpler machine
227 the (worst-case) cost of my NOT doing endedness-specific optimizations
228 in the data loading and storing code surrounding the key iterations
230 the input and output work areas do not need to be word-aligned.
239    note that if you select the wrong one, the des code will still work;
250 be able to get performance equal to assembly-coding, except that:
255 2) if your machine has less than 12 32-bit registers i doubt your compiler will
256    generate good code.
258    ``i386`` tries to configure the code for a 386 by only declaring 3 registers
260    however, if you like assembly coding, the 386 does have 7 32-bit registers,
285 	- anything more than 12 bits (bad for RISC and CISC)
286 	- greater than 127 in value (can't use movq or byte immediate on CISC)
287 	- 9-127 (may not be able to use CISC shift immediate or add/sub quick),
288 	- 1-8 were never registered, being the cheapest constants.
302 all index scaling is done explicitly - no hidden shifts by log2(sizeof).
304 the code is written so that even a dumb compiler
309 (actually, there are some code fragments now which do require two temps,
338 	used to hold full 768-bit key.
339 	must be long-aligned.
348 	m points to a 128byte block, k points to an 8 byte des key
349 	which must have odd parity (or -1 is returned) and which must
350 	not be a (semi-)weak key (or -2 is returned).
355 	en/decryption with the key k. if you use DesMethod,
356 	you supply a standard 56bit key; however, if you fill in
357 	m yourself, you will get a 768bit key - but then it won't
365 	provide a routine that converts 128 6-bit bytes (specified in
366 	S-box mapping order or something) into the right format for you.
373 	uses m as a 768bit key as explained above.
393 there are no machine-dependencies in the code (see porting),
403 note that i have included a kerberos-compatible interface in desUtil.c
405 to use these with kerberos or kerberos-compatible code put desCore.a
406 ahead of the kerberos-compatible library on your linker's command line.