← Back to branch summary

~ubuntu-branches/ubuntu/hardy/openswan/hardy-updates

« back to all changes in this revision

Viewing changes to lib/libcrypto/libdes/des_crypt.man

  • Committer: Bazaar Package Importer
  • Author(s): Rene Mayrhofer
  • Date: 2005-01-27 16:10:11 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20050127161011-idgybmyz3vwhpfiq
Tags: 2.3.0-2
http://bugs.debian.org/292458
http://bugs.debian.org/291143
Urgency HIGH due to security issue and problems with build-deps in sarge.
* Fix the security issue. Please see
  http://www.idefense.com/application/poi/display?id=190&
      type=vulnerabilities&flashstatus=false
  for more details. Thanks to Martin Schulze for informing me about
  this issue.
  Closes: #292458: Openswan XAUTH/PAM Buffer Overflow Vulnerability
* Added a Build-Dependency to lynx.
  Closes: #291143: openswan: FTBFS: Missing build dependency.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/libcrypto/libdes/des_crypt.man
 
1
.TH DES_CRYPT 3 
 
2
.SH NAME
 
3
des_read_password, des_read_2password,
 
4
des_string_to_key, des_string_to_2key, des_read_pw_string,
 
5
des_random_key, des_set_key,
 
6
des_key_sched, des_ecb_encrypt, des_ecb3_encrypt, des_cbc_encrypt,
 
7
des_3cbc_encrypt,
 
8
des_pcbc_encrypt, des_cfb_encrypt, des_ofb_encrypt,
 
9
des_cbc_cksum, des_quad_cksum,
 
10
des_enc_read, des_enc_write, des_set_odd_parity,
 
11
des_is_weak_key, crypt \- (non USA) DES encryption
 
12
.SH SYNOPSIS
 
13
.nf
 
14
.nj
 
15
.ft B
 
16
#include <des.h>
 
17
.PP
 
18
.B int des_read_password(key,prompt,verify)
 
19
des_cblock *key;
 
20
char *prompt;
 
21
int verify;
 
22
.PP
 
23
.B int des_read_2password(key1,key2,prompt,verify)
 
24
des_cblock *key1,*key2;
 
25
char *prompt;
 
26
int verify;
 
27
.PP
 
28
.B int des_string_to_key(str,key)
 
29
char *str;
 
30
des_cblock *key;
 
31
.PP
 
32
.B int des_string_to_2keys(str,key1,key2)
 
33
char *str;
 
34
des_cblock *key1,*key2;
 
35
.PP
 
36
.B int des_read_pw_string(buf,length,prompt,verify)
 
37
char *buf;
 
38
int length;
 
39
char *prompt;
 
40
int verify;
 
41
.PP
 
42
.B int des_random_key(key)
 
43
des_cblock *key;
 
44
.PP
 
45
.B int des_set_key(key,schedule)
 
46
des_cblock *key;
 
47
des_key_schedule schedule;
 
48
.PP
 
49
.B int des_key_sched(key,schedule)
 
50
des_cblock *key;
 
51
des_key_schedule schedule;
 
52
.PP
 
53
.B int des_ecb_encrypt(input,output,schedule,encrypt)
 
54
des_cblock *input;
 
55
des_cblock *output;
 
56
des_key_schedule schedule;
 
57
int encrypt;
 
58
.PP
 
59
.B int des_ecb3_encrypt(input,output,ks1,ks2,encrypt)
 
60
des_cblock *input;
 
61
des_cblock *output;
 
62
des_key_schedule ks1,ks2;
 
63
int encrypt;
 
64
.PP
 
65
.B int des_cbc_encrypt(input,output,length,schedule,ivec,encrypt)
 
66
des_cblock *input;
 
67
des_cblock *output;
 
68
long length;
 
69
des_key_schedule schedule;
 
70
des_cblock *ivec;
 
71
int encrypt;
 
72
.PP
 
