BIOfmd(3) OpenSSL BIOfmd(3)

NAME
       BIOfmd, BIOsetmd, BIOgetmd, BIOgetmdctx - message digest BIO
       filter

SYNOPSIS
        #include 
        #include 

        BIOMETHOD *   BIOfmd(void);
        int BIOsetmd(BIO *b,EVPMD *md);
        int BIOgetmd(BIO *b,EVPMD **mdp);
        int BIOgetmdctx(BIO *b,EVPMDCTX **mdcp);

DESCRIPTION
       BIOfmd() returns the message digest BIO method. This is a filter BIO
       that digests any data passed through it, it is a BIO wrapper for the
       digest routines EVPDigestInit(), EVPDigestUpdate() and
       EVPDigestFinal().

       Any data written or read through a digest BIO using BIOread() and
       BIOwrite() is digested.

       BIOgets(), if its ssiizzee parameter is large enough finishes the digest
       calculation and returns the digest value. BIOputs() is not supported.

       BIOreset() reinitialises a digest BIO.

       BIOsetmd() sets the message digest of BIO bb to mmdd: this must be
       called to initialize a digest BIO before any data is passed through it.
       It is a BIOctrl() macro.

       BIOgetmd() places the a pointer to the digest BIOs digest method in
       mmddpp, it is a BIOctrl() macro.

       BIOgetmdctx() returns the digest BIOs context into mmddccpp.

NNOOTTEESS
       The context returned by BIOgetmdctx() can be used in calls to
       EVPDigestFinal() and also the signature routines EVPSignFinal() and
       EVPVerifyFinal().

       The context returned by BIOgetmdctx() is an internal context
       structure. Changes made to this context will affect the digest BIO
       itself and the context pointer will become invalid when the digest BIO
       is freed.

       After the digest has been retrieved from a digest BIO it must be
       reinitialized by calling BIOreset(), or BIOsetmd() before any more
       data is passed through it.

       If an application needs to call BIOgets() or BIOputs() through a
       chain containing digest BIOs then this can be done by prepending a
       buffering BIO.

RETURN VALUES
       BIOfmd() returns the digest BIO method.

       BIOsetmd(), BIOgetmd() and BIOmdctx() return 1 for success and 0
       for failure.

EEXXAAMMPPLLEESS
       The following example creates a BIO chain containing an SHA1 and MD5
       digest BIO and passes the string "Hello World" through it. Error
       checking has been omitted for clarity.

        BIO *bio, *mdtmp;
        char message[] = "Hello World";
        bio = BIOnew(BIOsnull());
        mdtmp = BIOnew(BIOfmd());
        BIOsetmd(mdtmp, EVPsha1());
        /* For BIOpush() we want to append the sink BIO and keep a note of
         * the start of the chain.
         */
        bio = BIOpush(mdtmp, bio);
        mdtmp = BIOnew(BIOfmd());
        BIOsetmd(mdtmp, EVPmd5());
        bio = BIOpush(mdtmp, bio);
        /* Note: mdtmp can now be discarded */
        BIOwrite(bio, message, strlen(message));

       The next example digests data by reading through a chain instead:

        BIO *bio, *mdtmp;
        char buf[1024];
        int rdlen;
        bio = BIOnewfile(file, "rb");
        mdtmp = BIOnew(BIOfmd());
        BIOsetmd(mdtmp, EVPsha1());
        bio = BIOpush(mdtmp, bio);
        mdtmp = BIOnew(BIOfmd());
        BIOsetmd(mdtmp, EVPmd5());
        bio = BIOpush(mdtmp, bio);
        do {
               rdlen = BIOread(bio, buf, sizeof(buf));
               /* Might want to do something with the data here */
        } while(rdlen > 0);

       This next example retrieves the message digests from a BIO chain and
       outputs them. This could be used with the examples above.

        BIO *mdtmp;
        unsigned char mdbuf[EVPMAXMDSIZE];
        int mdlen;
        int i;
        mdtmp = bio;   /* Assume bio has previously been set up */
        do {
               EVPMD *md;
               mdtmp = BIOfindtype(mdtmp, BIOTYPEMD);
               if(!mdtmp) break;
               BIOgetmd(mdtmp, &md);
               printf("%s digest", OBJnid2sn(EVPMDtype(md)));
               mdlen = BIOgets(mdtmp, mdbuf, EVPMAXMDSIZE);
               for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
               printf("\n");
               mdtmp = BIOnext(mdtmp);
        } while(mdtmp);

        BIOfreeall(bio);

BUGS
       The lack of support for BIOputs() and the non standard behaviour of
       BIOgets() could be regarded as anomalous. It could be argued that
       BIOgets() and BIOputs() should be passed to the next BIO in the chain
       and digest the data passed through and that digests should be retrieved
       using a separate BIOctrl() call.

SEE ALSO
       TBA



0.9.7l                            2001-09-06                       BIOfmd(3)