FBB::OSymCryptStreambuf(3bobcat)
Symmetric en- and decryption
(libbobcat-dev_6.06.02)
2005-2024
NAME
FBB::OSymCryptStreambuf - std::streambuf performing symmetric
                                     en/decryption
SYNOPSIS
    #include <bobcat/osymcryptstreambuf>
    Linking option: -lbobcat -lcrypto
DESCRIPTION
    FBB::OSymCryptStreambuf objects can be used as std::streambuf
objects of std::ostream objects, and encrypt or decrypt
information, that is made available via separate std::istream streams.
The class OSymCryptStreambuf is a class template, using a
FBB::CryptType template non-type parameter. Objects of the class
FBB::OSymCryptStreambuf<FBB::ENCRYPT> encrypt the information they receive,
objects of the class FBB::OSymCryptStreambuf<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 an overview of the currently supported cipher
algorithms issue the command
        
    openssl list -cipher-algorithms
        
OSymCryptStreambuf 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 OSymCryptStreambuf objects are written to
std::ostream objects which are at construction-time specified as
ostream references or by filename.
NAMESPACE
    FBB
    All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
    FBB::OSymCryptBase (public)
The class FBB::OSymCryptBase is an `internal use only' class, derived
from std::streambuf, and therefore OSymCryptStreambuf is a
std::streambuf class.
CONSTRUCTORS
    
    -  OSymCryptStreambuf<CryptType>(std::ostream &outStreambuf,
                    std::string const &cipherName,
                    std::string const &key,
                    std::string const &iv,
                    size_t inBufSize = 100):
 This constructor defines a std::streambuf encrypting or decrypting
        the characters it receives.
- OSymCryptStreambuf<FBB::ENCRYPT> objects perform encryption;
 OSymCryptStreambuf<FBB::DECRYPT> objects perform decryption;
 
- OSymCryptStreambuf<CryptType> objects write the encrypted or decrypted
        characters to outStreambuf;
 - 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::OSymCryptStreambufbuf 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;
 
 
 
-  OSymCryptStreambuf<CryptType>(std::string const &outStreambufName,
                    std::string const &cipherName,
                    std::string const &key,
                    std::string const &iv,
                    size_t inBufSize = 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,
INHERITED MEMBERS
Since the class is publicly derived from std::ostream, all
std::streambuf members can be used.
MEMBER FUNCTIONS
    
    -  static std::string errorMsg():
 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;
 
-  static size_t keyLength(std::string const &cipherName):
 returns the minimum key length required for cipher cipherName;
 
-  static size_t ivLength(std::sting const &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.
MANIPULATOR
    
    -  std::ostream &FBB::eoi(std::ostream &out):
 By inserting the eoi manipulator into an std::ostream object
        that uses a OSymCryptStreambuf streambuf insertion is considered
        complete. It completes the insertion of information into the
        std::ostream specified at construction time as the
        OSymCryptStreambuf's first argument. That way, you don't have to
        wait until the OSymCryptStreambuf object's destructor flushes that
        stream. The example provided at the osymcryptstream(3bobcat)
        man-page illustrates the use of the eoi manipulator.
EXAMPLE
    See the example in the osymcryptstream(3bobcat) man-page. Instead of
defining an OSymCryptStream an OSymCryptStreamBuf can be defined,
passing its address to a std::ostream which can then be used as the
OSymCryptStream used in the example.
FILES
    bobcat/osymcryptstreambuf - defines the class interface
SEE ALSO
    bobcat(7),
    isymcryptstream(3bobcat), isymcryptstreambuf(3bobcat),
    osymcryptstream(3bobcat)
BUGS
    None Reported.
BOBCAT PROJECT FILES
    -  https://fbb-git.gitlab.io/bobcat/: gitlab project page;
    
-  bobcat_6.06.02-x.dsc: detached signature;
    
-  bobcat_6.06.02-x.tar.gz: source archive;
    
-  bobcat_6.06.02-x_i386.changes: change log;
    
-  libbobcat1_6.06.02-x_*.deb: debian package containing the
            libraries;
    
-  libbobcat1-dev_6.06.02-x_*.deb: debian package containing the
            libraries, headers and manual pages;
    
BOBCAT
    Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
COPYRIGHT
    This is free software, distributed under the terms of the
    GNU General Public License (GPL).
AUTHOR
    Frank B. Brokken (f.b.brokken@rug.nl).