Updated documentation

Author: noloader

cryptlib.h

@@ -875,10 +875,11 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE StreamTransformation : public Algorithm
 	//! \param inString the input byte buffer
 	//! \param inLength the size of the input byte buffer, in bytes
 	//! \returns the number of bytes used in outString
-	//!  ProcessLastBlock is used when the last block of data is special and the
-	//!   cipher text may expand larger than input data length. The current implementation provides
-	//!   an output buffer with a size <tt>inLength+2*MandatoryBlockSize()</tt>. This member function
-	//!   is used by CBC-CTS and OCB modes.
+	//! \details ProcessLastBlock is used when the last block of data is special and requires handling
+	//!   by the cipher. The current implementation provides an output buffer with a size
+	//!   <tt>inLength+2*MandatoryBlockSize()</tt>. The return value allows the cipher to expand cipher text
+	//!   during encryption or shrink plain text during decryption.
+	//! \details This member function is used by CBC-CTS and OCB modes.
 	//! \sa IsLastBlockSpecial
 	virtual size_t ProcessLastBlock(byte *outString, size_t outLength, const byte *inString, size_t inLength);
 
@@ -891,15 +892,34 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE StreamTransformation : public Algorithm
 	//! \brief Determines if the last block receives special processing
 	//! \returns true if the last block reveives special processing, false otherwise.
 	//! \details Some authenticated encryption modes have needs that are not expressed well
-	//!   with MandatoryBlockSize() and MinLastBlockSize(). When IsLastBlockSpecial() returns
-	//!   true three things happen. First, standard block cipher padding is not applied.
-	//!   Second, the ProcessLastBlock() is used that provides inString and outString lengths.
-	//!   Third, outString is larger than inString by <tt>2*MandatoryBlockSize()</tt>. That is,
-	//!   there's a reserve available when processing the last block.
+	//!   with MandatoryBlockSize() and MinLastBlockSize(). For example, AES/OCB uses
+	//!   16-byte blocks (MandatoryBlockSize = 16) and the last block requires special processing
+	//!   (MinLastBlockSize = 0). However, 0 is a valid last block size for OCB and the special
+	//!   processing is custom padding, and not standard PKCS padding. In response an
+	//!   unambiguous IsLastBlockSpecial() was added.
+	//!  \details When IsLastBlockSpecial() returns false nothing special happens. All the former
+	//!   rules and behaviors apply. This is the default behavior of IsLastBlockSpecial().
+	//!  \details When IsLastBlockSpecial() returns true four things happen. First, MinLastBlockSize = 0
+	//!   means 0 is a valid block size that should be processed. Second, standard block cipher padding is
+	//!   \a not \a applied. Third, the caller supplies an outString is larger than inString by
+	//!   <tt>2*MandatoryBlockSize()</tt>. That is, there's a reserve available when processing the last block.
+	//!   Fourth, the cipher is responsible for finalization like custom padding. The cipher will tell
+	//!   the library how many bytes were processed or used by returning the appropriate value from
+	//!   ProcessLastBlock().
 	//! \details The return value of ProcessLastBlock() indicates how many bytes were written
-	//!   to outString. A filter driving data will send <tt>outString</tt> and <tt>outLength</tt>
-	//!   to an <tt>AttachedTransformation()</tt> for additional processing.
+	//!   to outString. A filter pipelining data will send <tt>outString</tt> and up to <tt>outLength</tt>
+	//!   to an <tt>AttachedTransformation()</tt> for additional processing. Below is an example of the code
+	//!   used in <tt>StreamTransformationFilter::LastPut</tt>.
+	//! <pre>  if (m_cipher.IsLastBlockSpecial())
+	//!   {
+	//!     size_t reserve = 2*m_cipher.MandatoryBlockSize();
+	//!     space = HelpCreatePutSpace(*AttachedTransformation(), DEFAULT_CHANNEL, length, length+reserve);
+	//!     length = m_cipher.ProcessLastBlock(space, length+reserve, inString, length);
+	//!     AttachedTransformation()->Put(space, length);
+	//!     return;
+	//!   }</pre>
 	//! \sa ProcessLastBlock
+	//! \since Crypto++ 6.0
 	virtual bool IsLastBlockSpecial() const {return false;}
 
 	//! \brief Encrypt or decrypt a string of bytes