fix pk7_doit.c for new i2d_ASN1_SET argument
[openssl.git] / 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