openssl/doc/digest.doc

The Message Digest subroutines.

These routines require "evp.h" to be included.

These functions are a higher level interface to the various message digest
routines found in this library.  As such, they allow the same code to be
used to digest via different algorithms with only a change in an initial
parameter.  They are basically just a front-end to the MD2, MD5, SHA
and SHA1
routines.

These routines all take a pointer to the following structure to specify
which message digest algorithm to use.
typedef struct evp_md_st
	{
	int type;
	int pkey_type;
	int md_size;
	void (*init)();
	void (*update)();
	void (*final)();

	int required_pkey_type; /*EVP_PKEY_xxx */
	int (*sign)();
	int (*verify)();
	} EVP_MD;

If additional message digest algorithms are to be supported, a structure of
this type needs to be declared and populated and then the Digest routines
can be used with that algorithm.  The type field is the object NID of the
digest type (read the section on Objects for an explanation).  The pkey_type
is the Object type to use when the a message digest is generated by there
routines and then is to be signed with the pkey algorithm.  Md_size is
the size of the message digest returned.  Init, update
and final are the relevant functions to perform the message digest function
by parts.  One reason for specifying the message digest to use via this
mechanism is that if you only use md5, only the md5 routines will
be included in you linked program.  If you passed an integer
that specified which message digest to use, the routine that mapped that
integer to a set of message digest functions would cause all the message
digests functions to be link into the code.  This setup also allows new
message digest functions to be added by the application.

The six message digests defined in this library are

EVP_MD *EVP_md2(void);	/* RSA sign/verify */
EVP_MD *EVP_md5(void);	/* RSA sign/verify */
EVP_MD *EVP_sha(void);	/* RSA sign/verify */
EVP_MD *EVP_sha1(void);	/* RSA sign/verify */
EVP_MD *EVP_dss(void);	/* DSA sign/verify */
EVP_MD *EVP_dss1(void);	/* DSA sign/verify */

All the message digest routines take a EVP_MD_CTX pointer as an argument.
The state of the message digest is kept in this structure.

typedef struct pem_md_ctx_st
	{
	EVP_MD *digest;
	union	{
		unsigned char base[4]; /* this is used in my library as a
					* 'pointer' to all union elements
					* structures. */
		MD2_CTX md2;
		MD5_CTX md5;
		SHA_CTX sha;
		} md;
	} EVP_MD_CTX;

The Digest functions are as follows.

void EVP_DigestInit(
EVP_MD_CTX *ctx,
EVP_MD *type);
	This function is used to initialise the EVP_MD_CTX.  The message
	digest that will associated with 'ctx' is specified by 'type'.

void EVP_DigestUpdate(
EVP_MD_CTX *ctx,
unsigned char *data,
unsigned int cnt);
	This function is used to pass more data to the message digest
	function.  'cnt' bytes are digested from 'data'.

void EVP_DigestFinal(
EVP_MD_CTX *ctx,
unsigned char *md,
unsigned int *len);
	This function finishes the digestion and puts the message digest
	into 'md'.  The length of the message digest is put into len;
	EVP_MAX_MD_SIZE is the size of the largest message digest that
	can be returned from this function.  Len can be NULL if the
	size of the digest is not required.