Return to libdes.doc CVS log

Up to [CSRG BSD Unix] / 43BSDReno / kerberosIV / des / doc

Annotation of 43BSDReno/kerberosIV/des/doc/libdes.doc, revision 1.1

1.1     ! root        1: 
        !             2:        How to use the Kerberos encryption library.
        !             3: 
        !             4:                        Revised         10/15/85        spm
        !             5: 
        !             6: 1)     The following include file is needed:
        !             7:        
        !             8:        /projects/auth/include/des.h    (VAX)
        !             9:        ---------------                                 (PC8086)
        !            10: 
        !            11: 2)     The encryption library that should be linked to is:
        !            12:        
        !            13:        /projects/auth/lib/libdes.a             (VAX)
        !            14: |      /projects/auth/ibm/lib/libdes.a (PC8086 cross-compilation environment)
        !            15: 
        !            16: 3)     For each key that may be simultaneously active,
        !            17:        allocate (either compile or malloc) a "Key_schedule" struct, 
        !            18:        defined in "des.h"
        !            19: 
        !            20: 4)     Create key schedules, as needed, prior to using the encryption
        !            21:        routines, via "des_set_key()".
        !            22: 
        !            23: 5)  Setup the input and output areas.  Make sure to note the restrictions
        !            24:        on lengths being multiples of eight bytes.
        !            25: 
        !            26: 6)     Invoke the encryption/decryption routines, "ecb_encrypt()"
        !            27:         or "cbc_encrypt()"
        !            28: 
        !            29: 7)     To generate a cryptographic checksum, use "cbc_cksum()"
        !            30: /*     ----------------------------------------------------------------        */
        !            31:        
        !            32:        Routine Interfaces--
        !            33: 
        !            34: /*     -----------------------------------------------------------------       */
        !            35: 
        !            36: int
        !            37:        des_set_key(k,schedule)
        !            38:                C_Block                 *k;
        !            39:                Key_schedule    schedule;
        !            40: 
        !            41:        Calculates a key schedule from (all) eight bytes of the input key, and
        !            42:        puts it into the indicated "Key_schedule" struct;
        !            43: 
        !            44:        Make sure to pass valid eight bytes, no padding or other processing
        !            45:        it done.
        !            46: 
        !            47:        The key schedule is then used in subsequent encryption/decryption
        !            48:        operations.  Many key schedules may be created and cached for later
        !            49:        use.
        !            50: 
        !            51:        The user is responsible to clear keys and schedules no longer needed
        !            52:        to prevent their disclosure.
        !            53: 
        !            54: |      Checks the parity of the key provided, to make sure it is odd per
        !            55: |      FIPS spec.  Returns 0 value for key ok, 1 for key_parity error.
        !            56: 
        !            57: /*     ----------------------------------------------------------------        */
        !            58:        
        !            59: int
        !            60:        ecb_encrypt(input,output,schedule,encrypt)
        !            61:                C_Block                 *input;         /* ptr to eight byte input value */
        !            62:                C_Block                 *output;        /* ptr to eight byte output value */
        !            63:                int                             encrypt;        /* 0 ==> decrypt, else encrypt */
        !            64:                Key_schedule    schedule;       /* addr of key schedule */
        !            65: 
        !            66: This is the low level routine that encrypts or decrypts a single 8-byte
        !            67: block in electronic code book mode.  Always transforms the input
        !            68: data into the output data.
        !            69: 
        !            70: If encrypt is non-zero, the input (cleartext) is encrypted into the
        !            71: output (ciphertext) using the specified key_schedule, pre-set via "des_set_key".
        !            72: 
        !            73: If encrypt is zero, the input (now ciphertext) is decrypted into
        !            74: the output (now cleartext).
        !            75: 
        !            76: Input and output may be the same space.
        !            77: 
        !            78: Does not return any meaningful value.  Void is not used for compatibility
        !            79: with other compilers.
        !            80: 
        !            81: /*     --------------------------------------------------------------  */
        !            82: 
        !            83: int    
        !            84:        cbc_encrypt(input,output,length,schedule,ivec,encrypt)
        !            85: 
        !            86:                C_Block                 *input;         /* ptr to input data */
        !            87:                C_Block                 *output;        /* ptr to output data */
        !            88:                int                             length;         /* desired length, in bytes */
        !            89:                Key_schedule    schedule;               /* addr of precomputed schedule */
        !            90:                C_Block                 *ivec;          /* pointer to 8 byte initialization
        !            91:                                                                         * vector
        !            92:                                                                         */
        !            93:                int                             encrypt         /* 0 ==> decrypt; else encrypt*/
        !            94: 
        !            95: 
        !            96:        If encrypt is non-zero, the routine cipher-block-chain encrypts
        !            97:        the INPUT (cleartext) into the OUTPUT (ciphertext) using the provided
        !            98:        key schedule and initialization vector.  If the length is not an integral
        !            99:        multiple of eight bytes, the last block is copied to a temp and zero 
        !           100:        filled (highest addresses).  The output is ALWAYS an integral multiple
        !           101:        of eight bytes.
        !           102: 
        !           103:        If encrypt is zero, the routine cipher-block chain decrypts the INPUT
        !           104:        (ciphertext) into the OUTPUT (cleartext) using the provided key schedule
        !           105:        and     initialization vector.  Decryption ALWAYS operates on integral
        !           106:        multiples of 8 bytes, so will round the length provided up to the
        !           107:        appropriate     multiple. Consequently, it will always produce the rounded-up
        !           108:        number of bytes of output cleartext. The application must determine if
        !           109:        the output cleartext was zero-padded due to cleartext lengths not integral
        !           110:        multiples of 8.
        !           111: 
        !           112:        No errors or meaningful value are returned.  Void is not used for
        !           113:        compatibility with other compilers.
        !           114: 
        !           115: 
        !           116: /* cbc checksum (MAC) only routine  ---------------------------------------- */
        !           117: int    
        !           118:        cbc_cksum(input,output,length,schedule,ivec)
        !           119: 
        !           120:        C_Block                 *input;         /* >= length bytes of inputtext  */
        !           121:        C_Block                 *output;        /* >= length bytes of outputtext */
        !           122:        int                             length;         /* in bytes                                             */
        !           123:        Key_schedule    schedule;       /* precomputed key schedule        */
        !           124:        C_Block                 *ivec;          /* 8 bytes of ivec                         */
        !           125: 
        !           126: 
        !           127:        Produces a cryptographic checksum, 8 bytes, by cipher-block-chain
        !           128:        encrypting the input, discarding the ciphertext output, and only retaining
        !           129:        the last ciphertext 8-byte block.  Uses the provided key schedule and ivec.
        !           130:        The input is effectively zero-padded to an integral multiple of
        !           131:        eight bytes, though the original input is not modified.
        !           132: 
        !           133:        No meaningful value is returned.  Void is not used for compatibility
        !           134:        with other compilers.
        !           135: 
        !           136: 
        !           137: /*     random_key ----------------------------------------*/
        !           138: int
        !           139:        random_key(key)
        !           140: 
        !           141:        C_Block *key;
        !           142: 
        !           143:        The start for the random number generated is set from the current time
        !           144:        in microseconds, then the random number generator is invoked
        !           145:        to create an eight byte output key (not a schedule).  The key
        !           146:        generated is set to odd parity per FIPS spec.
        !           147: 
        !           148:        The caller must supply space for the output key, pointed to 
        !           149:        by "*key", then after getting a new key, call the des_set_key() 
        !           150:        routine when needed.
        !           151: 
        !           152:        No meaningfull value is returned.  Void is not used for compatibility
        !           153:        with other compilers.
        !           154: 
        !           155: 
        !           156: /* string_to_key --------------------------------------------*/
        !           157: 
        !           158: int
        !           159:        string_to_key(str,key)
        !           160:        register char           *str;
        !           161:        register C_Block        *key;
        !           162: 
        !           163:        This routines converts an arbitrary length, null terminated string
        !           164:        to an 8 byte DES key, with each byte parity set to odd, per FIPS spec.
        !           165: 
        !           166:        The algorithm is as follows:
        !           167: 
        !           168: |      Take the first 8 bytes and remove the parity (leaving 56 bits).
        !           169: |      Do the same for the second 8 bytes, and the third, etc.  Do this for
        !           170: |      as many sets of 8 bytes as necessary, filling in the remainder of the
        !           171: |      last set with nulls.  Fold the second set back on the first (i.e. bit
        !           172: |      0 over bit 55, and bit 55 over bit 0).  Fold the third over the second
        !           173: |      (bit 0 of the third set is now over bit 0 of the first set).  Repeat
        !           174: |      until you have done this to all sets.  Xor the folded sets.  Break the
        !           175: |      result into 8 7 bit bytes, and generate odd parity for each byte.  You
        !           176: |      now have 64 bits.  Note that DES takes a 64 bit key, and uses only the
        !           177: |      non parity bits.
        !           178: 
        !           179: 
        !           180: /* read_password -------------------------------------------*/
        !           181: 
        !           182: read_password(k,prompt,verify)
        !           183:        C_Block *k;
        !           184:        char *prompt;
        !           185:        int     verify;
        !           186: 
        !           187: This routine issues the supplied prompt, turns off echo, if possible, and
        !           188: reads an input string.  If verify is non-zero, it does it again, for use
        !           189: in applications such as changing a password. If verify is non-zero, both
        !           190: versions are compared, and the input is requested repeatedly until they
        !           191: match.  Then, the input string is mapped into a valid DES key, internally
        !           192: using the string_to_key routine.  The newly created key is copied to the
        !           193: area pointed to by parameter "k".  
        !           194: 
        !           195: No meaningful value is returned.  If an error occurs trying to manipulate
        !           196: the terminal echo, the routine forces the process to exit.
        !           197: 
        !           198: /* get_line ------------------------*/
        !           199: long get_line(p,max)
        !           200:        char    *p;
        !           201:        long    max;
        !           202: 
        !           203: Reads input characters from standard input until either a newline appears or
        !           204: else the max length is reached.  The characters read are stuffed into
        !           205: the string pointed to, which will always be null terminated.  The newline
        !           206: is not inserted in the string.  The max parameter includes the byte needed
        !           207: for the null terminator, so allocate and pass one more than the maximum
        !           208: string length desired.

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