BSD 4_3_Reno development

[unix-history] / usr / share / man / cat3 / des.0

DES_CRYPT(3)		       4.0		     DES_CRYPT(3)



N\bNA\bAM\bME\bE
     des_read_password, des_string_to_key, des_random_key,
     des_set_key, des_ecb_encrypt, des_cbc_encrypt,
     des_pcbc_encrypt, des_cbc_cksum, des_quad_cksum, - (new) DES
     encryption

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
     #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<k\bke\ber\brb\bbe\ber\bro\bos\bsI\bIV\bV/\b/d\bde\bes\bs.\b.h\bh>\b>

     i\bin\bnt\bt d\bde\bes\bs_\b_r\bre\bea\bad\bd_\b_p\bpa\bas\bss\bsw\bwo\bor\brd\bd(\b(k\bke\bey\by,\b,p\bpr\bro\bom\bmp\bpt\bt,\b,v\bve\ber\bri\bif\bfy\by)\b)
     des_cblock *key;
     char *prompt;
     int verify;

     i\bin\bnt\bt d\bde\bes\bs_\b_s\bst\btr\bri\bin\bng\bg_\b_t\bto\bo_\b_k\bke\bey\by(\b(s\bst\btr\br,\b,k\bke\bey\by)\b)
     c\bch\bha\bar\br *\b*s\bst\btr\br;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk k\bke\bey\by;\b;

     i\bin\bnt\bt d\bde\bes\bs_\b_r\bra\ban\bnd\bdo\bom\bm_\b_k\bke\bey\by(\b(k\bke\bey\by)\b)
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*k\bke\bey\by;\b;

     i\bin\bnt\bt d\bde\bes\bs_\b_s\bse\bet\bt_\b_k\bke\bey\by(\b(k\bke\bey\by,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be)\b)
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*k\bke\bey\by;\b;
     d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;

     i\bin\bnt\bt d\bde\bes\bs_\b_e\bec\bcb\bb_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
     d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
     i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;

     i\bin\bnt\bt d\bde\bes\bs_\b_c\bcb\bbc\bc_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
     l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
     d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;
     i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;

     i\bin\bnt\bt d\bde\bes\bs_\b_p\bpc\bcb\bbc\bc_\b_e\ben\bnc\bcr\bry\byp\bpt\bt(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc,\b,e\ben\bnc\bcr\bry\byp\bpt\bt)\b)
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
     l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
     d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;
     i\bin\bnt\bt e\ben\bnc\bcr\bry\byp\bpt\bt;\b;

     u\bun\bns\bsi\big\bgn\bne\bed\bd l\blo\bon\bng\bg d\bde\bes\bs_\b_c\bcb\bbc\bc_\b_c\bck\bks\bsu\bum\bm(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b,i\biv\bve\bec\bc)\b)
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
     l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
     d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;



Printed 7/27/90             Kerberos				1






DES_CRYPT(3)		       4.0		     DES_CRYPT(3)



     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\biv\bve\bec\bc;\b;

     u\bun\bns\bsi\big\bgn\bne\bed\bd l\blo\bon\bng\bg q\bqu\bua\bad\bd_\b_c\bck\bks\bsu\bum\bm(\b(i\bin\bnp\bpu\but\bt,\b,o\bou\but\btp\bpu\but\bt,\b,l\ble\ben\bng\bgt\bth\bh,\b,o\bou\but\bt_\b_c\bco\bou\bun\bnt\bt,\b,s\bse\bee\bed\bd)\b)
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*i\bin\bnp\bpu\but\bt;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*o\bou\but\btp\bpu\but\bt;\b;
     l\blo\bon\bng\bg l\ble\ben\bng\bgt\bth\bh;\b;
     i\bin\bnt\bt o\bou\but\bt_\b_c\bco\bou\bun\bnt\bt;\b;
     d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk *\b*s\bse\bee\bed\bd;\b;

D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
     This library supports various DES encryption related opera-
     tions. It differs from the _\bc_\br_\by_\bp_\bt, _\bs_\be_\bt_\bk_\be_\by, _\ba_\bn_\bd _\be_\bn_\bc_\br_\by_\bp_\bt
     library routines in that it provides a true DES encryption,
     without modifying the algorithm, and executes much faster.

     For each key that may be simultaneously active, create a
     d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be struct, defined in "des.h". Next, create
     key schedules (from the 8-byte keys) as needed, via
     _\bd_\be_\bs__\bs_\be_\bt__\bk_\be_\by, prior to using the encryption or checksum rou-
     tines. Then setup the input and output areas.  Make sure to
     note the restrictions on lengths being multiples of eight
     bytes. Finally, invoke the encryption/decryption routines,
     _\bd_\be_\bs__\be_\bc_\bb__\be_\bn_\bc_\br_\by_\bp_\bt or _\bd_\be_\bs__\bc_\bb_\bc__\be_\bn_\bc_\br_\by_\bp_\bt or _\bd_\be_\bs__\bp_\bc_\bb_\bc__\be_\bn_\bc_\br_\by_\bp_\bt, or,
     to generate a cryptographic checksum, use _\bq_\bu_\ba_\bd__\bc_\bk_\bs_\bu_\bm (fast)
     or _\bd_\be_\bs__\bc_\bb_\bc__\bc_\bk_\bs_\bu_\bm (slow).

     A _\bd_\be_\bs__\bc_\bb_\bl_\bo_\bc_\bk struct is an 8 byte block used as the fundamen-
     tal unit for DES data and keys, and is defined as:

	t\bty\byp\bpe\bed\bde\bef\bf     u\bun\bns\bsi\big\bgn\bne\bed\bd c\bch\bha\bar\br d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk[\b[8\b8]\b];\b;

     and a _\bd_\be_\bs__\bk_\be_\by__\bs_\bc_\bh_\be_\bd_\bu_\bl_\be, is defined as:

	t\bty\byp\bpe\bed\bde\bef\bf     s\bst\btr\bru\buc\bct\bt d\bde\bes\bs_\b_k\bks\bs_\b_s\bst\btr\bru\buc\bct\bt {\b{d\bde\bes\bs_\b_c\bcb\bbl\blo\boc\bck\bk _\b_;\b;}\b}
     d\bde\bes\bs_\b_k\bke\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be[\b[1\b16\b6]\b];\b;

     _\bd_\be_\bs__\br_\be_\ba_\bd__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd writes the string specified by _\bp_\br_\bo_\bm_\bp_\bt to
     the standard output, turns off echo (if possible) and reads
     an input string from standard input until terminated with a
     newline.  If _\bv_\be_\br_\bi_\bf_\by is non-zero, it prompts and reads input
     again, for use in applications such as changing a password;
     both versions are compared, and the input is requested
     repeatedly until they match.  Then _\bd_\be_\bs__\br_\be_\ba_\bd__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd con-
     verts the input string into a valid DES key, internally
     using the _\bd_\be_\bs__\bs_\bt_\br_\bi_\bn_\bg__\bt_\bo__\bk_\be_\by routine.  The newly created key
     is copied to the area pointed to by the _\bk_\be_\by argument.
     _\bd_\be_\bs__\br_\be_\ba_\bd__\bp_\ba_\bs_\bs_\bw_\bo_\br_\bd returns a zero if no errors occurred, or a
     -1 indicating that an error occurred trying to manipulate
     the terminal echo.

     _\bd_\be_\bs__\bs_\bt_\br_\bi_\bn_\bg__\bt_\bo__\bk_\be_\by converts an arbitrary length null-
     terminated string to an 8 byte DES key, with odd byte



Printed 7/27/90             Kerberos				2






DES_CRYPT(3)		       4.0		     DES_CRYPT(3)



     parity, per FIPS specification.  A one-way function is used
     to convert the string to a key, making it very difficult to
     reconstruct the string from the key.  The _\bs_\bt_\br argument is a
     pointer to the string, and _\bk_\be_\by should point to a _\bd_\be_\bs__\bc_\bb_\bl_\bo_\bc_\bk
     supplied by the caller to receive the generated key.  No
     meaningful value is returned. Void is not used for compati-
     bility with other compilers.

     _\bd_\be_\bs__\br_\ba_\bn_\bd_\bo_\bm__\bk_\be_\by generates a random DES encryption key (eight
     bytes), set to odd parity per FIPS specifications.  This
     routine uses the current time, process id, and a counter as
     a seed for the random number generator.  The caller
     must     supply space for the output key, pointed to by
     argument _\bk_\be_\by, then after calling _\bd_\be_\bs__\br_\ba_\bn_\bd_\bo_\bm__\bk_\be_\by should call
     the _\bd_\be_\bs__\bs_\be_\bt__\bk_\be_\by routine when needed.  No meaningful value is
     returned.	Void is not used for compatibility with other
     compilers.

     _\bd_\be_\bs__\bs_\be_\bt__\bk_\be_\by calculates a key schedule from all eight bytes
     of the input key, pointed to by the _\bk_\be_\by argument, and out-
     puts the schedule into the _\bd_\be_\bs__\bk_\be_\by__\bs_\bc_\bh_\be_\bd_\bu_\bl_\be indicated by the
     _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument. Make sure to pass a valid eight byte key;
     no padding is done.  The key schedule may then be used in
     subsequent encryption/decryption/checksum operations.  Many
     key schedules may be cached for later use.  The user is
     responsible to clear keys and schedules as soon as no longer
     needed, to prevent their disclosure.  The routine also
     checks the key parity, and returns a zero if the key parity
     is correct (odd), a -1 indicating a key parity error, or a
     -2 indicating use of an illegal weak key. If an error is
     returned, the key schedule was not created.

     _\bd_\be_\bs__\be_\bc_\bb__\be_\bn_\bc_\br_\by_\bp_\bt is the basic DES encryption routine that
     encrypts or decrypts a single 8-byte block in e\bel\ble\bec\bct\btr\bro\bon\bni\bic\bc
     c\bco\bod\bde\be b\bbo\boo\bok\bk mode.  It always transforms the input data,
     pointed to by _\bi_\bn_\bp_\bu_\bt, into the output data, pointed to by the
     _\bo_\bu_\bt_\bp_\bu_\bt argument.

     If the _\be_\bn_\bc_\br_\by_\bp_\bt argument is non-zero, the _\bi_\bn_\bp_\bu_\bt (cleartext)
     is encrypted into the _\bo_\bu_\bt_\bp_\bu_\bt (ciphertext) using the
     key_schedule specified by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument, previously
     set via _\bd_\be_\bs__\bs_\be_\bt__\bk_\be_\by

     If encrypt is zero, the _\bi_\bn_\bp_\bu_\bt (now ciphertext) is decrypted
     into the _\bo_\bu_\bt_\bp_\bu_\bt (now cleartext).

     Input and output may overlap.

     No meaningful value is returned.  Void is not used for com-
     patibility with other compilers.





Printed 7/27/90             Kerberos				3






DES_CRYPT(3)		       4.0		     DES_CRYPT(3)



     _\bd_\be_\bs__\bc_\bb_\bc__\be_\bn_\bc_\br_\by_\bp_\bt encrypts/decrypts using the c\bci\bip\bph\bhe\ber\br-\b-b\bbl\blo\boc\bck\bk-\b-
     c\bch\bha\bai\bin\bni\bin\bng\bg m\bmo\bod\bde\be o\bof\bf D\bDE\bES\bS.\b. If the _\be_\bn_\bc_\br_\by_\bp_\bt argument is non-zero,
     the routine cipher-block-chain encrypts the cleartext data
     pointed to by the _\bi_\bn_\bp_\bu_\bt argument into the ciphertext pointed
     to by the _\bo_\bu_\bt_\bp_\bu_\bt argument, using the key schedule provided
     by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument, and initialization vector provided
     by the _\bi_\bv_\be_\bc argument.  If the _\bl_\be_\bn_\bg_\bt_\bh argument is not an
     integral multiple of eight bytes, the last block is copied
     to a temp and zero filled (highest addresses).  The output
     is ALWAYS an integral multiple of eight bytes.

     If _\be_\bn_\bc_\br_\by_\bp_\bt is zero, the routine cipher-block chain decrypts
     the (now) ciphertext data pointed to by the _\bi_\bn_\bp_\bu_\bt argument
     into (now) cleartext pointed to by the _\bo_\bu_\bt_\bp_\bu_\bt argument using
     the key schedule provided by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument, and ini-
     tialization vector provided by the _\bi_\bv_\be_\bc argument. Decryption
     ALWAYS operates on integral multiples of 8 bytes, so it will
     round the _\bl_\be_\bn_\bg_\bt_\bh provided up to the appropriate multiple.
     Consequently, it will always produce the rounded-up number
     of bytes of output cleartext. The application must determine
     if the output cleartext was zero-padded due to original
     cleartext lengths that were not integral multiples of 8.

     No errors or meaningful values are returned.  Void is not
     used for compatibility with other compilers.

     A characteristic of cbc mode is that changing a single bit
     of the cleartext, then encrypting using cbc mode, affects
     ALL the subsequent ciphertext.  This makes cryptanalysis
     much more difficult. However, modifying a single bit of the
     ciphertext, then decrypting, only affects the resulting
     cleartext from the modified block and the succeeding block.
     Therefore, _\bd_\be_\bs__\bp_\bc_\bb_\bc__\be_\bn_\bc_\br_\by_\bp_\bt is STRONGLY recommended for
     applications where indefinite propagation of errors is
     required in order to detect modifications.

     _\bd_\be_\bs__\bp_\bc_\bb_\bc__\be_\bn_\bc_\br_\by_\bp_\bt encrypts/decrypts using a modified block
     chaining mode. Its calling sequence is identical to
     _\bd_\be_\bs__\bc_\bb_\bc__\be_\bn_\bc_\br_\by_\bp_\bt. It differs in its error propagation charac-
     teristics.

     _\bd_\be_\bs__\bp_\bc_\bb_\bc__\be_\bn_\bc_\br_\by_\bp_\bt is highly recommended for most encryption
     purposes, in that modification of a single bit of the
     ciphertext will affect ALL the subsequent (decrypted) clear-
     text. Similarly, modifying a single bit of the cleartext
     will affect ALL the subsequent (encrypted) ciphertext.
     "PCBC" mode, on encryption, "xors" both the cleartext of
     block N and the ciphertext resulting from block N with the
     cleartext for block N+1 prior to encrypting block N+1.

     _\bd_\be_\bs__\bc_\bb_\bc__\bc_\bk_\bs_\bu_\bm produces an 8 byte cryptographic checksum by
     cipher-block-chain encrypting the cleartext data pointed to



