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

FreeBSD Manual Pages

  
 
  

home | help
FBB::DecryptBuf(3bobcat)      Decrypt information     FBB::DecryptBuf(3bobcat)

NAME
       FBB::DecryptBuf	-  Decrypts  information  using	various	methods	into a
       std::ostream

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

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

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

       All  encryption	methods	defined	by the OpenSSL library that can	be se-
       lected by name may be used in combination with DecryptBuf objects. Most
       likely the information will have	been encrypted using an	EncryptBuf ob-
       ject, selecting a particular encryption method. The  encryption	method
       used  when  encrypting  information  should also	be specified when con-
       structing a DecryptBuf object. Likewise,	the constructor	expects	a  key
       and  initialization  vector. The	key and	initialization vector that was
       passed to the EncryptBuf	object must be	passed	to  DecryptBuf's  con-
       structor	as well.

       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/DESTRUCTOR
       o      DecryptBuf(std::ostream	 &outStream,	char	const	*type,
	      std::string const	&key, std::string const	&iv, size_t bufsize  =
	      1024):
	      This  constructor	initializes the	DecryptBuf object preparing it
	      for the message decrypt algorithm	specified with type.  The  de-
	      cryption	algorithms  that  can  be used are listed in the table
	      found in the EncryptBuf(3bobcat) manual page. As an example:  to
	      use  the AES method on 192 bit keys and blocks in	CBC mode spec-
	      ify "aes-192-cbc". The key parameter refers to  the  key	to  be
	      used,  the  iv  parameter	refers to the initialization vector to
	      use. The iv's length cannot be zero. When	 using	ECB  modes  no
	      initialization vector is used. In	those cases any	non-empty ini-
	      tialization vector may be	provided.

	      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 decrypted information.

	      The bufsize argument specifies the size in bytes of the internal
	      buffer used by DecryptBuf	to store incoming characters temporar-
	      ily. The provided	default	argument should	be OK  in  all	normal
	      cases.

       o      ~DecryptBuf():
	      The  destructor  calls the done()	member (see below), prevending
	      any exception that function might	throw  from  leaving  the  de-
	      structor.	 In  this case only a non thread-safe way to determine
	      whether the decryption was successfully completed	 is  available
	      through  the static member function lastOK() (see	below).	 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::DecryptBuf	inher-
       its from	this class. Some of the	std::streambuf's member	are overridden
       or  are hidden by DecryptBuf. In	normal situations these	inherited mem-
       bers will not be	used by	programs using DecryptBuf objects.

       o      void done():
	      This member can be called	to indicate that all information to be
	      decrypted	 has been received. It throws an FBB::Exception	excep-
	      tion if decryption fails (resulting from providing the  Decrypt-
	      Buf object with incorrect	(usually improperly padded) input). If
	      not explicitly called it is called by  DecryptBuf's  destructor,
	      preventing its exception from leaving the	destructor.

       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  de-
	      crypted. When called after decryption has	started	or when	speci-
	      fying an empty intialization vector an FBB::Exception  exception
	      will  be	thrown.	 When using ECB	modes no initialization	vector
	      is used. In those	cases any non-empty initialization vector  may
	      be provided.

       o      bool setRounds(size_t nRounds):
	      This  member  can	only be	used with the RC5 decryption 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  decryption	 methods  than	RC5 or the requested number of
	      rounds differ from 8, 12 or 16).

STATIC MEMBER
       o      bool lastOK():
	      This member is a non thread-safe way to  determine  whether  the
	      decryption has succeeded when the	 DecryptBuf object's done mem-
	      ber has not been called and the object has  been	destroyed.  In
	      that case	the object's destructor	will call done to complete the
	      decryption. The member lastOK returns true if the	DecryptBuf ob-
	      ject   destroyed last could complete its decryption successfully
	      and returns false	otherwise.

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

EXAMPLE
       #include	<iostream>
       #include	<fstream>
       #include	<bobcat/errno>
       #include	<bobcat/decryptbuf>

       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: file to "
			   "decrypt (to	stdout), 4th arg: iv");

	   cerr	<< "Key: `" << argv[2] << "'\n"
		   "IV:	 `" << argv[4] << "'\n";

	   DecryptBuf decryptbuf(cout, argv[1],	argv[2], argv[4]);
	   ostream out(&decryptbuf);
	   ifstream in(argv[3]);

	   out << in.rdbuf();
	   // decryptbuf.done();       // optionally
       }
       catch(Errno const &err)
       {
	   cout	<< err.why() <<	endl;
	   return 1;
       }

FILES
       bobcat/decryptbuf - defines the class interface

SEE ALSO
       bobcat(7), encryptbuf(3bobcat), std::streambuf

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::DecryptBuf(3bobcat)

NAME | SYNOPSIS | DESCRIPTION | NAMESPACE | INHERITS FROM | CONSTRUCTOR/DESTRUCTOR | MEMBER FUNCTIONS | STATIC MEMBER | 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=decryptbuf&sektion=3bobcat&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help