73
.B int des_3cbc_encrypt(input,output,length,sk1,sk2,ivec1,ivec2,encrypt)
 
74
des_cblock *input;
 
75
des_cblock *output;
 
76
long length;
 
77
des_key_schedule sk1;
 
78
des_key_schedule sk2;
 
79
des_cblock *ivec1;
 
80
des_cblock *ivec2;
 
81
int encrypt;
 
82
.PP
 
83
.B int des_pcbc_encrypt(input,output,length,schedule,ivec,encrypt)
 
84
des_cblock *input;
 
85
des_cblock *output;
 
86
long length;
 
87
des_key_schedule schedule;
 
88
des_cblock *ivec;
 
89
int encrypt;
 
90
.PP
 
91
.B int des_cfb_encrypt(input,output,numbits,length,schedule,ivec,encrypt)
 
92
unsigned char *input;
 
93
unsigned char *output;
 
94
int numbits;
 
95
long length;
 
96
des_key_schedule schedule;
 
97
des_cblock *ivec;
 
98
int encrypt;
 
99
.PP
 
100
.B int des_ofb_encrypt(input,output,numbits,length,schedule,ivec)
 
101
unsigned char *input,*output;
 
102
int numbits;
 
103
long length;
 
104
des_key_schedule schedule;
 
105
des_cblock *ivec;
 
106
.PP
 
107
.B unsigned long des_cbc_cksum(input,output,length,schedule,ivec)
 
108
des_cblock *input;
 
109
des_cblock *output;
 
110
long length;
 
111
des_key_schedule schedule;
 
112
des_cblock *ivec;
 
113
.PP
 
114
.B unsigned long des_quad_cksum(input,output,length,out_count,seed)
 
115
des_cblock *input;
 
116
des_cblock *output;
 
117
long length;
 
118
int out_count;
 
119
des_cblock *seed;
 
120
.PP
 
121
.B int des_check_key;
 
122
.PP
 
123
.B int des_enc_read(fd,buf,len,sched,iv)
 
124
int fd;
 
125
char *buf;
 
126
int len;
 
127
des_key_schedule sched;
 
128
des_cblock *iv;
 
129
.PP
 
130
.B int des_enc_write(fd,buf,len,sched,iv)
 
131
int fd;
 
132
char *buf;
 
133
int len;
 
134
des_key_schedule sched;
 
135
des_cblock *iv;
 
136
.PP
 
137
.B extern int des_rw_mode;
 
138
.PP
 
139
.B void des_set_odd_parity(key)
 
140
des_cblock *key;
 
141
.PP
 
142
.B int des_is_weak_key(key)
 
143
des_cblock *key;
 
144
.PP
 
145
.B char *crypt(passwd,salt)
 
146
char *passwd;
 
147
char *salt;
 
148
.PP
 
149
.fi
 
150
.SH DESCRIPTION
 
151
This library contains a fast implementation of the DES encryption
 
152
algorithm.
 
153
.PP
 
154
There are two phases to the use of DES encryption.
 
155
The first is the generation of a
 
156
.I des_key_schedule
 
157
from a key,
 
158
the second is the actual encryption.
 
159
A des key is of type
 
160
.I des_cblock.
 
161
This type is made from 8 characters with odd parity.
 
162
The least significant bit in the character is the parity bit.
 
163
The key schedule is an expanded form of the key; it is used to speed the
 
164
encryption process.
 
165
.PP
 
166
.I des_read_password
 
167
writes the string specified by prompt to the standard output,
 
168
turns off echo and reads an input string from standard input
 
169
until terminated with a newline.
 
170
If verify is non-zero, it prompts and reads the input again and verifies
 
171
that both entered passwords are the same.
 
172
The entered string is converted into a des key by using the
 
173
.I des_string_to_key
 
174
routine.
 
175
The new key is placed in the
 
176
.I des_cblock
 
177
that was passed (by reference) to the routine.
 
178
If there were no errors,
 
179
.I des_read_password
 
180
returns 0,
 
