.TH "FBB::OSymCryptStream" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Symmetric en\- and decryption"

.PP 
.SH "NAME"
FBB::OSymCryptStream \- std::ostream performing symmetric
en/decryption
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/osymcryptstream>\fP
.br 
Linking option: \fI\-lbobcat \-lcrypto\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::OSymCryptStream\fP objects can be used to encrypt or decrypt
information,  that is available on separate \fIstd::istream\fP streams\&.
.PP 
The class \fIOSymCryptStream\fP is a class template, using a
\fIFBB::CryptType\fP template non\-type parameter\&. Objects of the class
\fIFBB::OSymCryptStream<FBB::ENCRYPT>\fP encrypt the information they receive,
objects of the class \fIFBB::OSymCryptStream<FBB::DECRYPT>\fP decrypt the
information they receive\&.
.PP 
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\&.,
\fI\(dq\&aes\-256\-gcm\(dq\&\fP\&. For the currently supported cipher algorithms issue the
command
.nf 

    openssl list \-cipher\-algorithms
        
.fi 

.PP 
\fIOSymCryptStream\fP objects read the information to en/decrypt from an
external source (e\&.g\&., from \fIstd::istream\fP objects)\&.  The characters that
are encrypted or decrypted by \fIOSymCryptStream\fP objects are written to
\fIstd::ostream\fP objects which are at construction\-time specified as
\fIostream\fP references or by filename\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\fBFBB::OSymCryptStreambuf\fP (private), 
.br 
\fBstd::istream\fP
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBOSymCryptStream<CryptType>(std::ostream &outStream,
std::string const &cipherName,
std::string const &key,
std::string const &iv,
size_t inBufSize = 100)\fP:
.br 
This constructor defines a \fIstd::streambuf\fP encrypting or decrypting
the characters it receives\&.
.IP 
\- \fIOSymCryptStream<FBB::ENCRYPT>\fP objects perform encryption;
.br 
\fIOSymCryptStream<FBB::DECRYPT>\fP objects perform decryption;
.IP 
\- \fIOSymCryptStream<CryptType>\fP objects write the encrypted or decrypted
characters to \fIoutStream\fP;
.br 
\- The encryption method to use is specified by the \fIcipherName\fP
parameter\&. E\&.g\&., \fI\(dq\&AES\-256\-GCM\(dq\&\fP;
.br 
\- The symmetric key to use is specified by the \fIkey\fP parameter;
.br 
\- The initialization vector is specified by the \fIiv\fP parameter;
.br 
\- The \fIFBB::OSymCryptStreambuf\fP internally used buffer will hold
\fIinBufSize\fP characters\&. The default value is the smallest value that
is used\&. When specifying a smaller \fIbufSize\fP value the default value
is used;
.br 

.IP 
.IP o 
\fBOSymCryptStream<CryptType>(std::string const &outStreamName,
std::string const &cipherName,
std::string const &key,
std::string const &iv,
size_t inBufSize = 100)\fP:
.br 
Same constructor as the previous one, but this constructor\(cq\&s first
parameter specifies the name of the file to receive the encrypted or
decrypted characters\&.

.PP 
If the construction fails an exception is thrown, mentioning the openssl
function that failed to complete (see also \fIerrorMsg\fP below)\&.
.PP 
The move constructor is available, the copy constructor and assignment
operators are not available,
.PP 
.SH "INHERITED MEMBERS"

.PP 
Since the class is publicly derived from \fBstd::ostream\fP, all
\fIstd::ostream\fP members can be used\&.
.PP 
.SH "MEMBER FUNCTIONS"
.IP o 
\fBstatic std::string errorMsg()\fP:
.br 
If an openssl function fails an exception is thrown mentioning the
name of the failing function\&. In those cases the function \fIerrorMsg\fP can be
called returning a \fIstd::string\fP containing the openssl error code (returned
by \fIERR_get_error\fP) and its textual representation (returned by
\fIERR_error_string\fP)\&. If the reported error code is zero, then in fact no
error has occurred and the exception was spuriously reported;
.IP 
.IP o 
\fBstatic size_t keyLength(std::string const &cipherName)\fP:
.br 
returns the minimum key length required for cipher \fIcipherName\fP;
.IP 
.IP o 
\fBstatic size_t ivLength(std::sting const &cipherName)\fP:
.br 
returns the minimum length of the initialization vector that is
required for cipher \fIcipherName\fP\&.

.PP 
The latter two functions throw exceptions if \fIcipherName\fP does not
contain the name of a supported cipher algorithm\&.
.PP 
.SH "MANIPULATOR"
.IP o 
\fBstd::ostream &FBB::eoi(std::ostream &out)\fP:
.br 
By inserting the \fIeoi\fP manipulator into an \fIOSymCryptStream\fP object
insertion is considered complete\&. It completes the insertion of
information into the \fIstd::ostream\fP specified at construction time
as the \fIOSymCryptStream\(cq\&s\fP first argument\&. That way, you don\(cq\&t have
to wait until the \fIOSymCryptStream\fP object\(cq\&s destructor flushes that
stream\&. In the following example using the \fIeoi\fP manipulator is
illustrated in the (commented out lines near line 40): 
.nf 

    //in\&.seekg(0);              // when activated, this won\(cq\&t
    //enc << in\&.rdbuf();        // be processed due to \(cq\&<< eoi\(cq\&
        
.fi 
Activating those lines will not result in processing the \fIin\fP stream
twice\&.

.PP 
.SH "EXAMPLE"
.nf 
#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 << \(dq\&arg[1]: e \- encrypt, d \- decrypt,\en\(dq\&
                \(dq\&arg[2]: file to process, arg[3]: processed file\en\(dq\&;
        return 0;
    }

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

    char cipherName[] =
        \(dq\&AES\-256\-GCM\(dq\&
        //\(dq\&AES\-256\-CBC\(dq\&
    ;

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

    if (*argv[1] == \(cq\&e\(cq\&)
    {
        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\(cq\&t
        //enc << in\&.rdbuf();        // be processed due to \(cq\&<< eoi\(cq\&
    }
    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() << \(cq\&\en\(cq\&;
}
.fi 

.PP 
.SH "FILES"
\fIbobcat/osymcryptstream\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7),
\fBisymcryptstream\fP(3bobcat), \fBisymcryptstreambuf\fP(3bobcat),
\fBosymcryptstreambuf\fP(3bobcat)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP