Return to des_crypt.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / kerberosIV / man

Annotation of 43BSDReno/kerberosIV/man/des_crypt.3, revision 1.1

1.1     ! root        1: .\" $Source: /usr/src/kerberosIV/man/RCS/des_crypt.3,v $
        !             2: .\" $Author: kfall $
        !             3: .\" $Header: /usr/src/kerberosIV/man/RCS/des_crypt.3,v 4.4 90/06/25 21:11:49 kfall Exp $
        !             4: .\" Copyright 1989 by the Massachusetts Institute of Technology.
        !             5: .\"
        !             6: .\" For copying and distribution information,
        !             7: .\" please see the file <mit-copyright.h>.
        !             8: .\"
        !             9: .TH DES_CRYPT 3  "Kerberos Version 4.0" "MIT Project Athena"
        !            10: .SH NAME
        !            11: des_read_password, des_string_to_key, des_random_key, des_set_key,
        !            12: des_ecb_encrypt, des_cbc_encrypt, des_pcbc_encrypt, des_cbc_cksum,
        !            13: des_quad_cksum, \- (new) DES encryption
        !            14: .SH SYNOPSIS
        !            15: .nf
        !            16: .nj
        !            17: .ft B
        !            18: #include <kerberosIV/des.h>
        !            19: .PP
        !            20: .ft B
        !            21: .B int des_read_password(key,prompt,verify)
        !            22: des_cblock *key;
        !            23: char *prompt;
        !            24: int verify;
        !            25: .PP
        !            26: .ft B
        !            27: int des_string_to_key(str,key)
        !            28: char *str;
        !            29: des_cblock key;
        !            30: .PP
        !            31: .ft B
        !            32: int des_random_key(key)
        !            33: des_cblock *key;
        !            34: .PP
        !            35: .ft B
        !            36: int des_set_key(key,schedule)
        !            37: des_cblock *key;
        !            38: des_key_schedule schedule;
        !            39: .PP
        !            40: .ft B
        !            41: int des_ecb_encrypt(input,output,schedule,encrypt)
        !            42: des_cblock *input;
        !            43: des_cblock *output;
        !            44: des_key_schedule schedule;
        !            45: int encrypt;
        !            46: .PP
        !            47: .ft B
        !            48: int des_cbc_encrypt(input,output,length,schedule,ivec,encrypt)
        !            49: des_cblock *input;
        !            50: des_cblock *output;
        !            51: long length;
        !            52: des_key_schedule schedule;
        !            53: des_cblock *ivec;
        !            54: int encrypt;
        !            55: .PP
        !            56: .ft B
        !            57: int des_pcbc_encrypt(input,output,length,schedule,ivec,encrypt)
        !            58: des_cblock *input;
        !            59: des_cblock *output;
        !            60: long length;
        !            61: des_key_schedule schedule;
        !            62: des_cblock *ivec;
        !            63: int encrypt;
        !            64: .PP
        !            65: .ft B
        !            66: unsigned long des_cbc_cksum(input,output,length,schedule,ivec)
        !            67: des_cblock *input;
        !            68: des_cblock *output;
        !            69: long length;
        !            70: des_key_schedule schedule;
        !            71: des_cblock *ivec;
        !            72: .PP
        !            73: .ft B
        !            74: unsigned long quad_cksum(input,output,length,out_count,seed)
        !            75: des_cblock *input;
        !            76: des_cblock *output;
        !            77: long length;
        !            78: int out_count;
        !            79: des_cblock *seed;
        !            80: .PP
        !            81: .fi
        !            82: .SH DESCRIPTION
        !            83: This library supports various DES encryption related operations. It differs
        !            84: from the
        !            85: .I crypt, setkey, and encrypt
        !            86: library routines in that it provides
        !            87: a true DES encryption, without modifying the algorithm,
        !            88: and executes much faster.
        !            89: .PP
        !            90: For each key that may be simultaneously active, create a
        !            91: .B des_key_schedule
        !            92: struct,
        !            93: defined in "des.h". Next, create key schedules (from the 8-byte keys) as
        !            94: needed, via
        !            95: .I des_set_key,
        !            96: prior to using the encryption or checksum routines. Then
        !            97: setup the input and output areas.  Make sure to note the restrictions
        !            98: on lengths being multiples of eight bytes. Finally, invoke the
        !            99: encryption/decryption routines,
        !           100: .I des_ecb_encrypt
        !           101: or
        !           102: .I des_cbc_encrypt
        !           103: or
        !           104: .I des_pcbc_encrypt,
        !           105: or, to generate a cryptographic checksum, use
        !           106: .I quad_cksum
        !           107: (fast) or
        !           108: .I des_cbc_cksum
        !           109: (slow).
        !           110: .PP
        !           111: A
        !           112: .I des_cblock
        !           113: struct is an 8 byte block used as the fundamental unit for DES data and
        !           114: keys, and is defined as:
        !           115: .PP
        !           116: .B     typedef unsigned char des_cblock[8];
        !           117: .PP
        !           118: and a
        !           119: .I des_key_schedule,
        !           120: is defined as:
        !           121: .PP
        !           122: .B     typedef struct des_ks_struct {des_cblock _;}  des_key_schedule[16];
        !           123: .PP
        !           124: .I des_read_password
        !           125: writes the string specified by
        !           126: .I prompt
        !           127: to the standard
        !           128: output, turns off echo (if possible)
        !           129: and reads an input string from standard input until terminated with a newline.
        !           130: If
        !           131: .I verify
        !           132: is non-zero, it prompts and reads input again, for use
        !           133: in applications such as changing a password; both
        !           134: versions are compared, and the input is requested repeatedly until they
        !           135: match.  Then
        !           136: .I des_read_password
        !           137: converts the input string into a valid DES key, internally
        !           138: using the
        !           139: .I des_string_to_key
        !           140: routine.  The newly created key is copied to the
        !           141: area pointed to by the
        !           142: .I key
        !           143: argument.
        !           144: .I des_read_password
        !           145: returns a zero if no errors occurred, or a -1
        !           146: indicating that an error
        !           147: occurred trying to manipulate the terminal echo.
        !           148: .PP
        !           149: .PP
        !           150: .I des_string_to_key
        !           151: converts an arbitrary length null-terminated string
        !           152: to an 8 byte DES key, with odd byte parity, per FIPS specification.
        !           153: A one-way function is used to convert the string to a key, making it
        !           154: very difficult to reconstruct the string from the key.
        !           155: The
        !           156: .I str
        !           157: argument is a pointer to the string, and
        !           158: .I key
        !           159: should
        !           160: point to a
        !           161: .I des_cblock
        !           162: supplied by the caller to receive the generated key.
        !           163: No meaningful value is returned. Void is not used for compatibility with
        !           164: other compilers.
        !           165: .PP
        !           166: .PP
        !           167: .I des_random_key
        !           168: generates a random DES encryption key (eight bytes), set to odd parity per
        !           169: FIPS
        !           170: specifications.
        !           171: This routine uses the current time, process id, and a counter
        !           172: as a seed for the random number generator.
        !           173: The caller must        supply space for the output key, pointed to
        !           174: by argument
        !           175: .I key,
        !           176: then after calling
        !           177: .I des_random_key
        !           178: should
        !           179: call the
        !           180: .I des_set_key
        !           181: routine when needed.
        !           182: No meaningful value is returned.  Void is not used for compatibility
        !           183: with other compilers.
        !           184: .PP
        !           185: .PP
        !           186: .I des_set_key
        !           187: calculates a key schedule from all eight bytes of the input key, pointed
        !           188: to by the
        !           189: .I key
        !           190: argument, and outputs the schedule into the
        !           191: .I des_key_schedule
        !           192: indicated by the
        !           193: .I schedule
        !           194: argument. Make sure to pass a valid eight byte
        !           195: key; no padding is done.  The key schedule may then be used in subsequent
        !           196: encryption/decryption/checksum operations.  Many key schedules may be
        !           197: cached for later use.  The user is responsible to clear keys and schedules
        !           198: as soon as no longer needed, to prevent their disclosure.
        !           199: The routine also checks the key
        !           200: parity, and returns a zero if the key parity is correct (odd), a -1
        !           201: indicating a key parity error, or a -2 indicating use of an illegal
        !           202: weak key. If an error is returned, the key schedule was not created.
        !           203: .PP
        !           204: .PP
        !           205: .I des_ecb_encrypt
        !           206: is the basic DES encryption routine that encrypts or decrypts a single 8-byte
        !           207: block in
        !           208: .B electronic code book
        !           209: mode.  It always transforms the input data, pointed to by
        !           210: .I input,
        !           211: into the output data, pointed to by the
        !           212: .I output
        !           213: argument.
        !           214: .PP
        !           215: If the
        !           216: .I encrypt
        !           217: argument is non-zero, the
        !           218: .I input
        !           219: (cleartext) is encrypted into the
        !           220: .I output
        !           221: (ciphertext) using the key_schedule specified by the
        !           222: .I schedule
        !           223: argument, previously set via
        !           224: .I des_set_key
        !           225: .PP
        !           226: If encrypt is zero, the
        !           227: .I input
        !           228: (now ciphertext) is decrypted into the
        !           229: .I output
        !           230: (now cleartext).
        !           231: .PP
        !           232: Input and output may overlap.
        !           233: .PP
        !           234: No meaningful value is returned.  Void is not used for compatibility
        !           235: with other compilers.
        !           236: .PP
        !           237: .PP
        !           238: .I des_cbc_encrypt
        !           239: encrypts/decrypts using the
        !           240: .B cipher-block-chaining mode of DES.
        !           241: If the
        !           242: .I encrypt
        !           243: argument is non-zero, the routine cipher-block-chain encrypts
        !           244: the cleartext data pointed to by the
        !           245: .I input
        !           246: argument into the ciphertext pointed to by the
        !           247: .I output
        !           248: argument, using the key schedule provided by the
        !           249: .I schedule
        !           250: argument, and initialization vector provided by the
        !           251: .I ivec
        !           252: argument.
        !           253: If the
        !           254: .I length
        !           255: argument is not an integral
        !           256: multiple of eight bytes, the last block is copied to a temp and zero
        !           257: filled (highest addresses).  The output is ALWAYS an integral multiple
        !           258: of eight bytes.
        !           259: .PP
        !           260: If
        !           261: .I encrypt
        !           262: is zero, the routine cipher-block chain decrypts the (now) ciphertext
        !           263: data pointed to by the
        !           264: .I input
        !           265: argument into (now) cleartext pointed to by the
        !           266: .I output
        !           267: argument using the key schedule provided by the
        !           268: .I schedule
        !           269: argument, and initialization vector provided by the
        !           270: .I ivec
        !           271: argument. Decryption ALWAYS operates on integral
        !           272: multiples of 8 bytes, so it will round the
        !           273: .I length
        !           274: provided up to the
        !           275: appropriate multiple. Consequently, it will always produce the rounded-up
        !           276: number of bytes of output cleartext. The application must determine if
        !           277: the output cleartext was zero-padded due to original cleartext lengths that
        !           278: were not integral multiples of 8.
        !           279: .PP
        !           280: No errors or meaningful values are returned.  Void is not used for
        !           281: compatibility with other compilers.
        !           282: .PP
        !           283: A characteristic of cbc mode is that changing a single bit of the
        !           284: cleartext, then encrypting using cbc mode,
        !           285: affects ALL the subsequent ciphertext.  This makes cryptanalysis
        !           286: much more difficult. However, modifying a single bit of the ciphertext,
        !           287: then decrypting, only affects the resulting cleartext from
        !           288: the modified block and the succeeding block.  Therefore,
        !           289: .I des_pcbc_encrypt
        !           290: is STRONGLY recommended for applications where
        !           291: indefinite propagation of errors is required in order to detect modifications.
        !           292: .PP
        !           293: .PP
        !           294: .I des_pcbc_encrypt
        !           295: encrypts/decrypts using a modified block chaining mode. Its calling
        !           296: sequence is identical to
        !           297: .I des_cbc_encrypt.
        !           298: It differs in its error propagation characteristics.
        !           299: .PP
        !           300: .I des_pcbc_encrypt
        !           301: is highly recommended for most encryption purposes, in that
        !           302: modification of a single bit of the ciphertext will affect ALL the
        !           303: subsequent (decrypted) cleartext. Similarly, modifying a single bit of
        !           304: the cleartext will affect ALL the subsequent (encrypted) ciphertext.
        !           305: "PCBC" mode, on encryption, "xors" both the
        !           306: cleartext of block N and the ciphertext resulting from block N with the
        !           307: cleartext for block N+1 prior to encrypting block N+1.
        !           308: .PP
        !           309: .I des_cbc_cksum
        !           310: produces an 8 byte cryptographic checksum by cipher-block-chain
        !           311: encrypting the cleartext data pointed to by the
        !           312: .I input
        !           313: argument. All of the ciphertext output is discarded, except the
        !           314: last 8-byte ciphertext block, which is written into the area pointed to by
        !           315: the
        !           316: .I output
        !           317: argument.
        !           318: It uses the key schedule,
        !           319: provided by the
        !           320: .I schedule
        !           321: argument and initialization vector provided by the
        !           322: .I ivec
        !           323: argument.
        !           324: If the
        !           325: .I length
        !           326: argument is not an integral
        !           327: multiple of eight bytes, the last cleartext block is copied to a temp and zero
        !           328: filled (highest addresses).  The output is ALWAYS eight bytes.
        !           329: .PP
        !           330: The routine also returns an unsigned long, which is the last (highest address)
        !           331: half of the 8 byte checksum computed.
        !           332: .PP
        !           333: .PP
        !           334: .I quad_cksum
        !           335: produces a checksum by chaining quadratic operations on the cleartext data
        !           336: pointed to by the
        !           337: .I input
        !           338: argument. The
        !           339: .I length
        !           340: argument specifies the length of the
        !           341: input -- only exactly that many bytes are included for the checksum,
        !           342: without any padding.
        !           343: .PP
        !           344: The algorithm may be iterated over the same input data, if the
        !           345: .I out_count
        !           346: argument is 2, 3 or 4, and the optional
        !           347: .I output
        !           348: argument is a non-null pointer .
        !           349: The default is one iteration, and it will not run
        !           350: more than 4 times. Multiple iterations run slower, but provide
        !           351: a longer checksum if desired. The
        !           352: .I seed
        !           353: argument provides an 8-byte seed for the first iteration. If multiple iterations are
        !           354: requested, the results of one iteration are automatically used as
        !           355: the seed for the next iteration.
        !           356: .PP
        !           357: It returns both an unsigned long checksum value, and
        !           358: if the
        !           359: .I output
        !           360: argument is not a null pointer, up to 16 bytes of
        !           361: the computed checksum are written into the output.
        !           362: .PP
        !           363: .PP
        !           364: .SH FILES
        !           365: /usr/include/kerberosIV/des.h
        !           366: .br
        !           367: /usr/lib/libdes.a
        !           368: .SH "SEE ALSO"
        !           369: .SH DIAGNOSTICS
        !           370: .SH BUGS
        !           371: This software has not yet been compiled or tested on machines other than the
        !           372: VAX and the IBM PC.
        !           373: .SH AUTHORS
        !           374: Steve Miller, MIT Project Athena/Digital Equipment Corporation
        !           375: .SH RESTRICTIONS
        !           376: COPYRIGHT 1985,1986 Massachusetts Institute of Technology
        !           377: .PP
        !           378: This software may not be exported outside of the US without a special
        !           379: license from the US Dept of Commerce. It may be replaced by any secret
        !           380: key block cipher with block length and key length of 8 bytes, as long
        !           381: as the interface is the same as described here.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.