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

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

    openssl list \-cipher\-algorithms
        
.fi 

.PP 
\fIISymCryptStream\fP objects read the information to en/decrypt from
\fIstd::istream\fP objects, which are at construction\-time specified as
\fIistream\fP references or by filename\&. The characters that are thereupon
extracted or read from \fIISymCryptStream\fP objects are en/decrypted, and
could, e\&.g\&., be written to some output stream\&.
.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::ISymCryptStreambuf\fP (private), 
.br 
\fBstd::istream\fP
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBISymCryptStream<CryptType>(std::istream &inStream,
std::string const &cipherName,
std::string const &key,
std::string const &iv,
size_t inBufSize = 100)\fP:
.br 
This constructor defines a \fIstd::istream\fP object encrypting or
decrypting the characters which are read from \fIinStream\fP\&.
.IP 
\- \fIISymCryptStream<FBB::ENCRYPT>\fP objects perform encryption;
.br 
\fIISymCryptStream<FBB::DECRYPT>\fP objects perform decryption;
.IP 
\- \fIISymCryptStream<CryptType>\fP objects receive the characters to encrypt
or decrypt from \fIinStream\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::ISymCryptStreambuf\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 than the default
value then the default value is used;
.br 

.IP 
.IP o 
\fBISymCryptStream<CryptType>(std::string const &inStreamName,
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 containing the characters to
encrypt or decrypt\&.

.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::istream\fP, all
\fIstd::istream\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 "EXAMPLE"
.nf 
#include <iostream>
#include <fstream>
#include <string>

#include <bobcat/isymcryptstream>
#include <bobcat/isymcryptstreambuf>

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\&;
    string iv = \(dq\& 0123456789ab\(dq\& \(dq\&456\(dq\&;

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

    ifstream in = Exception::factory<ifstream>(argv[2]);
    ofstream out{ argv[3] };

    ISymCryptStreambuf<ENCRYPT> encbuf{ in, cipherName, key, iv, 100 };

    if (*argv[1] == \(cq\&e\(cq\&)
    {
        ISymCryptStream<ENCRYPT> enc{ in, cipherName, key, iv, 100 };
            // comment out the previous line and uncomment the next
            // to use the constructor expecting a string as 1st arg:
//      ISymCryptStream<ENCRYPT> enc{ argv[2], cipherName, key, 
//                                    iv, 100};

        out << enc\&.rdbuf();
    }
    else
    {
        ISymCryptStream<DECRYPT> decrypt{ in, cipherName, key, iv, 100 };
            // comment out the previous line and uncomment the next
            // to use the constructor expecting a string as 1st arg:
//      ISymCryptStream<DECRYPT> decrypt{ argv[2], cipherName, key, 
//                                        iv, 100 };
        out << decrypt\&.rdbuf();
    }
}
catch (exception const &exc)
{
    cerr << exc\&.what() << \(cq\&\en\(cq\&;
}





.fi 

.PP 
.SH "FILES"
\fIbobcat/isymcryptstream\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBisymcryptstreambuf\fP(3bobcat),
\fBosymcryptstream\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