FBB::OSymCryptStream - std::ostream performing symmetric en/decryption

       Frank B. Brokken (f.b.brokken@rug.nl).

libbobcat-dev_6.07.01                               2005-2025                      FBB::OSymCryptStream(3bobcat)

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       Debian Bobcat project files:

       o      libbobcat6: debian package containing the shared library, changelog and copyright note;

       o      libbobcat-dev:  debian package containing the static library, headers, manual pages, and developer
              info;

       None Reported.

       o      OSymCryptStream<CryptType>(std::ostream&outStream,std::stringconst&cipherName,std::stringconst&key,std::stringconst&iv,size_tinBufSize=100):
              This constructor defines a std::streambuf encrypting or decrypting the characters it receives.

              - OSymCryptStream<FBB::ENCRYPT> objects perform encryption;
              OSymCryptStream<FBB::DECRYPT> objects perform decryption;

              - OSymCryptStream<CryptType> objects write the encrypted or decrypted characters to outStream;
              - The encryption method to use is specified by the cipherName parameter. E.g., "AES-256-GCM";
              - The symmetric key to use is specified by the key parameter;
              - The initialization vector is specified by the iv parameter;
              -  The  FBB::OSymCryptStreambuf internally used buffer will hold inBufSize characters. The default
              value is the smallest value that is used. When specifying a  smaller  bufSize  value  the  default
              value is used;

       o      OSymCryptStream<CryptType>(std::stringconst&outStreamName,std::stringconst&cipherName,std::stringconst&key,std::stringconst&iv,size_tinBufSize=100):
              Same constructor as the previous one, but this constructor’s first parameter specifies the name of
              the file to receive the encrypted or decrypted characters.

       If the construction fails an exception is thrown, mentioning the openssl function that failed to complete
       (see also errorMsg below).

       The move constructor is available, the copy constructor and assignment operators are not available,

       This is free software, distributed under the terms of the GNU General Public License (GPL).

FBB::OSymCryptStream  objects  can  be  used  to  encrypt  or  decrypt information,  that is available on
       separate std::istream streams.

       The class OSymCryptStream is a class  template,  using  a  FBB::CryptType  template  non-type  parameter.
       Objects  of the class FBB::OSymCryptStream<FBB::ENCRYPT> encrypt the information they receive, objects of
       the class FBB::OSymCryptStream<FBB::DECRYPT> decrypt the information they receive.

       All symmetric encryption methods defined by the OpenSSL library that can be selected by name may be  used
       to  en/decrypt  information.  To  select  a  particular  encryption method an identifier is passed to the
       constructor. E.g., "aes-256-gcm". For the currently supported cipher algorithms issue the command

           openssl list -cipher-algorithms

       OSymCryptStream objects  read  the  information  to  en/decrypt  from  an  external  source  (e.g.,  from
       std::istream  objects).   The  characters  that are encrypted or decrypted by OSymCryptStream objects are
       written to std::ostream objects which are at construction-time specified  as  ostream  references  or  by
       filename.

       #include <iostream>
       #include <fstream>
       #include <string>

       #include <bobcat/osymcryptstream>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
           if (argc == 1)
           {
               cout << "arg[1]: e - encrypt, d - decrypt,\n"
                       "arg[2]: file to process, arg[3]: processed file\n";
               return 0;
           }

           string key = "0123456789abcdef0123456789abcdef";
           cout << "encryption key ? ";
           cin >> key;
           while (key.size() < 32)
               key += key;
           string iv = " 0123456789ab" "456";

           char cipherName[] =
               "AES-256-GCM"
               //"AES-256-CBC"
           ;

           ifstream in{ argv[2] };
           ofstream out{ argv[3] };

           if (*argv[1] == ’e’)
           {
               OSymCryptStream<ENCRYPT> enc{ out, cipherName, key, iv, 100 };
                   // comment out the above statement and uncomment the next
                   // to use the constructor expecting a string as 1st arg:
       //      OSymCryptStream<ENCRYPT> enc{ argv[3], cipherName, key,
       //                                    iv, 100 };

               enc << in.rdbuf() << eoi;
               //in.seekg(0);              // when activated, this won’t
               //enc << in.rdbuf();        // be processed due to ’<< eoi’
           }
           else
           {
               OSymCryptStream<DECRYPT> decrypt{ out, cipherName, key,
                                                                  iv, 100 };
                   // comment out the above statement and uncomment the next
                   // to use the constructor expecting a string as 1st arg:
       //      OSymCryptStream<DECRYPT> decrypt{ argv[3], cipherName, key,
       //                                        iv, 100 };

               decrypt << in.rdbuf() << eoi;
           }
       }
       catch (exception const &exc)
       {
           cerr << exc.what() << ’\n’;
       }

bobcat/osymcryptstream - defines the class interface

       Since the class is publicly derived from std::ostream, all std::ostream members can be used.

FBB::OSymCryptStreambuf (private),
       std::istream

       o      std::ostream&FBB::eoi(std::ostream&out):
              By  inserting the eoi manipulator into an OSymCryptStream object insertion is considered complete.
              It completes the insertion of information into the std::ostream specified at construction time  as
              the  OSymCryptStream’s  first argument. That way, you don’t have to wait until the OSymCryptStream
              object’s destructor flushes that stream. In the following example using  the  eoi  manipulator  is
              illustrated in the (commented out lines near line 40):

                  //in.seekg(0);              // when activated, this won’t
                  //enc << in.rdbuf();        // be processed due to ’<< eoi’

              Activating those lines will not result in processing the in stream twice.

       o      staticstd::stringerrorMsg():
              If an openssl function fails an exception is thrown mentioning the name of the  failing  function.
              In  those cases the function errorMsg can be called returning a std::string containing the openssl
              error  code  (returned  by  ERR_get_error)   and   its   textual   representation   (returned   by
              ERR_error_string).  If the reported error code is zero, then in fact no error has occurred and the
              exception was spuriously reported;

       o      staticsize_tkeyLength(std::stringconst&cipherName):
              returns the minimum key length required for cipher cipherName;

       o      staticsize_tivLength(std::stingconst&cipherName):
              returns the minimum length of the initialization vector that is required for cipher cipherName.

       The latter two functions throw exceptions if cipherName does not contain the name of a  supported  cipher
       algorithm.

       FBB::OSymCryptStream - std::ostream performing symmetric en/decryption

FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are defined in the
       namespace FBB.

bobcat(7), isymcryptstream(3bobcat), isymcryptstreambuf(3bobcat), osymcryptstreambuf(3bobcat)

#include<bobcat/osymcryptstream>
       Linking option: -lbobcat-lcrypto