181
-1 is returned if there was a terminal error and 1 is returned for
 
182
any other error.
 
183
.PP
 
184
.I des_read_2password
 
185
operates in the same way as
 
186
.I des_read_password
 
187
except that it generates 2 keys by using the
 
188
.I des_string_to_2key
 
189
function.
 
190
.PP
 
191
.I des_read_pw_string
 
192
is called by
 
193
.I des_read_password
 
194
to read and verify a string from a terminal device.
 
195
The string is returned in
 
196
.I buf.
 
197
The size of
 
198
.I buf
 
199
is passed to the routine via the
 
200
.I length
 
201
parameter.
 
202
.PP
 
203
.I des_string_to_key
 
204
converts a string into a valid des key.
 
205
.PP
 
206
.I des_string_to_2key
 
207
converts a string into 2 valid des keys.
 
208
This routine is best suited for used to generate keys for use with
 
209
.I des_ecb3_encrypt.
 
210
.PP
 
211
.I des_random_key
 
212
returns a random key that is made of a combination of process id,
 
213
time and an increasing counter.
 
214
.PP
 
215
Before a des key can be used it is converted into a
 
216
.I des_key_schedule
 
217
via the
 
218
.I des_set_key
 
219
routine.
 
220
If the
 
221
.I des_check_key
 
222
flag is non-zero,
 
223
.I des_set_key
 
224
will check that the key passed is of odd parity and is not a week or
 
225
semi-weak key.
 
226
If the parity is wrong,
 
227
then -1 is returned.
 
228
If the key is a weak key,
 
229
then -2 is returned.
 
230
If an error is returned,
 
231
the key schedule is not generated.
 
232
.PP
 
233
.I des_key_sched
 
234
is another name for the
 
235
.I des_set_key
 
236
function.
 
237
.PP
 
238
The following routines mostly operate on an input and output stream of
 
239
.I des_cblock's.
 
240
.PP
 
241
.I des_ecb_encrypt
 
242
is the basic DES encryption routine that encrypts or decrypts a single 8-byte
 
243
.I des_cblock
 
244
in
 
245
.I electronic code book
 
246
mode.
 
247
It always transforms the input data, pointed to by
 
248
.I input,
 
249
into the output data,
 
250
pointed to by the
 
251
.I output
 
252
argument.
 
253
If the
 
254
.I encrypt
 
255
argument is non-zero (DES_ENCRYPT),
 
256
the
 
257
.I input
 
258
(cleartext) is encrypted in to the
 
259
.I output
 
260
(ciphertext) using the key_schedule specified by the
 
261
.I schedule
 
262
argument,
 
263
previously set via
 
264
.I des_set_key.
 
265
If
 
266
.I encrypt
 
267
is zero (DES_DECRYPT),
 
268
the
 
269
.I input
 
270
(now ciphertext)
 
271
is decrypted into the
 
272
.I output
 
273
(now cleartext).
 
274
Input and output may overlap.
 
275
No meaningful value is returned.
 
276
.PP
 
277
.I des_ecb3_encrypt
 
278
encrypts/decrypts the
 
279
.I input
 
280
block by using triple ecb DES encryption.
 
281
This involves encrypting the input with 
 
282
.I ks1,
 
283
decryption with the key schedule
 
284
.I ks2,
 
285
and then encryption with the first again.
 
286
This routine greatly reduces the chances of brute force breaking of
 
287
DES and has the advantage of if
 
288
.I ks1
 
289
and
 
290
.I ks2
 
291
are the same, it is equivalent to just encryption using ecb mode and
 
292
.I ks1
 
293
as the key.
 
294
.PP
 
295
.I des_cbc_encrypt
 
296
encrypts/decrypts using the
 
297
.I cipher-block-chaining
 
298
mode of DES.
 
299
If the
 
300
.I encrypt
 
301
argument is non-zero,
 
302
the routine cipher-block-chain encrypts the cleartext data pointed to by the
 
