doc/digest.doc

   1
   2 The Message Digest subroutines.
   3
   4 These routines require "evp.h" to be included.
   5
   6 These functions are a higher level interface to the various message digest
   7 routines found in this library.  As such, they allow the same code to be
   8 used to digest via different algorithms with only a change in an initial
   9 parameter.  They are basically just a front-end to the MD2, MD5, SHA
  10 and SHA1
  11 routines.
  12
  13 These routines all take a pointer to the following structure to specify
  14 which message digest algorithm to use.
  15 typedef struct evp_md_st
  16         {
  17         int type;
  18         int pkey_type;
  19         int md_size;
  20         void (*init)();
  21         void (*update)();
  22         void (*final)();
  23
  24         int required_pkey_type; /*EVP_PKEY_xxx */
  25         int (*sign)();
  26         int (*verify)();
  27         } EVP_MD;
  28
  29 If additional message digest algorithms are to be supported, a structure of
  30 this type needs to be declared and populated and then the Digest routines
  31 can be used with that algorithm.  The type field is the object NID of the
  32 digest type (read the section on Objects for an explanation).  The pkey_type
  33 is the Object type to use when the a message digest is generated by there
  34 routines and then is to be signed with the pkey algorithm.  Md_size is
  35 the size of the message digest returned.  Init, update
  36 and final are the relevant functions to perform the message digest function
  37 by parts.  One reason for specifying the message digest to use via this
  38 mechanism is that if you only use md5, only the md5 routines will
  39 be included in you linked program.  If you passed an integer
  40 that specified which message digest to use, the routine that mapped that
  41 integer to a set of message digest functions would cause all the message
  42 digests functions to be link into the code.  This setup also allows new
  43 message digest functions to be added by the application.
  44
  45 The six message digests defined in this library are
  46
  47 EVP_MD *EVP_md2(void);  /* RSA sign/verify */
  48 EVP_MD *EVP_md5(void);  /* RSA sign/verify */
  49 EVP_MD *EVP_sha(void);  /* RSA sign/verify */
  50 EVP_MD *EVP_sha1(void); /* RSA sign/verify */
  51 EVP_MD *EVP_dss(void);  /* DSA sign/verify */
  52 EVP_MD *EVP_dss1(void); /* DSA sign/verify */
  53
  54 All the message digest routines take a EVP_MD_CTX pointer as an argument.
  55 The state of the message digest is kept in this structure.
  56
  57 typedef struct pem_md_ctx_st
  58         {
  59         EVP_MD *digest;
  60         union   {
  61                 unsigned char base[4]; /* this is used in my library as a
  62                                         * 'pointer' to all union elements
  63                                         * structures. */
  64                 MD2_CTX md2;
  65                 MD5_CTX md5;
  66                 SHA_CTX sha;
  67                 } md;
  68         } EVP_MD_CTX;
  69
  70 The Digest functions are as follows.
  71
  72 void EVP_DigestInit(
  73 EVP_MD_CTX *ctx,
  74 EVP_MD *type);
  75         This function is used to initialise the EVP_MD_CTX.  The message
  76         digest that will associated with 'ctx' is specified by 'type'.
  77
  78 void EVP_DigestUpdate(
  79 EVP_MD_CTX *ctx,
  80 unsigned char *data,
  81 unsigned int cnt);
  82         This function is used to pass more data to the message digest
  83         function.  'cnt' bytes are digested from 'data'.
  84
  85 void EVP_DigestFinal(
  86 EVP_MD_CTX *ctx,
  87 unsigned char *md,
  88 unsigned int *len);
  89         This function finishes the digestion and puts the message digest
  90         into 'md'.  The length of the message digest is put into len;
  91         EVP_MAX_MD_SIZE is the size of the largest message digest that
  92         can be returned from this function.  Len can be NULL if the
  93         size of the digest is not required.
  94