.TH "FBB::OSymCryptStreambuf" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.03\&.02" "Symmetric en\- and decryption"

.PP 
.SH "NAME"
FBB::OSymCryptStreambuf \- std::streambuf performing symmetric
en/decryption
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/osymcryptstreambuf>\fP
.br 
Linking option: \fI\-lbobcat \-lcrypto\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::OSymCryptStreambuf\fP objects can be used as \fIstd::streambuf\fP
objects of \fIstd::ostream\fP objects, and encrypt or decrypt
information, that is made available via separate \fIstd::istream\fP streams\&.
.PP 
The class \fIOSymCryptStreambuf\fP is a class template, using a
\fIFBB::CryptType\fP template non\-type parameter\&. Objects of the class
\fIFBB::OSymCryptStreambuf<FBB::ENCRYPT>\fP encrypt the information they receive,
objects of the class \fIFBB::OSymCryptStreambuf<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 
\fIOSymCryptStreambuf\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 \fIOSymCryptStreambuf\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::OSymCryptBase\fP (public)
.PP 
The class \fIFBB::OSymCryptBase\fP is an `internal use only\(cq\& class, derived
from \fIstd::streambuf\fP, and therefore \fIOSymCryptStreambuf\fP is a
\fIstd::streambuf\fP class\&.
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBOSymCryptStreambuf<CryptType>(std::ostream &outStreambuf,
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 
\- \fIOSymCryptStreambuf<FBB::ENCRYPT>\fP objects perform encryption;
.br 
\fIOSymCryptStreambuf<FBB::DECRYPT>\fP objects perform decryption;
.IP 
\- \fIOSymCryptStreambuf<CryptType>\fP objects write the encrypted or decrypted
characters to \fIoutStreambuf\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::OSymCryptStreambufbuf\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 
\fBOSymCryptStreambuf<CryptType>(std::string const &outStreambufName,
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::streambuf\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 \fIstd::ostream\fP object
that uses a \fIOSymCryptStreambuf\fP streambuf insertion is considered
complete\&. It completes the insertion of information into the
\fIstd::ostream\fP specified at construction time as the
\fIOSymCryptStreambuf\(cq\&s\fP first argument\&. That way, you don\(cq\&t have to
wait until the \fIOSymCryptStreambuf\fP object\(cq\&s destructor flushes that
stream\&. The example provided at the \fBosymcryptstream\fP(3bobcat)
man\-page illustrates the use of the \fIeoi\fP manipulator\&.

.PP 
.SH "EXAMPLE"
See the example in the \fBosymcryptstream\fP(3bobcat) man\-page\&. Instead of
defining an \fIOSymCryptStream\fP an \fIOSymCryptStreamBuf\fP can be defined,
passing its address to a \fIstd::ostream\fP which can then be used as the
\fIOSymCryptStream\fP used in the example\&.
.PP 
.SH "FILES"
\fIbobcat/osymcryptstreambuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7),
\fBisymcryptstream\fP(3bobcat), \fBisymcryptstreambuf\fP(3bobcat),
\fBosymcryptstream\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\&.03\&.02\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.03\&.02\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.03\&.02\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.03\&.02\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.03\&.02\-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