303
.I input
 
304
argument into the ciphertext pointed to by the
 
305
.I output
 
306
argument,
 
307
using the key schedule provided by the
 
308
.I schedule
 
309
argument,
 
310
and initialisation vector provided by the
 
311
.I ivec
 
312
argument.
 
313
If the
 
314
.I length
 
315
argument is not an integral multiple of eight bytes, 
 
316
the last block is copied to a temporary area and zero filled.
 
317
The output is always
 
318
an integral multiple of eight bytes.
 
319
To make multiple cbc encrypt calls on a large amount of data appear to
 
320
be one 
 
321
.I des_cbc_encrypt
 
322
call, the
 
323
.I ivec
 
324
of subsequent calls should be the last 8 bytes of the output.
 
325
.PP
 
326
.I des_3cbc_encrypt
 
327
encrypts/decrypts the
 
328
.I input
 
329
block by using triple cbc DES encryption.
 
330
This involves encrypting the input with key schedule
 
331
.I ks1,
 
332
decryption with the key schedule
 
333
.I ks2,
 
334
and then encryption with the first again.
 
335
2 initialisation vectors are required,
 
336
.I ivec1
 
337
and
 
338
.I ivec2.
 
339
Unlike
 
340
.I des_cbc_encrypt,
 
341
these initialisation vectors are modified by the subroutine.
 
342
This routine greatly reduces the chances of brute force breaking of
 
343
DES and has the advantage of if
 
344
.I ks1
 
345
and
 
346
.I ks2
 
347
are the same, it is equivalent to just encryption using cbc mode and
 
348
.I ks1
 
349
as the key.
 
350
.PP
 
351
.I des_pcbc_encrypt
 
352
encrypt/decrypts using a modified block chaining mode.
 
353
It provides better error propagation characteristics than cbc
 
354
encryption.
 
355
.PP
 
356
.I des_cfb_encrypt
 
357
encrypt/decrypts using cipher feedback mode.  This method takes an
 
358
array of characters as input and outputs and array of characters.  It
 
359
does not require any padding to 8 character groups.  Note: the ivec
 
360
variable is changed and the new changed value needs to be passed to
 
361
the next call to this function.  Since this function runs a complete
 
362
DES ecb encryption per numbits, this function is only suggested for
 
363
use when sending small numbers of characters.
 
364
.PP
 
365
.I des_ofb_encrypt
 
366
encrypt using output feedback mode.  This method takes an
 
367
array of characters as input and outputs and array of characters.  It
 
368
does not require any padding to 8 character groups.  Note: the ivec
 
369
variable is changed and the new changed value needs to be passed to
 
370
the next call to this function.  Since this function runs a complete
 
371
DES ecb encryption per numbits, this function is only suggested for
 
372
use when sending small numbers of characters.
 
373
.PP
 
374
.I des_cbc_cksum
 
375
produces an 8 byte checksum based on the input stream (via cbc encryption).
 
376
The last 4 bytes of the checksum is returned and the complete 8 bytes is
 
377
placed in
 
378
.I output.
 
379
.PP
 
380
.I des_quad_cksum
 
381
returns a 4 byte checksum from the input bytes.
 
382
The algorithm can be iterated over the input,
 
383
depending on
 
384
.I out_count,
 
385
1, 2, 3 or 4 times.
 
386
If
 
387
.I output
 
388
is non-NULL,
 
389
the 8 bytes generated by each pass are written into
 
390
.I output.
 
391
.PP
 
392
.I des_enc_write
 
393
is used to write
 
394
.I len
 
395
bytes
 
396
to file descriptor
 
397
.I fd
 
398
from buffer
 
399
.I buf.
 
400
The data is encrypted via
 
401
.I pcbc_encrypt
 
402
(default) using
 
403
.I sched
 
404
for the key and
 
405
.I iv
 
406
as a starting vector.
 
407
The actual data send down
 
408
.I fd
 
409
consists of 4 bytes (in network byte order) containing the length of the
 
