.TH "FBB::ISymCryptStreambuf" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Symmetric Encryption Stream Buffer" .PP .SH "NAME" FBB::ISymCryptStreambuf \- Input Filtering stream buffer doing symmetric encryption .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat \-lcrypto\fP .PP .SH "DESCRIPTION" The information made available by \fBISymCryptStreambuf\fP objects has been subject to symmetric encryption or decryption\&. The information to be encrypted or decrypted is made available to \fBISymCryptStreambuf\fP object via \fIstd::istream\fP objects\&. .PP The \fIclass ISymCryptStreambuf\fP is a class template, using a \fIFBB::CryptType\fP template non\-type parameter\&. Objects of the class \fIFBB::ISymCryptStreambuf\fP encrypt the information they receive, objects of the class \fIFBB::ISymCryptStreambuf\fP decrypt the information they receive\&. See also section \fBENUMERATION\fP below\&. .PP All symmetric encryption methods defined by the OpenSSL library that can be selected by name may be used in combination with \fIEncryptBuf\fP objects\&. To select a particular encryption method an identifier is passed to the constructor\&. E\&.g\&., \fI\(dq\&aes\-128\-cbc\(dq\&\fP indicating the AES (Rijndael) method, using 128 bit sized keys and blocks using `cbc\(cq\& mode (see below for an explanation)\&. .PP When providing shorter keys than expected by the method the provided key is extended by adding the required number of 0\-bytes\&. (zero valued bytes, not \fI\(cq\&0\(cq\&\fP characters)\&. .PP Most modes use an \fIinitialization vector\fP\&. The initialization vector must be provided at construction time\&. The matching decrypting object needs to know the initialization vector that was used when encrypting the data: the application must ensure that the matching decryption object receives the same initialization vector as the one that was provided to the encryption object\&. Initialization vectors are not security sensitive in the sense that they can be sent in the clear to the decryption object\&. What \fIis\fP important, though, is that they contain random data when used `for real\(cq\&\&. When an initialization vector is specified that is shorter than expected by the method it will be extended with the required number of 0\-bytes\&. .PP Block ciphers use one of the following four encryption modes: .IP o \fBCBC (Cipher Block Chaining)\fP: .br The first block is XOR\-ed by the initialization vector and then encrypted using the specified method\&. Subsequent blocks are XOR\-ed by the encrypted version of the preceding block\&. Due to the initialization vector dictionary attacks are infeasible, as long as the initialization vector is truly random\&. .IP o \fBECB (Electronic Code Book)\fP: .br Each block is encrypted by itself, using the specified encryption method\&. Although an \fIinitialization vector\fP may be specified, it is not used\&. This method is susceptible to dictionary attacks and should therefore be avoided, unless you know what you\(cq\&re doing\&. .IP o \fBCFB (Cipher Feednack)\fP: .br This method allows a block cipher to be used as a stream cipher\&. It uses an initialization vector, which should be unique and random for each new stream of data that is encrypted using the method\&. Encryption can only start after the first data block has been received\&. .IP o \fBOFB (Output Feednack)\fP: .br This is an alternative way to use a block cipher as a stream cipher\&. It is somewhat more susceptible to traditional data manipulation attacks, which can usually be thwarted when a message authentication code is added to the information as well\&. Like CFB it uses an initialization vector, which should again be unique and random for each new stream of data that is encrypted\&. .PP The following table presents an overview of methods that are currently available\&. Methods for which the block size is specified as N\&.A\&. are stream ciphers; other methods are block ciphers: .TS tab(~); ----- lllll lllll ----- lllll lllll lllll lllll lllll lllll lllll lllll lllll lllll lllll lllll ----- lllll lllll lllll lllll lssss ----- lllll lllll lllll lllll lllll lllll lllll lllll lllll lllll lllll lllll ----- lllll lllll lllll lllll lssss ----- lllll lllll lllll lllll ----- lllll ----- lllll lllll lllll lllll ----- lllll lllll lllll lllll lssss lssss ----- lllll lllll lllll lllll lssss ----- lllll lssss ----- lllll lssss ----- lllll lssss lssss ----- lllll lssss ----- lllll lllll lllll lllll lssss lssss ----- c. method~keysize~blocksize~mode~identifier ~(bytes)~(bytes)~ AES~16~8~CBC~\(dq\&aes\-128\-cbc\(dq\& ~ ~ ~EBC~\(dq\&aes\-128\-ecb\(dq\& ~ ~ ~CFB~\(dq\&aes\-128\-cfb\(dq\& ~ ~ ~OFB~\(dq\&aes\-128\-ofb\(dq\& ~24~24~CBC~\(dq\&aes\-192\-cbc\(dq\& ~ ~ ~EBC~\(dq\&aes\-192\-ecb\(dq\& ~ ~ ~CFB~\(dq\&aes\-192\-cfb\(dq\& ~ ~ ~OFB~\(dq\&aes\-192\-ofb\(dq\& ~32~32~CBC~\(dq\&aes\-256\-cbc\(dq\& ~ ~ ~EBC~\(dq\&aes\-256\-ecb\(dq\& ~ ~ ~CFB~\(dq\&aes\-256\-cfb\(dq\& ~ ~ ~OFB~\(dq\&aes\-256\-ofb\(dq\& BLOWFISH~16~8~CBC~\(dq\&bf\-cbc\(dq\& ~ ~ ~EBC~\(dq\&bf\-ecb\(dq\& ~ ~ ~CFB~\(dq\&bf\-cfb\(dq\& ~ ~ ~OFB~\(dq\&bf\-ofb\(dq\& max key length is 56 bytes, 16 generally used~ CAMELLIA~16~16~CBC~\(dq\&camellia\-128\-cbc\(dq\& ~ ~ ~EBC~\(dq\&camellia\-128\-ecb\(dq\& ~ ~ ~CFB~\(dq\&camellia\-128\-cfb\(dq\& ~ ~ ~OFB~\(dq\&camellia\-128\-ofb\(dq\& ~24~~CBC~\(dq\&camellia\-192\-cbc\(dq\& ~ ~ ~EBC~\(dq\&camellia\-192\-ecb\(dq\& ~ ~ ~CFB~\(dq\&camellia\-192\-cfb\(dq\& ~ ~ ~OFB~\(dq\&camellia\-192\-ofb\(dq\& ~32~~CBC~\(dq\&camellia\-256\-cbc\(dq\& ~ ~ ~EBC~\(dq\&camellia\-256\-ecb\(dq\& ~ ~ ~CFB~\(dq\&camellia\-256\-cfb\(dq\& ~ ~ ~OFB~\(dq\&camellia\-256\-ofb\(dq\& CAST~16~8~CBC~\(dq\&cast\-cbc\(dq\& ~ ~ ~EBC~\(dq\&cast\-ecb\(dq\& ~ ~ ~CFB~\(dq\&cast\-cfb\(dq\& ~ ~ ~OFB~\(dq\&cast\-ofb\(dq\& min key length is 5 bytes, max is shown~ DES~8~8~CBC~\(dq\&des\-cbc\(dq\& ~ ~ ~EBC~\(dq\&des\-ebc\(dq\& ~ ~ ~CFB~\(dq\&des\-cfb\(dq\& ~ ~ ~OFB~\(dq\&des\-ofb\(dq\& DESX~8~8~CBC~\(dq\&desx\-cbc\(dq\& 3DES~16~8~CBC~\(dq\&des\-ede\-cbc\(dq\& ~ ~ ~EBC~\(dq\&des\-ede\(dq\& ~ ~ ~CFB~\(dq\&des\-ede\-cfb\(dq\& ~ ~ ~OFB~\(dq\&des\-ede\-ofb\(dq\& 3DES~24~8~CBC~\(dq\&des\-ede3\-cbc\(dq\& ~ ~ ~EBC~\(dq\&des\-ede3\(dq\& ~ ~ ~CFB~\(dq\&des\-ede3\-cfb\(dq\& ~ ~ ~OFB~\(dq\&des\-ede3\-ofb\(dq\& Key bytes 9\-16 define the 2nd key, bytes 17\-24~ define the 3rd key~ RC2~16~8~CBC~\(dq\&rc2\-cbc\(dq\& ~ ~ ~EBC~\(dq\&rc2\-ecb\(dq\& ~ ~ ~CFB~\(dq\&rc2\-cfb\(dq\& ~ ~ ~OFB~\(dq\&rc2\-ofb\(dq\& Key length variable, max\&. 128 bytes, default length is shown~ RC2\-40~5~8~~\(dq\&rc2\-40\-cbc\(dq\& obsolete: avoid~ RC2\-64~8~8~~\(dq\&rc2\-64\-cbc\(dq\& obsolete: avoid~ RC4~16~N\&.A\&.~~\(dq\&rc4\(dq\& Key length is variable, max\&. 256 bytes\&. default length is shown~ Encrypt again to decrypt\&. Don\(cq\&t use \fIDecryptBuf\fP~ RC4\-40~5~N\&.A\&.~~\(dq\&rc4\-40\(dq\& obsolete: avoid~ RC5~16~8~CBC~\(dq\&rc5\-cbc\(dq\& ~ ~ ~EBC~\(dq\&rc5\-ecb\(dq\& ~ ~ ~CFB~\(dq\&rc5\-cfb\(dq\& ~ ~ ~OFB~\(dq\&rc5\-ofb\(dq\& Key length variable, max\&. 256 bytes, rounds 8, 12 or 16,~ default # rounds is 12~ .TE .PP The RC4 stream cipher is subject to a well\-known attack (cf\&. http://www\&.wisdom\&.weizmann\&.ac\&.il/~itsik/RC4/Papers/Mantin1\&.zip) unless the initial 256 bytes produced by the cipher are discarded\&. .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::IFilterBuf\fP .PP .SH "MEMBER FUNCTIONS" All members of \fBFBB::IFilterBuf\fP are available, as \fBISymCryptStreambuf\fP inherits from this class\&. .PP Overloaded move and/or copy assignment operators are not available\&. .PP .SH "ENUMERATION" .PP \fBISymCryptStreambuf\fP objects either encrypt or decrypt information\&. \fBISymCryptStreambuf\fP objects of the class \fBFBB::ISymCryptStreambuf\fP encrypt the data they receive, \fBISymCryptStreambuf\fP objects of the class \fBFBB::ISymCryptStreambuf\fP decrypt the data they receive\&. .PP The values \fIENCRYPT\fP and \fIDECRYPT\fP are defined in the \fIenum CryptType\fP, which is defined in the \fIFBB\fP namespace\&. .PP .SH "CONSTRUCTOR" .IP o \fBISymCryptStreambuf( std::istream &in, char const *type, std::string const &key, std::string const &iv, size_t bufSize = 100, size_t filterBufSize = 1000, ENGINE *engine = 0)\fP: .br This constructor initializes the streambuf\&. \- \fIISymCryptStreambuf\fP objects perform encryption; .br \fIISymCryptStreambuf\fP objects perform decryption; .br \- \fIISymCryptStreambuf\fP objects obtain the bytes to encrypt or decrypt from \fIstd::istream &in\fP; .br \- The encryption method to use is specified by the \fItype\fP parameter\&. E\&.g\&., \fI\(dq\&bf\-cbc\(dq\&\fP selects the Blowfish Cipher Block Chaining method; .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 contain \fIbufSize\fP characters\&. The default value is the smallest value that is used\&. When a smaller \fIbufSize\fP value is specified, the default value is used; .br \- \fIFBB::ISymCryptStreambuf\fP\(cq\&s \fIIFilterBuf\fP base class is initialized with a buffer of size \fIfilterBufSize\fP, using a lower bound of 100; .br \- The parameter \fIENGINE\fP can be used to specify a hardware acceleration engine, as supported by the used encryption/decryption method\&. Its default argument value indicates that no hardware acceleration is available\&. .PP Copy and move constructors (and assignment operators) are not available\&. .PP .SH "EXAMPLE" .PP The example shows the construction of an \fIISymCryptStreambuf\fP object \fIebuf\fP which is used to initialize a \fIstd::istream\fP object\&. The information read from this \fIistream\fP is encrypted using the Blowfish CBC method\&. A \fIISymCryptStreambuf\fP object (\fIdbuf\fP reads the information from that stream and decrypts it again)\&. The \fIstd::istream din\fP object is initialized with the \fIISymCryptStreambuf\fP object, and its content is sent to \fIstd::cout\fP\&. The information that is presented at \fIstd::cin\fP and that appears at \fIstd::cout\fP should be identical\&. .PP .nf #include #include using namespace std; using namespace FBB; int main() { ISymCryptStreambuf ebuf(cin, \(dq\&bf\-cbc\(dq\&, \(dq\&1234567890\(dq\&, \(dq\&1234567890\(dq\&); istream ein(&ebuf); ISymCryptStreambuf dbuf(ein, \(dq\&bf\-cbc\(dq\&, \(dq\&1234567890\(dq\&, \(dq\&1234567890\(dq\&); istream din(&dbuf); cout << din\&.rdbuf(); } .fi .PP .SH "FILES" \fIbobcat/isymcryptstreambuf\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBencryptbuf\fP(3bobcat), \fBisymcryptstream\fP(3bobcat), \fBibase64buf\fP(3bobcat), \fBifilterbuf\fP(3bobcat), \fBofilterbuf\fP(3bobcat), \fBstd::streambuf\fP\&. .PP .SH "BUGS" .PP Sep/Oct 2013: due to a change in library handling by the linker (cf\&. http://fedoraproject\&.org/wiki/UnderstandingDSOLinkChange and https://wiki\&.debian\&.org/ToolChain/DSOLinking) libraries that are indirectly required are no longer automatically linked to your program\&. With \fBBigInt\fP this is \fIlibcrypto\fP, which requires programs to link to both \fIbobcat\fP and \fIcrypto\fP\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_5\&.07\&.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