Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FBB::EncryptBuf(3bobcat)      Encrypt information     FBB::EncryptBuf(3bobcat)

NAME
       FBB::EncryptBuf	-  Encrypts  information  using	various	methods	into a
       std::ostream

SYNOPSIS
       #include	<bobcat/encryptbuf>
       Linking option:	-lbobcat

DESCRIPTION
       FBB::EncryptBuf objects are std::streambuf objects that can be used  to
       initialize std::ostream objects with.

       All  information	 inserted  into	 such  a std::ostream is encrypted and
       written into a std::ostream that	is given as argument  to  EncryptBuf's
       constructor.

       All  encryption	methods	defined	by the OpenSSL library that can	be se-
       lected by name may be used in combination with EncryptBuf  objects.  To
       select  a  particular  encryption method	an identifier is passed	to the
       constructor. E.g., "aes-128-cbc"	indicating the AES (Rijndael)  method,
       using  128 bit sized keys and blocks using `cbc'	mode (see below	for an
       explanation).

       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 '0' characters).

       Most modes use an initialization	vector.	Unless provided	 at  construc-
       tion  time  or  explicitly set thereafter an initialization vector con-
       taing randomly selected values will be used. The	initialization	vector
       that  is	actually used can be obtained from the EncryptBuf object. This
       is important, as	the matching decrypting	object needs to	know the  ini-
       tialization  vector that	was used when encrypting the data. Initializa-
       tion vectors are	not security sensitive in the sense that they  can  be
       sent  in	the clear to the decryption object. What is important, though,
       is that they contain random data	when used `for real'. When an initial-
       ization vector is specified that	is shorter than	expected by the	method
       it will be extended with	the required number of 0-bytes.

       Block ciphers use one of	the following four encryption modes:

       o      CBC (Cipher Block	Chaining):
	      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.

       o      ECB (Electronic Code Book):
	      Each block is encrypted by itself, using the  specified  encryp-
	      tion method. Although an initialization vector may be specified,
	      it is not	used. This method is susceptible to dictionary attacks
	      and should therefore be avoided, unless you know what you're do-
	      ing.

       o      CFB (Cipher Feednack):
	      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.

       o      OFB (Output Feednack):
	      This is an alternative way to use	a block	cipher as a stream ci-
	      pher. It is somewhat more	susceptible to traditional data	manip-
	      ulation 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.

       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:

       ----------------------------------------------------------------
       method	   keysize    blocksize	   mode	   identifier
		   (bytes)    (bytes)
       ----------------------------------------------------------------
       AES	   16	      8		   CBC	   "aes-128-cbc"
					   EBC	   "aes-128-ecb"
					   CFB	   "aes-128-cfb"
					   OFB	   "aes-128-ofb"
		   24	      24	   CBC	   "aes-192-cbc"
					   EBC	   "aes-192-ecb"
					   CFB	   "aes-192-cfb"
					   OFB	   "aes-192-ofb"
		   32	      32	   CBC	   "aes-256-cbc"
					   EBC	   "aes-256-ecb"
					   CFB	   "aes-256-cfb"
					   OFB	   "aes-256-ofb"
       ----------------------------------------------------------------
       BLOWFISH	   16	      8		   CBC	   "bf-cbc"
					   EBC	   "bf-ecb"
					   CFB	   "bf-cfb"
					   OFB	   "bf-ofb"
       max key length is 56 bytes, 16 generally	used
       ----------------------------------------------------------------
       CAMELLIA	   16	      16	   CBC	   "camellia-128-cbc"
					   EBC	   "camellia-128-ecb"
					   CFB	   "camellia-128-cfb"
					   OFB	   "camellia-128-ofb"
		   24			   CBC	   "camellia-192-cbc"
					   EBC	   "camellia-192-ecb"
					   CFB	   "camellia-192-cfb"
					   OFB	   "camellia-192-ofb"
		   32			   CBC	   "camellia-256-cbc"
					   EBC	   "camellia-256-ecb"
					   CFB	   "camellia-256-cfb"
					   OFB	   "camellia-256-ofb"
       ----------------------------------------------------------------
       CAST	   16	      8		   CBC	   "cast-cbc"
					   EBC	   "cast-ecb"
					   CFB	   "cast-cfb"
					   OFB	   "cast-ofb"
       min key length is 5 bytes, max is shown
       ----------------------------------------------------------------
       DES	   8	      8		   CBC	   "des-cbc"
					   EBC	   "des-ebc"
					   CFB	   "des-cfb"
					   OFB	   "des-ofb"
       ----------------------------------------------------------------
       DESX	   8	      8		   CBC	   "desx-cbc"
       ----------------------------------------------------------------
       3DES	   16	      8		   CBC	   "des-ede-cbc"
					   EBC	   "des-ede"
					   CFB	   "des-ede-cfb"

					   OFB	   "des-ede-ofb"
       ----------------------------------------------------------------
       3DES	   24	      8		   CBC	   "des-ede3-cbc"
					   EBC	   "des-ede3"
					   CFB	   "des-ede3-cfb"
					   OFB	   "des-ede3-ofb"
       Key bytes 9-16 define the 2nd key, bytes	17-24
       define the 3rd key
       ----------------------------------------------------------------
       RC2	   16	      8		   CBC	   "rc2-cbc"
					   EBC	   "rc2-ecb"
					   CFB	   "rc2-cfb"
					   OFB	   "rc2-ofb"
       Key length variable, max. 128 bytes, default length is shown
       ----------------------------------------------------------------
       RC2-40	   5	      8			   "rc2-40-cbc"
       obsolete: avoid
       ----------------------------------------------------------------
       RC2-64	   8	      8			   "rc2-64-cbc"
       obsolete: avoid
       ----------------------------------------------------------------
       RC4	   16	      N.A.		   "rc4"
       Key length is variable, max. 256	bytes. default length is shown
       Encrypt again to	decrypt. Don't use DecryptBuf
       ----------------------------------------------------------------
       RC4-40	   5	      N.A.		   "rc4-40"
       obsolete: avoid
       ----------------------------------------------------------------
       RC5	   16	      8		   CBC	   "rc5-cbc"
					   EBC	   "rc5-ecb"
					   CFB	   "rc5-cfb"
					   OFB	   "rc5-ofb"
       Key length variable, max. 256 bytes, rounds 8, 12 or 16,
       default # rounds	is 12
       ----------------------------------------------------------------

       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.