410
following encrypted data.  The encrypted data then follows, padded with random
 
411
data out to a multiple of 8 bytes.
 
412
.PP
 
413
.I des_enc_read
 
414
is used to read
 
415
.I len
 
416
bytes
 
417
from file descriptor
 
418
.I fd
 
419
into buffer
 
420
.I buf.
 
421
The data being read from
 
422
.I fd
 
423
is assumed to have come from
 
424
.I des_enc_write
 
425
and is decrypted using
 
426
.I sched
 
427
for the key schedule and
 
428
.I iv
 
429
for the initial vector.
 
430
The
 
431
.I des_enc_read/des_enc_write
 
432
pair can be used to read/write to files, pipes and sockets.
 
433
I have used them in implementing a version of rlogin in which all
 
434
data is encrypted.
 
435
.PP
 
436
.I des_rw_mode
 
437
is used to specify the encryption mode to use with 
 
438
.I des_enc_read
 
439
and 
 
440
.I des_end_write.
 
441
If set to
 
442
.I DES_PCBC_MODE
 
443
(the default), des_pcbc_encrypt is used.
 
444
If set to
 
445
.I DES_CBC_MODE
 
446
des_cbc_encrypt is used.
 
447
These two routines and the variable are not part of the normal MIT library.
 
448
.PP
 
449
.I des_set_odd_parity
 
450
sets the parity of the passed
 
451
.I key
 
452
to odd.  This routine is not part of the standard MIT library.
 
453
.PP
 
454
.I des_is_weak_key
 
455
returns 1 is the passed key is a weak key (pick again :-),
 
456
0 if it is ok.
 
457
This routine is not part of the standard MIT library.
 
458
.PP
 
459
.I crypt
 
460
is a replacement for the normal system crypt.
 
461
It is much faster than the system crypt.
 
462
.PP
 
463
.SH FILES
 
464
/usr/include/des.h
 
465
.br
 
466
/usr/lib/libdes.a
 
467
.PP
 
468
The encryption routines have been tested on 16bit, 32bit and 64bit
 
469
machines of various endian and even works under VMS.
 
470
.PP
 
471
.SH BUGS
 
472
.PP
 
473
If you think this manual is sparse,
 
474
read the des_crypt(3) manual from the MIT kerberos (or bones outside
 
475
of the USA) distribution.
 
476
.PP
 
477
.I des_cfb_encrypt
 
478
and
 
479
.I des_ofb_encrypt
 
480
operates on input of 8 bits.  What this means is that if you set
 
481
numbits to 12, and length to 2, the first 12 bits will come from the 1st
 
482
input byte and the low half of the second input byte.  The second 12
 
483
bits will have the low 8 bits taken from the 3rd input byte and the
 
484
top 4 bits taken from the 4th input byte.  The same holds for output.
 
485
This function has been implemented this way because most people will
 
486
be using a multiple of 8 and because once you get into pulling bytes input
 
487
bytes apart things get ugly!
 
488
.PP
 
489
.I des_read_pw_string
 
490
is the most machine/OS dependent function and normally generates the
 
491
most problems when porting this code.
 
492
.PP
 
493
.I des_string_to_key
 
494
is probably different from the MIT version since there are lots
 
495
of fun ways to implement one-way encryption of a text string.
 
496
.PP
 
497
The routines are optimised for 32 bit machines and so are not efficient
 
498
on IBM PCs.
 
499
.PP
 
500
NOTE: extensive work has been done on this library since this document
 
501
was origionally written.  Please try to read des.doc from the libdes
 
502
distribution since it is far more upto date and documents more of the
 
503
functions.  Libdes is now also being shipped as part of SSLeay, a
 
504
general cryptographic library that amonst other things implements
 
505
netscapes SSL protocoll.  The most recent version can be found in
 
506
SSLeay distributions.
 
507
.SH AUTHOR
 
508
Eric Young (eay@cryptsoft.com)