des.pod

开源的ssl算法openssl,版本0.9.8H

=pod

=head1 NAME

DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked,
DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key,
DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt,
DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt,
DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt,
DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt,
DES_ede3_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys,
DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption

=head1 SYNOPSIS

 #include <openssl/des.h>

 void DES_random_key(DES_cblock *ret);

 int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);
 int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);
 int DES_set_key_checked(const_DES_cblock *key,
        DES_key_schedule *schedule);
 void DES_set_key_unchecked(const_DES_cblock *key,
        DES_key_schedule *schedule);

 void DES_set_odd_parity(DES_cblock *key);
 int DES_is_weak_key(const_DES_cblock *key);

 void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, 
        DES_key_schedule *ks, int enc);
 void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, 
        DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);
 void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, 
        DES_key_schedule *ks1, DES_key_schedule *ks2, 
        DES_key_schedule *ks3, int enc);

 void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, 
        long length, DES_key_schedule *schedule, DES_cblock *ivec, 
        int enc);
 void DES_cfb_encrypt(const unsigned char *in, unsigned char *out,
        int numbits, long length, DES_key_schedule *schedule,
        DES_cblock *ivec, int enc);
 void DES_ofb_encrypt(const unsigned char *in, unsigned char *out,
        int numbits, long length, DES_key_schedule *schedule,
        DES_cblock *ivec);
 void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, 
        long length, DES_key_schedule *schedule, DES_cblock *ivec, 
        int enc);
 void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,
        long length, DES_key_schedule *schedule, DES_cblock *ivec,
        int *num, int enc);
 void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,
        long length, DES_key_schedule *schedule, DES_cblock *ivec,
        int *num);

 void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, 
        long length, DES_key_schedule *schedule, DES_cblock *ivec, 
        const_DES_cblock *inw, const_DES_cblock *outw, int enc);

 void DES_ede2_cbc_encrypt(const unsigned char *input,
        unsigned char *output, long length, DES_key_schedule *ks1,
        DES_key_schedule *ks2, DES_cblock *ivec, int enc);
 void DES_ede2_cfb64_encrypt(const unsigned char *in,
        unsigned char *out, long length, DES_key_schedule *ks1,
        DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc);
 void DES_ede2_ofb64_encrypt(const unsigned char *in,
        unsigned char *out, long length, DES_key_schedule *ks1,
        DES_key_schedule *ks2, DES_cblock *ivec, int *num);

 void DES_ede3_cbc_encrypt(const unsigned char *input,
        unsigned char *output, long length, DES_key_schedule *ks1,
        DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec,
        int enc);
 void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out, 
        long length, DES_key_schedule *ks1, DES_key_schedule *ks2, 
        DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2, 
        int enc);
 void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, 
        long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
        DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc);
 void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, 
        long length, DES_key_schedule *ks1, 
        DES_key_schedule *ks2, DES_key_schedule *ks3, 
        DES_cblock *ivec, int *num);

 DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, 
        long length, DES_key_schedule *schedule, 
        const_DES_cblock *ivec);
 DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], 
        long length, int out_count, DES_cblock *seed);
 void DES_string_to_key(const char *str, DES_cblock *key);
 void DES_string_to_2keys(const char *str, DES_cblock *key1,
        DES_cblock *key2);

 char *DES_fcrypt(const char *buf, const char *salt, char *ret);
 char *DES_crypt(const char *buf, const char *salt);

 int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched,
        DES_cblock *iv);
 int DES_enc_write(int fd, const void *buf, int len,
        DES_key_schedule *sched, DES_cblock *iv);

=head1 DESCRIPTION

This library contains a fast implementation of the DES encryption
algorithm.

There are two phases to the use of DES encryption.  The first is the
generation of a I<DES_key_schedule> from a key, the second is the
actual encryption.  A DES key is of type I<DES_cblock>. This type is
consists of 8 bytes with odd parity.  The least significant bit in
each byte is the parity bit.  The key schedule is an expanded form of
the key; it is used to speed the encryption process.

DES_random_key() generates a random key.  The PRNG must be seeded
prior to using this function (see L<rand(3)|rand(3)>).  If the PRNG
could not generate a secure key, 0 is returned.

Before a DES key can be used, it must be converted into the
architecture dependent I<DES_key_schedule> via the
DES_set_key_checked() or DES_set_key_unchecked() function.

DES_set_key_checked() will check that the key passed is of odd parity
and is not a week or semi-weak key.  If the parity is wrong, then -1
is returned.  If the key is a weak key, then -2 is returned.  If an
error is returned, the key schedule is not generated.

DES_set_key() works like
DES_set_key_checked() if the I<DES_check_key> flag is non-zero,
otherwise like DES_set_key_unchecked().  These functions are available
for compatibility; it is recommended to use a function that does not
depend on a global variable.

DES_set_odd_parity() sets the parity of the passed I<key> to odd.

DES_is_weak_key() returns 1 is the passed key is a weak key, 0 if it
is ok.  The probability that a randomly generated key is weak is
1/2^52, so it is not really worth checking for them.

The following routines mostly operate on an input and output stream of
I<DES_cblock>s.

DES_ecb_encrypt() is the basic DES encryption routine that encrypts or
decrypts a single 8-byte I<DES_cblock> in I<electronic code book>
(ECB) mode.  It always transforms the input data, pointed to by
I<input>, into the output data, pointed to by the I<output> argument.
If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input>
(cleartext) is encrypted in to the I<output> (ciphertext) using the
key_schedule specified by the I<schedule> argument, previously set via
I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now
ciphertext) is decrypted into the I<output> (now cleartext).  Input
and output may overlap.  DES_ecb_encrypt() does not return a value.

DES_ecb3_encrypt() encrypts/decrypts the I<input> block by using
three-key Triple-DES encryption in ECB mode.  This involves encrypting
the input with I<ks1>, decrypting with the key schedule I<ks2>, and
then encrypting with I<ks3>.  This routine greatly reduces the chances
of brute force breaking of DES and has the advantage of if I<ks1>,
I<ks2> and I<ks3> are the same, it is equivalent to just encryption
using ECB mode and I<ks1> as the key.

The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES
encryption by using I<ks1> for the final encryption.

DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining>
(CBC) mode of DES.  If the I<encrypt> argument is non-zero, the
routine cipher-block-chain encrypts the cleartext data pointed to by
the I<input> argument into the ciphertext pointed to by the I<output>
argument, using the key schedule provided by the I<schedule> argument,
and initialization vector provided by the I<ivec> argument.  If the
I<length> argument is not an integral multiple of eight bytes, the
last block is copied to a temporary area and zero filled.  The output
is always an integral multiple of eight bytes.

DES_xcbc_encrypt() is RSA's DESX mode of DES.  It uses I<inw> and
I<outw> to 'whiten' the encryption.  I<inw> and I<outw> are secret
(unlike the iv) and are as such, part of the key.  So the key is sort
of 24 bytes.  This is much better than CBC DES.