NAMESPACE
       FBB
       All  constructors,  members,  operators	and manipulators, mentioned in
       this man-page, are defined in the namespace FBB.

INHERITS FROM
       std::streambuf

CONSTRUCTOR
       o      EncryptBuf(std::ostream	&outStream,    char    const	*type,
	      std::string  const &key, std::string const &iv, size_t bufsize =
	      1024):
	      This constructor initializes the EncryptBuf object preparing  it
	      for  the	message	encrypt	algorithm specified with type. The en-
	      cryption algorithms that can be used are	listed	in  the	 table
	      found in the DESCRIPTION section.	E.g., to use the AES method on
	      24 bit keys and blocks in	CBC mode  specify  "aes-192-cbc".  The
	      key  parameter  refers  to  the key to be	used, the iv parameter
	      refers to	the initialization vector to use. Both key and iv  may
	      contain  non-displayable characters. When	iv.length() is zero at
	      the time encryption starts it will be filled by  the  EncryptBuf
	      object with random data. When the	key and/or the iv is too small
	      for the requested	method they will be expanded by	adding the re-
	      quired number of zero valued bytes.

	      The constructor throws an	FBB::Exception exception if an unknown
	      encryption method	was specified.

	      The constructor's	first parameter	refers to the std::ostream  to
	      receive the encrypted information. Be aware of the fact that the
	      encrypted	information most likely	contains non-displayable char-
	      acters.

	      The bufsize argument specifies the size in bytes of the internal
	      buffer used by EncryptBuf	to store incoming characters temporar-
	      ily.  The	 provided  default argument should be OK in all	normal
	      cases.  There is no copy constructor, nor	move  constructor  (as
	      std::streambuf doesn't support either).

MEMBER FUNCTIONS
       All  members of std::streambuf are available, as	FBB::EncryptBuf	inher-
       its from	this class. Some of the	std::streambuf's member	are overridden
       or  are hidden by EncryptBuf. In	normal situations these	inherited mem-
       bers will not be	used by	programs using EncryptBuf objects.

       o      size_t blockLength() const:
	      This member returns the block size (in bytes) that are  used  by
	      the specified method.

       o      size_t ivLength()	const:
	      This  member  returns  the size (in bytes) of the	initialization
	      vector that is used by the specified method.

       o      std::string iv() const:
	      This member returns a reference  to  the	initialization	vector
	      that  is	used by	the specified method. Be advised that the ini-
	      tialization vector may contain non-displayable characters.

       o      size_t keyLength() const:
	      This member returns the size of the key (in bytes) that are used
	      by the specified method.

       o      size_t rounds() const:
	      This  member  can	only be	used with the RC5 encryption method to
	      query the	number of rounds of the	algorithm. It returns the cur-
	      rently  used  number  of rounds or 0 if the member is called for
	      another encryption method	than RC5.

       o      void setIv(std::string const &iv):
	      This member can be used to specify the initialization vector  to
	      use  after  construction	time  but before any data has been en-
	      crypted. When called after encryption has	started	an FBB::Excep-
	      tion exception will be thrown.

       o      void setKey(std::string const &key, size_t numberOfBytes = 0):
	      This  member can be used to specify the key and its length after
	      construction time	but before any data has	been  encrypted.  When
	      called  after encryption has started an FBB::Exception exception
	      will be thrown. The size of the key is assumed to	be the	number
	      of  bytes	 in  the key's data. If	another	key length is required
	      the member function's second parameter can be  used  to  specify
	      the length of the	key in bytes.

       o      bool setRounds(size_t nRounds):
	      This  member  can	only be	used with the RC5 encryption method to
	      set the number of	rounds of the algorithm	to 8, 12 or  16.  When
	      the  number  of  rounds were updated successfully	the member re-
	      turns true. It returns false in other cases  (e.g.,  called  for
	      other  encryption	 methods  than	RC5 or the requested number of
	      rounds differ from 8, 12 or 16).

PROTECTED MEMBER
       o      EVP_CIPHER_CTX *cipherCtx():
	      Classes derived from EncryptBuf may use this member to gain  di-
	      rect access to the EVP_CIPHER_CTX	pointer	used by	the EncryptBuf
	      object. This pointer is a	pointer	to an opaque structure used by
	      many  OpenSSL functions to set or	query parameters of an encryp-
	      tion method.

EXAMPLE
       #include	<iostream>
       #include	<fstream>
       #include	<bobcat/errno>
       #include	<bobcat/encryptbuf>
       #include	<bobcat/ohexstreambuf>

       #include	<openssl/evp.h>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
	   if (argc == 1)
	       throw Errno("1st	arg: method, 2nd arg: key, 3rd arg:  (opt): iv,	"
			   "stdin: file	to encrypt (to stdout)");

	   string key(argv[2]);
	   string iv;

	   if (argc > 3)
	       iv = argv[3];

	   EncryptBuf encryptbuf(cout, argv[1],	key, iv);
	   ostream out(&encryptbuf);

	   cerr	<< "Block length: " << encryptbuf.blockLength()	<< '\n'	<<
		   "Key	length:	" << encryptbuf.keyLength() << '\n' <<
		   "Max	Key length: " << EVP_MAX_KEY_LENGTH << '\n' <<
		   "IV length: " << encryptbuf.ivLength() << endl;

	   cerr	<< encryptbuf.iv().length() << ' ';

	   OHexStreambuf ohsb(cerr);

	   ostream ohs(&ohsb);
	   ohs.write(encryptbuf.iv().data(), encryptbuf.iv().length()) << flush;
	   cerr	<< endl;

	   out << cin.rdbuf();
       }
       catch(Errno const &err)
       {
	   cout	<< err.why() <<	endl;
	   return 1;
       }

       To ignore the initial 256 bytes generated by the	RC4 algorithm a	simple
       wrapper class around the	eventual output	stream can be used. Here is an
       illustration:

	   #include <ostream>
	   #include <bobcat/ofilterstreambuf>

	   class Skip256: public FBB::OFilterStreambuf
	   {
	       size_t d_count;
	       public:
		   Skip256(std::ostream	&os)
		   :
		       OFilterStreambuf(os),
		       d_count(0)
		   {}
	       private:
		   virtual int overflow(int c)
		   {
		       if (d_count == 256)
			   out().put(c);
		       else
			   ++d_count;
		       return c;
		   }
	   };

       Next, an	Skip256	object is used to define an intermediate  std::ostream
       that  is	 then  passed to the EncryptBuf	object.	E.g., only showing the
       essential steps defining	the EncryptBuf object:

	   Skip256 skip256(std::cout);
	   std::ostream	out(&skip256);

	   EncryptBuf encryptbuf(out, "rc4", key, "");

FILES
       bobcat/encryptbuf - defines the class interface

SEE ALSO
       bobcat(7), decryptbuf(3bobcat), ofilterstreambuf(3bobcat), std::stream-
       buf

BUGS
       None reported

DISTRIBUTION FILES
       o      bobcat_3.25.01-x.dsc: detached signature;

       o      bobcat_3.25.01-x.tar.gz: source archive;

       o      bobcat_3.25.01-x_i386.changes: change log;

       o      libbobcat1_3.25.01-x_*.deb:   debian  package  holding  the  li-
	      braries;

       o      libbobcat1-dev_3.25.01-x_*.deb: debian package holding  the  li-
	      braries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

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).

libbobcat-dev_3.25.01-x.tar.gz	   2005-2015	      FBB::EncryptBuf(3bobcat)

NAME | SYNOPSIS | DESCRIPTION | NAMESPACE | INHERITS FROM | CONSTRUCTOR | MEMBER FUNCTIONS | PROTECTED MEMBER | EXAMPLE | FILES | SEE ALSO | BUGS | DISTRIBUTION FILES | BOBCAT | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=encryptbuf&sektion=3bobcat&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help