Printed 7/27/90             Kerberos				4






DES_CRYPT(3)		       4.0		     DES_CRYPT(3)



     by the _\bi_\bn_\bp_\bu_\bt argument. All of the ciphertext output is dis-
     carded, except the last 8-byte ciphertext block, which is
     written into the area pointed to by the _\bo_\bu_\bt_\bp_\bu_\bt argument.  It
     uses the key schedule, provided by the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument and
     initialization vector provided by the _\bi_\bv_\be_\bc argument.  If the
     _\bl_\be_\bn_\bg_\bt_\bh argument is not an integral multiple of eight bytes,
     the last cleartext block is copied to a temp and zero filled
     (highest addresses).  The output is ALWAYS eight bytes.

     The routine also returns an unsigned long, which is the last
     (highest address) half of the 8 byte checksum computed.

     _\bq_\bu_\ba_\bd__\bc_\bk_\bs_\bu_\bm produces a checksum by chaining quadratic opera-
     tions on the cleartext data pointed to by the _\bi_\bn_\bp_\bu_\bt argu-
     ment. The _\bl_\be_\bn_\bg_\bt_\bh argument specifies the length of the input
     -- only exactly that many bytes are included for the check-
     sum, without any padding.

     The algorithm may be iterated over the same input data, if
     the _\bo_\bu_\bt__\bc_\bo_\bu_\bn_\bt argument is 2, 3 or 4, and the optional _\bo_\bu_\bt_\bp_\bu_\bt
     argument is a non-null pointer .  The default is one itera-
     tion, and it will not run more than 4 times. Multiple itera-
     tions run slower, but provide a longer checksum if desired.
     The _\bs_\be_\be_\bd argument provides an 8-byte seed for the first
     iteration. If multiple iterations are requested, the results
     of one iteration are automatically used as the seed for the
     next iteration.

     It returns both an unsigned long checksum value, and if the
     _\bo_\bu_\bt_\bp_\bu_\bt argument is not a null pointer, up to 16 bytes of the
     computed checksum are written into the output.

F\bFI\bIL\bLE\bES\bS
     /usr/include/kerberosIV/des.h
     /usr/lib/libdes.a

S\bSE\bEE\bE A\bAL\bLS\bSO\bO
D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS
B\bBU\bUG\bGS\bS
     This software has not yet been compiled or tested on
     machines other than the VAX and the IBM PC.

A\bAU\bUT\bTH\bHO\bOR\bRS\bS
     Steve Miller, MIT Project Athena/Digital Equipment Corpora-
     tion

R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTI\bIO\bON\bNS\bS
     COPYRIGHT 1985,1986 Massachusetts Institute of Technology

     This software may not be exported outside of the US without
     a special license from the US Dept of Commerce. It may be
     replaced by any secret key block cipher with block length



Printed 7/27/90             Kerberos				5






DES_CRYPT(3)		       4.0		     DES_CRYPT(3)



     and key length of 8 bytes, as long as the interface is the
     same as described here.





















































Printed 7/27/90             Kerberos				6