(Answer) (Category) Crypto++ Faq-O-Matic :
How do I use the Filter class?
Moderator: weidai (inherited from parent)
I'll try to explain the filter/pipeline design in Crypto++.

The (abstract) base class is BufferedTransformation, with main member functions:

    virtual void Put(const byte *inString, unsigned int length) =0;
    virtual unsigned int Get(byte *outString, unsigned int getMax) =0;

The idea is that you put some bytes into a BufferedTransformation object, it does some transformation on them and buffers them, and then you get them back later (possibly with the length changed). One example of a BufferedTransformation is the MessageQueue, which just stores whatever you put in and then gives them back to you when you ask.

The Filter abstract class derives from BufferedTransformation. A Filter is a BufferedTransformation on which you can attach another BufferedTransformation object. Instead of buffering up the transformed bytes, it would Put() them into the attached object. When you call Get() on a Filter, it calls Get() on the attached object and returns what the attached object returns without change. By default the object attached is a MessageQueue, but you can specify another filter or link a series of filters into a pipeline.

Other abstract classes derived from BufferedTransformation include Source, which adds the Pump() member function (it pumps a specified number of bytes from its resevoir into the attached object) and Sink, which always returns 0 on Get().
2002-Oct-12 4:27pm alister, weidai

There are two ways to use filters. The first is defining your own Source and Sink classes (or use ones already in the library), and then link your Source and Sink objects with a series of filters. Examples:
2000-Aug-23 7:25am alister
void EncryptFile(const char *filein, const char *fileout, const char *passPhrase) { 
    FileSource f(filein, true, new DefaultEncryptor(passPhrase, 
        new FileSink(fileout)));
}

void GzipFile(const char *filein, const char *fileout) { 
    FileSource f(filein, true, new Gzip(new FileSink(fileout)));
}
2001-Jan-12 11:00pm alister, weidai
The "true" argument tells FileSource to immediately pump everything from filein to the attached BufferedTransformation.
2001-Jan-12 11:01pm alister, weidai
The second method is to link a series of filters into a pipeline, manually Put() some bytes into it and then Get() them back. For example:
2000-Aug-23 7:28am alister
// encode a string using passPhrase and encode it in hex 
// returns the ciphertext, which should be deleted by caller 
char *EncryptString(const char *instr, const char *passPhrase) { 
        unsigned int len=strlen(instr);
        char* outstr;
 
        DefaultEncryptor encryptor(passPhrase, new HexEncoder);
        encryptor.Put((byte *)instr, len);
        encryptor.MessageEnd();

        unsigned int outputLength = encryptor.MaxRetrieveable();
        outstr = new char[outputLength+1];
        encryptor.Get((byte *)outstr, outputLength);
        outstr[outputLength] = 0;
        return outstr;
}
2001-Jan-16 5:38pm alister, weidai
The filter/pipeline design has some more advanced features, such multiple channels (useful for secret sharing), but these basic features are all you need for most purposes.
2001-Jan-12 11:05pm weidai, alister
[Append to This Answer]
2002-Oct-12 4:27pm
Previous: (Answer) How much C++ experience do I need to use this library?
Next: (Answer) How do I use hex encoding and decoding?
This document is: http://www.cryptopp.com/cgi-bin/fom.cgi?file=29
[Search] [Appearance] [Show Expert Edit Commands]
This is a Faq-O-Matic 2.721.
This FAQ is administered by Wei Dai.