manpage.txt

密码包

       These are some extra functions  that  operate  on  modules
       that  have  been  opened:  These functions have the prefix
       mcrypt_enc_*.

       int  mcrypt_enc_set_state(MCRYPT  td,  void  *state,   int
       size);  This function sets the state of the algorithm. Can
       be used only with block algorithms and certain modes  like
       CBC,  CFB  etc.   It is usefully if you want to restart or
       start a different encryption  quickly.   Returns  zero  on
       success.     The     state     is     the     output    of
       mcrypt_enc_get_state().

       int  mcrypt_enc_get_state(MCRYPT  td,  void  *state,   int
       *size);  This function returns the state of the algorithm.
       Can be used only certain modes and  algorithms.  The  size
       will  hold  the  size of the state and the state must have
       enough bytes to hold it.  Returns zero on success.

       int mcrypt_enc_self_test( MCRYPT td);

       This function runs the self test on the  algorithm  speci-
       fied  by  the  descriptor td. If the self test succeeds it
       returns zero.

       int mcrypt_enc_is_block_algorithm_mode( MCRYPT td);

       Returns 1 if the mode is for use  with  block  algorithms,
       otherwise  it returns 0. (eg. 0 for stream, and 1 for cbc,
       cfb, ofb)

       int mcrypt_enc_is_block_algorithm( MCRYPT td);

       Returns 1 if the algorithm is a block algorithm or 0 if it
       is a stream algorithm.

       int mcrypt_enc_is_block_mode( MCRYPT td);

       Returns  1  if the mode outputs blocks of bytes or 0 if it
       outputs bytes.  (eg. 1 for cbc and ecb, and 0 for cfb  and
       stream)

       int mcrypt_enc_get_block_size( MCRYPT td);

       Returns  the  block size of the algorithm specified by the
       encryption descriptor in  bytes.  The  algorithm  MUST  be
       opened using mcrypt_module_open().

       int mcrypt_enc_get_key_size( MCRYPT td);

       Returns  the  maximum  supported key size of the algorithm
       specified by the encryption descriptor in bytes. The algo-
       rithm MUST be opened using mcrypt_module_open().

       int*  mcrypt_enc_get_supported_key_sizes(  MCRYPT td, int*
       sizes)

       Returns the key sizes supported by the algorithm specified
       by  the  encryption  descriptor.   If  sizes  is  zero and
       returns  NULL  then  all   key   sizes   between   1   and
       mcrypt_get_key_size()  are  supported by the algorithm. If
       it is 1 then only the mcrypt_get_key_size() size  is  sup-
       ported  and sizes[0] is equal to it. If it is greater than
       1 then that number specifies the  number  of  elements  in
       sizes which are the key sizes that the algorithm supports.
       The retured value is allocated with malloc, so you  should
       not forget to free it.

       int mcrypt_enc_get_iv_size( MCRYPT td);

       Returns  size  of the IV of the algorithm specified by the
       encryption descriptor in  bytes.  The  algorithm  MUST  be
       opened  using mcrypt_module_open().  If it is '0' then the
       IV is ignored in that algorithm. IV is used in  CBC,  CFB,
       OFB modes, and in some algorithms in STREAM mode.

       int mcrypt_enc_mode_has_iv( MCRYPT td);

       Returns  1  if  the  mode  needs  an IV, 0 otherwise. Some
       'stream' algorithms may need an IV even if the mode itself
       does not need an IV.

       char* mcrypt_enc_get_algorithms_name( MCRYPT td);

       Returns a character array containing the name of the algo-
       rithm.  The retured value is allocated with malloc, so you
       should not forget to free it.

       char* mcrypt_enc_get_modes_name( MCRYPT td);

       Returns a character array containing the name of the mode.
       The retured value is allocated with malloc, so you  should
       not forget to free it.


       These  are  some  extra functions that operate on modules:
       These functions have the prefix mcrypt_module_*.

       int mcrypt_module_self_test (char* algorithm, char* direc-
       tory);

       This  function  runs  the self test on the specified algo-
       rithm. If the self test succeeds it returns zero.

       int  mcrypt_module_is_block_algorithm_mode(  char*   algo-
       rithm, char* directory);

       Returns  1  if  the mode is for use with block algorithms,
       otherwise it returns 0. (eg. 0 for stream, and 1 for  cbc,
       cfb, ofb)

       int  mcrypt_module_is_block_algorithm(  char*  mode, char*
       directory);

       Returns 1 if the algorithm is a block algorithm or 0 if it
       is a stream algorithm.

       int  mcrypt_module_is_block_mode( char* mode, char* direc-
       tory);

       Returns 1 if the mode outputs blocks of bytes or 0  if  it
       outputs  bytes.  (eg. 1 for cbc and ecb, and 0 for cfb and
       stream)

       int  mcrypt_module_get_algo_block_size(  char*  algorithm,
       char* directory);

       Returns the block size of the algorithm.

       int   mcrypt_module_get_algo_key_size(   char*  algorithm,
       char* directory);

       Returns the maximum supported key size of the algorithm.

       int*   mcrypt_module_get_algo_supported_key_sizes(   char*
       algorithm, char* directory, int* sizes);

       Returns the key sizes supported by the algorithm. If sizes
       is zero and returns NULL then all key sizes between 1  and
       mcrypt_get_key_size()  are  supported by the algorithm. If
       it is 1 then only the mcrypt_get_key_size() size  is  sup-
       ported  and sizes[0] is equal to it. If it is greater than
       1 then that number specifies the  number  of  elements  in
       sizes which are the key sizes that the algorithm supports.
       This    function    differs     to     mcrypt_enc_get_sup-
       ported_key_sizes(), because the return value here is allo-
       cated (not static), thus it should be freed.



       char** mcrypt_list_algorithms ( char* libdir, int* size);

       Returns a pointer to a character array cointaining all the
       mcrypt algorithms located in the libdir, or if it is NULL,
       in the default directory. The size is the  number  of  the
       character arrays.  The arrays are allocated internally and
       should be freed by using mcrypt_free_p().

       char** mcrypt_list_modes ( char* libdir, int *size);

       Returns a pointer to a character array cointaining all the
       mcrypt  modes  located in the libdir, or if it is NULL, in
       the default directory. The size is the number of the char-
       acter  arrays.   The  arrays  should  be  freed  by  using
       mcrypt_free_p().

       void mcrypt_free_p (char **p, int size);

       Frees the pointer to array returned by previous functions.

       void mcrypt_free (void *ptr);

       Frees the memory used by the pointer.

       void mcrypt_perror(int err);

       This  function  prints a human readable description of the
       error 'err' in the stderr.  The  err  should  be  a  value
       returned by mcrypt_generic_init().

       const char* mcrypt_strerror(int err);

       This  function returns a human readable description of the
       error 'err'.  The  err  should  be  a  value  returned  by
       mcrypt_generic_init().

       int  mcrypt_mutex_register  (  void  (*mutex_lock)(void) ,
       void (*mutex_unlock)(void) );

       This function is only used in  multithreaded  application.
       This  is  actually  used internally in libltdl. Except for
       the dynamic module loading libmcrypt is thread safe.


       Some example programs follow here. Compile as  "cc  prog.c
       -lmcrypt  -lltdl",  or "cc prog.c -lmcrypt -ldl" depending
       on your installation.  Libltdl is used for opening dynamic
       libraries (modules).

       /* First example: Encrypts stdin to stdout using TWOFISH with 128 bit key and CFB */

       #include <mcrypt.h>
       #include <stdio.h>
       #include <stdlib.h>
       /* #include <mhash.h> */

       main() {

         MCRYPT td;
         int i;
         char *key;
         char password[20];
         char block_buffer;
         char *IV;
         int keysize=16; /* 128 bits */

         key=calloc(1, keysize);
         strcpy(password, "A_large_key");

       /* Generate the key using the password */
       /*  mhash_keygen( KEYGEN_MCRYPT, MHASH_MD5, key, keysize, NULL, 0, password, strlen(password));
        */
         memmove( key, password, strlen(password));

         td = mcrypt_module_open("twofish", NULL, "cfb", NULL);
         if (td==MCRYPT_FAILED) {
            return 1;
         }
         IV = malloc(mcrypt_enc_get_iv_size(td));

       /* Put random data in IV. Note these are not real random data,
        * consider using /dev/random or /dev/urandom.
        */

         /*  srand(time(0)); */
         for (i=0; i< mcrypt_enc_get_iv_size( td); i++) {
           IV[i]=rand();
         }

         i=mcrypt_generic_init( td, key, keysize, IV);
         if (i<0) {
            mcrypt_perror(i);
            return 1;
         }

         /* Encryption in CFB is performed in bytes */
         while ( fread (&block_buffer, 1, 1, stdin) == 1 ) {
             mcrypt_generic (td, &block_buffer, 1);

       /* Comment above and uncomment this to decrypt */
       /*    mdecrypt_generic (td, &block_buffer, 1);  */

             fwrite ( &block_buffer, 1, 1, stdout);
         }

       /* Deinit the encryption thread, and unload the module */
         mcrypt_generic_end(td);

         return 0;

       }


       /* Second Example: encrypts using CBC and SAFER+ with 192 bits key */

       #include <mcrypt.h>
       #include <stdio.h>
       #include <stdlib.h>

       main() {

         MCRYPT td;
         int i;
         char *key; /* created using mcrypt_gen_key */
         char *block_buffer;
         char *IV;
         int blocksize;
         int keysize = 24; /* 192 bits == 24 bytes */


         key = calloc(1, keysize);
         strcpy(key, "A_large_and_random_key");

         td = mcrypt_module_open("saferplus", NULL, "cbc", NULL);

         blocksize = mcrypt_get_block_size(td);
         block_buffer = malloc(blocksize);
       /* but unfortunately this does not fill all the key so the rest bytes are
        * padded with zeros. Try to use large keys or convert them with mcrypt_gen_key().
        */

         IV=malloc(mcrypt_enc_get_iv_size(td));

       /* Put random data in IV. Note these are not real random data,
        * consider using /dev/random or /dev/urandom.
        */

       /* srand(time(0)); */
         for (i=0; i < mcrypt_enc_get_iv_size(td); i++) {
           IV[i]=rand();
         }

         mcrypt_generic_init ( td key, keysize, IV);

         /* Encryption in CBC is performed in blocks */
         while ( fread (block_buffer, 1, blocksize, stdin) == blocksize ) {
             mcrypt_generic (td, block_buffer, blocksize);
       /*      mdecrypt_generic (td, block_buffer, blocksize); */
             fwrite ( block_buffer, 1, blocksize, stdout);
         }

       /* deinitialize the encryption thread */
         mcrypt_generic_deinit (td);

       /* Unload the loaded module */
         mcrypt_module_close(td);
         return 0;

       }


       The library does not install any signal handler.

       Questions about libmcrypt should be sent to:

              [e-mail]  or,  if  this fails, to
              the author addresses given below.  The mcrypt  home
              page is:

              http://mcrypt.hellug.gr


AUTHORS
       Version  2.4 Copyright (C) 1998-1999 Nikos Mavroyanopoulos
       ([e-mail]).

       Thanks to all the people who reported  problems  and  sug-
       gested various improvements for mcrypt; who are too numer-
       ous to cite here.




                          10 March 2002                 MCRYPT(3)