diff options
Diffstat (limited to 'doc/digest.doc')
| -rw-r--r-- | doc/digest.doc | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/doc/digest.doc b/doc/digest.doc new file mode 100644 index 0000000000..d2fb987591 --- /dev/null +++ b/doc/digest.doc @@ -0,0 +1,94 @@ + +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. + |