1 .TH DES_CRYPT 3
\r.SH NAME
\rdes_read_password, des_read_2password,
\rdes_string_to_key, des_string_to_2key, des_read_pw_string,
\rdes_random_key, des_set_key,
\rdes_key_sched, des_ecb_encrypt, des_3ecb_encrypt, des_cbc_encrypt,
\rdes_3cbc_encrypt,
\rdes_pcbc_encrypt, des_cfb_encrypt, des_ofb_encrypt,
\rdes_cbc_cksum, des_quad_cksum,
\rdes_enc_read, des_enc_write, des_set_odd_parity,
\rdes_is_weak_key, crypt \- (non USA) DES encryption
\r.SH SYNOPSIS
\r.nf
\r.nj
\r.ft B
\r#include <des.h>
\r.PP
\r.B int des_read_password(key,prompt,verify)
\rdes_cblock *key;
\rchar *prompt;
\rint verify;
\r.PP
\r.B int des_read_2password(key1,key2,prompt,verify)
\rdes_cblock *key1,*key2;
\rchar *prompt;
\rint verify;
\r.PP
\r.B int des_string_to_key(str,key)
\rchar *str;
\rdes_cblock *key;
\r.PP
\r.B int des_string_to_2keys(str,key1,key2)
\rchar *str;
\rdes_cblock *key1,*key2;
\r.PP
\r.B int des_read_pw_string(buf,length,prompt,verify)
\rchar *buf;
\rint length;
\rchar *prompt;
\rint verify;
\r.PP
\r.B int des_random_key(key)
\rdes_cblock *key;
\r.PP
\r.B int des_set_key(key,schedule)
\rdes_cblock *key;
\rdes_key_schedule schedule;
\r.PP
\r.B int des_key_sched(key,schedule)
\rdes_cblock *key;
\rdes_key_schedule schedule;
\r.PP
\r.B int des_ecb_encrypt(input,output,schedule,encrypt)
\rdes_cblock *input;
\rdes_cblock *output;
\rdes_key_schedule schedule;
\rint encrypt;
\r.PP
\r.B int des_3ecb_encrypt(input,output,ks1,ks2,encrypt)
\rdes_cblock *input;
\rdes_cblock *output;
\rdes_key_schedule ks1,ks2;
\rint encrypt;
\r.PP
\r.B int des_cbc_encrypt(input,output,length,schedule,ivec,encrypt)
\rdes_cblock *input;
\rdes_cblock *output;
\rlong length;
\rdes_key_schedule schedule;
\rdes_cblock *ivec;
\rint encrypt;
\r.PP
\r.B int des_3cbc_encrypt(input,output,length,sk1,sk2,ivec1,ivec2,encrypt)
\rdes_cblock *input;
\rdes_cblock *output;
\rlong length;
\rdes_key_schedule sk1;
\rdes_key_schedule sk2;
\rdes_cblock *ivec1;
\rdes_cblock *ivec2;
\rint encrypt;
\r.PP
\r.B int des_pcbc_encrypt(input,output,length,schedule,ivec,encrypt)
\rdes_cblock *input;
\rdes_cblock *output;
\rlong length;
\rdes_key_schedule schedule;
\rdes_cblock *ivec;
\rint encrypt;
\r.PP
\r.B int des_cfb_encrypt(input,output,numbits,length,schedule,ivec,encrypt)
\runsigned char *input;
\runsigned char *output;
\rint numbits;
\rlong length;
\rdes_key_schedule schedule;
\rdes_cblock *ivec;
\rint encrypt;
\r.PP
\r.B int des_ofb_encrypt(input,output,numbits,length,schedule,ivec)
\runsigned char *input,*output;
\rint numbits;
\rlong length;
\rdes_key_schedule schedule;
\rdes_cblock *ivec;
\r.PP
\r.B unsigned long des_cbc_cksum(input,output,length,schedule,ivec)
\rdes_cblock *input;
\rdes_cblock *output;
\rlong length;
\rdes_key_schedule schedule;
\rdes_cblock *ivec;
\r.PP
\r.B unsigned long des_quad_cksum(input,output,length,out_count,seed)
\rdes_cblock *input;
\rdes_cblock *output;
\rlong length;
\rint out_count;
\rdes_cblock *seed;
\r.PP
\r.B int des_check_key;
\r.PP
\r.B int des_enc_read(fd,buf,len,sched,iv)
\rint fd;
\rchar *buf;
\rint len;
\rdes_key_schedule sched;
\rdes_cblock *iv;
\r.PP
\r.B int des_enc_write(fd,buf,len,sched,iv)
\rint fd;
\rchar *buf;
\rint len;
\rdes_key_schedule sched;
\rdes_cblock *iv;
\r.PP
\r.B extern int des_rw_mode;
\r.PP
\r.B void des_set_odd_parity(key)
\rdes_cblock *key;
\r.PP
\r.B int des_is_weak_key(key)
\rdes_cblock *key;
\r.PP
\r.B char *crypt(passwd,salt)
\rchar *passwd;
\rchar *salt;
\r.PP
\r.fi
\r.SH DESCRIPTION
\rThis library contains a fast implementation of the DES encryption
\ralgorithm.
\r.PP
\rThere are two phases to the use of DES encryption.
\rThe first is the generation of a
\r.I des_key_schedule
\rfrom a key,
\rthe second is the actual encryption.
\rA des key is of type
\r.I des_cblock.
\rThis type is made from 8 characters with odd parity.
\rThe least significant bit in the character is the parity bit.
\rThe key schedule is an expanded form of the key; it is used to speed the
\rencryption process.
\r.PP
\r.I des_read_password
\rwrites the string specified by prompt to the standard output,
\rturns off echo and reads an input string from standard input
\runtil terminated with a newline.
\rIf verify is non-zero, it prompts and reads the input again and verifies
\rthat both entered passwords are the same.
\rThe entered string is converted into a des key by using the
\r.I des_string_to_key
\rroutine.
\rThe new key is placed in the
\r.I des_cblock
\rthat was passed (by reference) to the routine.
\rIf there were no errors,
\r.I des_read_password
\rreturns 0,
\r-1 is returned if there was a terminal error and 1 is returned for
\rany other error.
\r.PP
\r.I des_read_2password
\roperates in the same way as
\r.I des_read_password
\rexcept that it generates 2 keys by using the
\r.I des_string_to_2key
\rfunction.
\r.PP
\r.I des_read_pw_string
\ris called by
\r.I des_read_password
\rto read and verify a string from a terminal device.
\rThe string is returned in
\r.I buf.
\rThe size of
\r.I buf
\ris passed to the routine via the
\r.I length
\rparameter.
\r.PP
\r.I des_string_to_key
\rconverts a string into a valid des key.
\r.PP
\r.I des_string_to_2key
\rconverts a string into 2 valid des keys.
\rThis routine is best suited for used to generate keys for use with
\r.I des_3ecb_encrypt.
\r.PP
\r.I des_random_key
\rreturns a random key that is made of a combination of process id,
\rtime and an increasing counter.
\r.PP
\rBefore a des key can be used it is converted into a
\r.I des_key_schedule
\rvia the
\r.I des_set_key
\rroutine.
\rIf the
\r.I des_check_key
\rflag is non-zero,
\r.I des_set_key
\rwill check that the key passed is of odd parity and is not a week or
\rsemi-weak key.
\rIf the parity is wrong,
\rthen -1 is returned.
\rIf the key is a weak key,
\rthen -2 is returned.
\rIf an error is returned,
\rthe key schedule is not generated.
\r.PP
\r.I des_key_sched
\ris another name for the
\r.I des_set_key
\rfunction.
\r.PP
\rThe following routines mostly operate on an input and output stream of
\r.I des_cblock's.
\r.PP
\r.I des_ecb_encrypt
\ris the basic DES encryption routine that encrypts or decrypts a single 8-byte
\r.I des_cblock
\rin
\r.I electronic code book
\rmode.
\rIt always transforms the input data, pointed to by
\r.I input,
\rinto the output data,
\rpointed to by the
\r.I output
\rargument.
\rIf the
\r.I encrypt
\rargument is non-zero (DES_ENCRYPT),
\rthe
\r.I input
\r(cleartext) is encrypted in to the
\r.I output
\r(ciphertext) using the key_schedule specified by the
\r.I schedule
\rargument,
\rpreviously set via
\r.I des_set_key.
\rIf
\r.I encrypt
\ris zero (DES_DECRYPT),
\rthe
\r.I input
\r(now ciphertext)
\ris decrypted into the
\r.I output
\r(now cleartext).
\rInput and output may overlap.
\rNo meaningful value is returned.
\r.PP
\r.I des_3ecb_encrypt
\rencrypts/decrypts the
\r.I input
\rblock by using triple ecb DES encryption.
\rThis involves encrypting the input with
\r.I ks1,
\rdecryption with the key schedule
\r.I ks2,
\rand then encryption with the first again.
\rThis routine greatly reduces the chances of brute force breaking of
\rDES and has the advantage of if
\r.I ks1
\rand
\r.I ks2
\rare the same, it is equivalent to just encryption using ecb mode and
\r.I ks1
\ras the key.
\r.PP
\r.I des_cbc_encrypt
\rencrypts/decrypts using the
\r.I cipher-block-chaining
\rmode of DES.
\rIf the
\r.I encrypt
\rargument is non-zero,
\rthe routine cipher-block-chain encrypts the cleartext data pointed to by the
\r.I input
\rargument into the ciphertext pointed to by the
\r.I output
\rargument,
\rusing the key schedule provided by the
\r.I schedule
\rargument,
\rand initialisation vector provided by the
\r.I ivec
\rargument.
\rIf the
\r.I length
\rargument is not an integral multiple of eight bytes,
\rthe last block is copied to a temporary area and zero filled.
\rThe output is always
\ran integral multiple of eight bytes.
\rTo make multiple cbc encrypt calls on a large amount of data appear to
\rbe one
\r.I des_cbc_encrypt
\rcall, the
\r.I ivec
\rof subsequent calls should be the last 8 bytes of the output.
\r.PP
\r.I des_3cbc_encrypt
\rencrypts/decrypts the
\r.I input
\rblock by using triple cbc DES encryption.
\rThis involves encrypting the input with key schedule
\r.I ks1,
\rdecryption with the key schedule
\r.I ks2,
\rand then encryption with the first again.
\r2 initialisation vectors are required,
\r.I ivec1
\rand
\r.I ivec2.
\rUnlike
\r.I des_cbc_encrypt,
\rthese initialisation vectors are modified by the subroutine.
\rThis routine greatly reduces the chances of brute force breaking of
\rDES and has the advantage of if
\r.I ks1
\rand
\r.I ks2
\rare the same, it is equivalent to just encryption using cbc mode and
\r.I ks1
\ras the key.
\r.PP
\r.I des_pcbc_encrypt
\rencrypt/decrypts using a modified block chaining mode.
\rIt provides better error propagation characteristics than cbc
\rencryption.
\r.PP
\r.I des_cfb_encrypt
\rencrypt/decrypts using cipher feedback mode. This method takes an
\rarray of characters as input and outputs and array of characters. It
\rdoes not require any padding to 8 character groups. Note: the ivec
\rvariable is changed and the new changed value needs to be passed to
\rthe next call to this function. Since this function runs a complete
\rDES ecb encryption per numbits, this function is only suggested for
\ruse when sending small numbers of characters.
\r.PP
\r.I des_ofb_encrypt
\rencrypt using output feedback mode. This method takes an
\rarray of characters as input and outputs and array of characters. It
\rdoes not require any padding to 8 character groups. Note: the ivec
\rvariable is changed and the new changed value needs to be passed to
\rthe next call to this function. Since this function runs a complete
\rDES ecb encryption per numbits, this function is only suggested for
\ruse when sending small numbers of characters.
\r.PP
\r.I des_cbc_cksum
\rproduces an 8 byte checksum based on the input stream (via cbc encryption).
\rThe last 4 bytes of the checksum is returned and the complete 8 bytes is
\rplaced in
\r.I output.
\r.PP
\r.I des_quad_cksum
\rreturns a 4 byte checksum from the input bytes.
\rThe algorithm can be iterated over the input,
\rdepending on
\r.I out_count,
\r1, 2, 3 or 4 times.
\rIf
\r.I output
\ris non-NULL,
\rthe 8 bytes generated by each pass are written into
\r.I output.
\r.PP
\r.I des_enc_write
\ris used to write
\r.I len
\rbytes
\rto file descriptor
\r.I fd
\rfrom buffer
\r.I buf.
\rThe data is encrypted via
\r.I pcbc_encrypt
\r(default) using
\r.I sched
\rfor the key and
\r.I iv
\ras a starting vector.
\rThe actual data send down
\r.I fd
\rconsists of 4 bytes (in network byte order) containing the length of the
\rfollowing encrypted data. The encrypted data then follows, padded with random
\rdata out to a multiple of 8 bytes.
\r.PP
\r.I des_enc_read
\ris used to read
\r.I len
\rbytes
\rfrom file descriptor
\r.I fd
\rinto buffer
\r.I buf.
\rThe data being read from
\r.I fd
\ris assumed to have come from
\r.I des_enc_write
\rand is decrypted using
\r.I sched
\rfor the key schedule and
\r.I iv
\rfor the initial vector.
\rThe
\r.I des_enc_read/des_enc_write
\rpair can be used to read/write to files, pipes and sockets.
\rI have used them in implementing a version of rlogin in which all
\rdata is encrypted.
\r.PP
\r.I des_rw_mode
\ris used to specify the encryption mode to use with
\r.I des_enc_read
\rand
\r.I des_end_write.
\rIf set to
\r.I DES_PCBC_MODE
\r(the default), des_pcbc_encrypt is used.
\rIf set to
\r.I DES_CBC_MODE
\rdes_cbc_encrypt is used.
\rThese two routines and the variable are not part of the normal MIT library.
\r.PP
\r.I des_set_odd_parity
\rsets the parity of the passed
\r.I key
\rto odd. This routine is not part of the standard MIT library.
\r.PP
\r.I des_is_weak_key
\rreturns 1 is the passed key is a weak key (pick again :-),
\r0 if it is ok.
\rThis routine is not part of the standard MIT library.
\r.PP
\r.I crypt
\ris a replacement for the normal system crypt.
\rIt is much faster than the system crypt.
\r.PP
\r.SH FILES
\r/usr/include/des.h
\r.br
\r/usr/lib/libdes.a
\r.PP
\rThe encryption routines have been tested on 16bit, 32bit and 64bit
\rmachines of various endian and even works under VMS.
\r.PP
\r.SH BUGS
\r.PP
\rIf you think this manual is sparse,
\rread the des_crypt(3) manual from the MIT kerberos (or bones outside
\rof the USA) distribution.
\r.PP
\r.I des_cfb_encrypt
\rand
\r.I des_ofb_encrypt
\roperates on input of 8 bits. What this means is that if you set
\rnumbits to 12, and length to 2, the first 12 bits will come from the 1st
\rinput byte and the low half of the second input byte. The second 12
\rbits will have the low 8 bits taken from the 3rd input byte and the
\rtop 4 bits taken from the 4th input byte. The same holds for output.
\rThis function has been implemented this way because most people will
\rbe using a multiple of 8 and because once you get into pulling bytes input
\rbytes apart things get ugly!
\r.PP
\r.I des_read_pw_string
\ris the most machine/OS dependent function and normally generates the
\rmost problems when porting this code.
\r.PP
\r.I des_string_to_key
\ris probably different from the MIT version since there are lots
\rof fun ways to implement one-way encryption of a text string.
\r.PP
\rThe routines are optimised for 32 bit machines and so are not efficient
\ron IBM PCs.
\r.PP
\rNOTE: extensive work has been done on this library since this document
\rwas origionally written. Please try to read des.doc from the libdes
\rdistribution since it is far more upto date and documents more of the
\rfunctions. Libdes is now also being shipped as part of SSLeay, a
\rgeneral cryptographic library that amonst other things implements
\rnetscapes SSL protocoll. The most recent version can be found in
\rSSLeay distributions.
\r.SH AUTHOR
\rEric Young (eay@mincom.oz.au or eay@psych.psy.uq.oz.au)
\r
projects / cyrus-sasl.git / blob