3
Please note that this library was originally written to operate with
4
eBones, a version of Kerberos that had had encryption removed when it left
5
the USA and then put back in. As such there are some routines that I will
6
advise not using but they are still in the library for historical reasons.
7
For all calls that have an 'input' and 'output' variables, they can be the
10
This library requires the inclusion of 'des.h'.
12
All of the encryption functions take what is called a des_key_schedule as an
13
argument. A des_key_schedule is an expanded form of the des key.
14
A des_key is 8 bytes of odd parity, the type used to hold the key is a
15
des_cblock. A des_cblock is an array of 8 bytes, often in this library
16
description I will refer to input bytes when the function specifies
17
des_cblock's as input or output, this just means that the variable should
18
be a multiple of 8 bytes.
20
The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to
21
specify decryption. The functions and global variable are as follows:
24
DES keys are supposed to be odd parity. If this variable is set to
25
a non-zero value, des_set_key() will check that the key has odd
26
parity and is not one of the known weak DES keys. By default this
27
variable is turned off;
29
void des_set_odd_parity(
31
This function takes a DES key (8 bytes) and sets the parity to odd.
35
This function returns a non-zero value if the DES key passed is a
36
weak, DES key. If it is a weak key, don't use it, try a different
37
one. If you are using 'random' keys, the chances of hitting a weak
38
key are 1/2^52 so it is probably not worth checking for them.
42
des_key_schedule schedule);
43
Des_set_key converts an 8 byte DES key into a des_key_schedule.
44
A des_key_schedule is an expanded form of the key which is used to
45
perform actual encryption. It can be regenerated from the DES key
46
so it only needs to be kept when encryption or decryption is about
47
to occur. Don't save or pass around des_key_schedule's since they
48
are CPU architecture dependent, DES keys are not. If des_check_key
49
is non zero, zero is returned if the key has the wrong parity or
50
the key is a weak key, else 1 is returned.
54
des_key_schedule schedule);
55
An alternative name for des_set_key().
57
int des_rw_mode; /* defaults to DES_PCBC_MODE */
58
This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default).
59
This specifies the function to use in the enc_read() and enc_write()
66
This is the DES encryption function that gets called by just about
67
every other DES routine in the library. You should not use this
68
function except to implement 'modes' of DES. I say this because the
69
functions that call this routine do the conversion from 'char *' to
70
long, and this needs to be done to make sure 'non-aligned' memory
71
access do not occur. The characters are loaded 'little endian',
72
have a look at my source code for more details on how I use this
74
Data is a pointer to 2 unsigned long's and ks is the
75
des_key_schedule to use. enc, is non zero specifies encryption,
82
This functions is the same as des_encrypt() except that the DES
83
initial permutation (IP) and final permutation (FP) have been left
84
out. As for des_encrypt(), you should not use this function.
85
It is used by the routines in my library that implement triple DES.
86
IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same
87
as des_encrypt() des_encrypt() des_encrypt() except faster :-).
94
This is the basic Electronic Code Book form of DES, the most basic
95
form. Input is encrypted into output using the key represented by
96
ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise
97
decryption occurs. Input is 8 bytes long and output is 8 bytes.
98
(the des_cblock structure is 8 chars).
100
void des_ecb3_encrypt(
103
des_key_schedule ks1,
104
des_key_schedule ks2,
105
des_key_schedule ks3,
107
This is the 3 key EDE mode of ECB DES. What this means is that
108
the 8 bytes of input is encrypted with ks1, decrypted with ks2 and
109
then encrypted again with ks3, before being put into output;
110
C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt()
111
that only takes 2 des_key_schedules that implements,
112
C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1.
114
void des_cbc_encrypt(
121
This routine implements DES in Cipher Block Chaining mode.
122
Input, which should be a multiple of 8 bytes is encrypted
123
(or decrypted) to output which will also be a multiple of 8 bytes.
124
The number of bytes is in length (and from what I've said above,
125
should be a multiple of 8). If length is not a multiple of 8, I'm
126
not being held responsible :-). ivec is the initialisation vector.
127
This function does not modify this variable. To correctly implement
128
cbc mode, you need to do one of 2 things; copy the last 8 bytes of
129
cipher text for use as the next ivec in your application,
130
or use des_ncbc_encrypt().
131
Only this routine has this problem with updating the ivec, all
132
other routines that are implementing cbc mode update ivec.
134
void des_ncbc_encrypt(
141
For historical reasons, des_cbc_encrypt() did not update the
142
ivec with the value requires so that subsequent calls to
143
des_cbc_encrypt() would 'chain'. This was needed so that the same
144
'length' values would not need to be used when decrypting.
145
des_ncbc_encrypt() does the right thing. It is the same as
146
des_cbc_encrypt accept that ivec is updates with the correct value
147
to pass in subsequent calls to des_ncbc_encrypt(). I advise using
148
des_ncbc_encrypt() instead of des_cbc_encrypt();
150
void des_xcbc_encrypt(
159
This is RSA's DESX mode of DES. It uses inw and outw to
160
'whiten' the encryption. inw and outw are secret (unlike the iv)
161
and are as such, part of the key. So the key is sort of 24 bytes.
162
This is much better than cbc des.
164
void des_3cbc_encrypt(
168
des_key_schedule sk1,
169
des_key_schedule sk2,
173
This function is flawed, do not use it. I have left it in the
174
library because it is used in my des(1) program and will function
175
correctly when used by des(1). If I removed the function, people
176
could end up unable to decrypt files.
177
This routine implements outer triple cbc encryption using 2 ks and
178
2 ivec's. Use des_ede2_cbc_encrypt() instead.
180
void des_ede3_cbc_encrypt(
184
des_key_schedule ks1,
185
des_key_schedule ks2,
186
des_key_schedule ks3,
189
This function implements inner triple CBC DES encryption with 3
190
keys. What this means is that each 'DES' operation
191
inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))).
192
Again, this is cbc mode so an ivec is requires.
193
This mode is used by SSL.
194
There is also a des_ede2_cbc_encrypt() that only uses 2
195
des_key_schedule's, the first being reused for the final
196
encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES
197
is used by the RSAref library.
199
void des_pcbc_encrypt(
206
This is Propagating Cipher Block Chaining mode of DES. It is used
207
by Kerberos v4. It's parameters are the same as des_ncbc_encrypt().
209
void des_cfb_encrypt(
217
Cipher Feedback Back mode of DES. This implementation 'feeds back'
218
in numbit blocks. The input (and output) is in multiples of numbits
219
bits. numbits should to be a multiple of 8 bits. Length is the
220
number of bytes input. If numbits is not a multiple of 8 bits,
221
the extra bits in the bytes will be considered padding. So if
222
numbits is 12, for each 2 input bytes, the 4 high bits of the
223
second byte will be ignored. So to encode 72 bits when using
224
a numbits of 12 take 12 bytes. To encode 72 bits when using
225
numbits of 9 will take 16 bytes. To encode 80 bits when using
226
numbits of 16 will take 10 bytes. etc, etc. This padding will
227
apply to both input and output.
230
void des_cfb64_encrypt(
238
This is one of the more useful functions in this DES library, it
239
implements CFB mode of DES with 64bit feedback. Why is this
240
useful you ask? Because this routine will allow you to encrypt an
241
arbitrary number of bytes, no 8 byte padding. Each call to this
242
routine will encrypt the input bytes to output and then update ivec
243
and num. num contains 'how far' we are though ivec. If this does
244
not make much sense, read more about cfb mode of DES :-).
246
void des_ede3_cfb64_encrypt(
250
des_key_schedule ks1,
251
des_key_schedule ks2,
252
des_key_schedule ks3,
256
Same as des_cfb64_encrypt() accept that the DES operation is
257
triple DES. As usual, there is a macro for
258
des_ede2_cfb64_encrypt() which reuses ks1.
260
void des_ofb_encrypt(
267
This is a implementation of Output Feed Back mode of DES. It is
268
the same as des_cfb_encrypt() in that numbits is the size of the
269
units dealt with during input and output (in bits).
271
void des_ofb64_encrypt(
278
The same as des_cfb64_encrypt() except that it is Output Feed Back
281
void des_ede3_ofb64_encrypt(
285
des_key_schedule ks1,
286
des_key_schedule ks2,
287
des_key_schedule ks3,
290
Same as des_ofb64_encrypt() accept that the DES operation is
291
triple DES. As usual, there is a macro for
292
des_ede2_ofb64_encrypt() which reuses ks1.
294
int des_read_pw_string(
299
This routine is used to get a password from the terminal with echo
300
turned off. Buf is where the string will end up and length is the
301
size of buf. Prompt is a string presented to the 'user' and if
302
verify is set, the key is asked for twice and unless the 2 copies
303
match, an error is returned. A return code of -1 indicates a
304
system error, 1 failure due to use interaction, and 0 is success.
306
unsigned long des_cbc_cksum(
312
This function produces an 8 byte checksum from input that it puts in
313
output and returns the last 4 bytes as a long. The checksum is
314
generated via cbc mode of DES in which only the last 8 byes are
315
kept. I would recommend not using this function but instead using
316
the EVP_Digest routines, or at least using MD5 or SHA. This
317
function is used by Kerberos v4 so that is why it stays in the
324
This is my fast version of the unix crypt(3) function. This version
325
takes only a small amount of space relative to other fast
326
crypt() implementations. This is different to the normal crypt
327
in that the third parameter is the buffer that the return value
328
is written into. It needs to be at least 14 bytes long. This
329
function is thread safe, unlike the normal crypt.
334
This function calls des_fcrypt() with a static array passed as the
335
third parameter. This emulates the normal non-thread safe semantics
338
void des_string_to_key(
341
This function takes str and converts it into a DES key. I would
342
recommend using MD5 instead and use the first 8 bytes of output.
343
When I wrote the first version of these routines back in 1990, MD5
344
did not exist but I feel these routines are still sound. This
345
routines is compatible with the one in MIT's libdes.
347
void des_string_to_2keys(
351
This function takes str and converts it into 2 DES keys.
352
I would recommend using MD5 and using the 16 bytes as the 2 keys.
353
I have nothing against these 2 'string_to_key' routines, it's just
354
that if you say that your encryption key is generated by using the
355
16 bytes of an MD5 hash, every-one knows how you generated your
358
int des_read_password(
362
This routine combines des_read_pw_string() with des_string_to_key().
364
int des_read_2passwords(
369
This routine combines des_read_pw_string() with des_string_to_2key().
371
void des_random_seed(
373
This routine sets a starting point for des_random_key().
377
This function return a random key. Make sure to 'seed' the random
378
number generator (with des_random_seed()) before using this function.
379
I personally now use a MD5 based random number system.
387
This function will write to a file descriptor the encrypted data
388
from buf. This data will be preceded by a 4 byte 'byte count' and
389
will be padded out to 8 bytes. The encryption is either CBC of
390
PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE,
391
pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use
400
This routines read stuff written by des_enc_read() and decrypts it.
401
I have used these routines quite a lot but I don't believe they are
402
suitable for non-blocking io. If you are after a full
403
authentication/encryption over networks, have a look at SSL instead.
405
unsigned long des_quad_cksum(
411
This is a function from Kerberos v4 that is not anything to do with
412
DES but was needed. It is a cksum that is quicker to generate than
413
des_cbc_cksum(); I personally would use MD5 routines now.
416
Quite a bit of the following information has been taken from
419
Electronic funds transfer - Requirements for interfaces,
420
Part 5.2: Modes of operation for an n-bit block cipher algorithm
423
There are several different modes in which DES can be used, they are
426
Electronic Codebook Mode (ECB) (des_ecb_encrypt())
427
- 64 bits are enciphered at a time.
428
- The order of the blocks can be rearranged without detection.
429
- The same plaintext block always produces the same ciphertext block
430
(for the same key) making it vulnerable to a 'dictionary attack'.
431
- An error will only affect one ciphertext block.
433
Cipher Block Chaining Mode (CBC) (des_cbc_encrypt())
434
- a multiple of 64 bits are enciphered at a time.
435
- The CBC mode produces the same ciphertext whenever the same
436
plaintext is encrypted using the same key and starting variable.
437
- The chaining operation makes the ciphertext blocks dependent on the
438
current and all preceding plaintext blocks and therefore blocks can not
440
- The use of different starting variables prevents the same plaintext
441
enciphering to the same ciphertext.
442
- An error will affect the current and the following ciphertext blocks.
444
Cipher Feedback Mode (CFB) (des_cfb_encrypt())
445
- a number of bits (j) <= 64 are enciphered at a time.
446
- The CFB mode produces the same ciphertext whenever the same
447
plaintext is encrypted using the same key and starting variable.
448
- The chaining operation makes the ciphertext variables dependent on the
449
current and all preceding variables and therefore j-bit variables are
450
chained together and can not be rearranged.
451
- The use of different starting variables prevents the same plaintext
452
enciphering to the same ciphertext.
453
- The strength of the CFB mode depends on the size of k (maximal if
454
j == k). In my implementation this is always the case.
455
- Selection of a small value for j will require more cycles through
456
the encipherment algorithm per unit of plaintext and thus cause
457
greater processing overheads.
458
- Only multiples of j bits can be enciphered.
459
- An error will affect the current and the following ciphertext variables.
461
Output Feedback Mode (OFB) (des_ofb_encrypt())
462
- a number of bits (j) <= 64 are enciphered at a time.
463
- The OFB mode produces the same ciphertext whenever the same
464
plaintext enciphered using the same key and starting variable. More
465
over, in the OFB mode the same key stream is produced when the same
466
key and start variable are used. Consequently, for security reasons
467
a specific start variable should be used only once for a given key.
468
- The absence of chaining makes the OFB more vulnerable to specific attacks.
469
- The use of different start variables values prevents the same
470
plaintext enciphering to the same ciphertext, by producing different
472
- Selection of a small value for j will require more cycles through
473
the encipherment algorithm per unit of plaintext and thus cause
474
greater processing overheads.
475
- Only multiples of j bits can be enciphered.
476
- OFB mode of operation does not extend ciphertext errors in the
477
resultant plaintext output. Every bit error in the ciphertext causes
478
only one bit to be in error in the deciphered plaintext.
479
- OFB mode is not self-synchronising. If the two operation of
480
encipherment and decipherment get out of synchronism, the system needs
481
to be re-initialised.
482
- Each re-initialisation should use a value of the start variable
483
different from the start variable values used before with the same
484
key. The reason for this is that an identical bit stream would be
485
produced each time from the same parameters. This would be
486
susceptible to a ' known plaintext' attack.
488
Triple ECB Mode (des_ecb3_encrypt())
489
- Encrypt with key1, decrypt with key2 and encrypt with key3 again.
490
- As for ECB encryption but increases the key length to 168 bits.
491
There are theoretic attacks that can be used that make the effective
492
key length 112 bits, but this attack also requires 2^56 blocks of
493
memory, not very likely, even for the NSA.
494
- If both keys are the same it is equivalent to encrypting once with
496
- If the first and last key are the same, the key length is 112 bits.
497
There are attacks that could reduce the key space to 55 bit's but it
498
requires 2^56 blocks of memory.
499
- If all 3 keys are the same, this is effectively the same as normal
502
Triple CBC Mode (des_ede3_cbc_encrypt())
503
- Encrypt with key1, decrypt with key2 and then encrypt with key3.
504
- As for CBC encryption but increases the key length to 168 bits with
505
the same restrictions as for triple ecb mode.
added
removed
linux/crypto/ciphers/des/des.doc
