Updated documentation

4 files changed, 49 insertions, 47 deletions

diff --git a/base32.h b/base32.h
index 27e222c5..05d68764 100644
--- a/base32.h
+++ b/base32.h
@@ -13,7 +13,7 @@ NAMESPACE_BEGIN(CryptoPP)
 

 //! \class Base32Encoder

 //! \brief Base32 encodes data

-//! \details Converts data to base32. The default code is based on draft-ietf-idn-dude-02.txt.

+//! \details Converts data to base32. The default code is based on <A HREF="http://www.ietf.org/proceedings/51/I-D/draft-ietf-idn-dude-02.txt">Differential Unicode Domain Encoding (DUDE) (draft-ietf-idn-dude-02.txt)</A>.

 class Base32Encoder : public SimpleProxyFilter

 {

 public:

@@ -41,25 +41,23 @@ public:
 	//!   <pre>

 	//!     Base32Encoder encoder;

 	//!     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);

-	//!     encoder.IsolatedInitialize(params);

-	//!   </pre>

-	//! \details The default encoding alpahbet is DUDE. You can change the encoding to RFC 4648 alphabet by

-	//!   performing the following:

+	//!     encoder.IsolatedInitialize(params);</pre>

+	//! \details You can change the encoding to <A HREF="http://tools.ietf.org/html/rfc4648#page-10">RFC 4648, Base

+	//!   32 Encoding with Extended Hex Alphabet</A> by performing the following:

 	//!   <pre>

 	//!     Base32Encoder encoder;

-	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";

+	//!     const byte ALPHABET[] = "0123456789ABCDEFGHIJKLMNOPQRSTUV";

 	//!     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);

-	//!     encoder.IsolatedInitialize(params);

-	//!   </pre>

+	//!     encoder.IsolatedInitialize(params);</pre>

 	//! \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and

 	//!   the decoder's lookup table.

-	//! \sa IsolatedInitialize() for an example of modifying a Base32Encoder after construction.

+	//! \sa Base32Decoder::IsolatedInitialize() for an example of changing a Base32Decoder's lookup table.

 	void IsolatedInitialize(const NameValuePairs &parameters);

 };

 

 //! \class Base32Decoder

 //! \brief Base32 decodes data

-//! \details Decode base32 data. The default code is based on draft-ietf-idn-dude-02.txt

+//! \details Decode base32 data. The default code is based on <A HREF="http://www.ietf.org/proceedings/51/I-D/draft-ietf-idn-dude-02.txt">Differential Unicode Domain Encoding (DUDE) (draft-ietf-idn-dude-02.txt)</A>.

 class Base32Decoder : public BaseN_Decoder

 {

 public:

@@ -74,17 +72,17 @@ public:
 	//! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable

 	//!   number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached

 	//!   transformations. If initialization should be propagated, then use the Initialize() function.

-	//! \details The default decoding alpahbet is DUDE. You can change the to RFC 4868 alphabet by

-	//!   performing the following:

+	//! \details You can change the encoding to <A HREF="http://tools.ietf.org/html/rfc4648#page-10">RFC 4648, Base

+	//!   32 Encoding with Extended Hex Alphabet</A> by performing the following:

 	//!   <pre>

 	//!     int lookup[256];

-	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";

+	//!     const byte ALPHABET[] = "0123456789ABCDEFGHIJKLMNOPQRSTUV";

 	//!     Base32Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 32, true /*insensitive*/);

 	//!

 	//!     Base32Decoder decoder;

 	//!     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);

-	//!     decoder.IsolatedInitialize(params);

-	//!   </pre>

+	//!     decoder.IsolatedInitialize(params);</pre>

+	//! \sa Base32Encoder::IsolatedInitialize() for an example of changing a Base32Encoder's alphabet.

 	void IsolatedInitialize(const NameValuePairs &parameters);

 

 private:

diff --git a/base64.h b/base64.h
index 70c3acde..6f6fd51f 100644
--- a/base64.h
+++ b/base64.h
@@ -13,7 +13,7 @@ NAMESPACE_BEGIN(CryptoPP)
 

 //! \class Base64Encoder

 //! \brief Base64 encodes data

-//! \details Base64 encodes data per RFC 4648 (http://tools.ietf.org/html/rfc4648#section-4)

+//! \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-4">RFC 4648, Base 64 Encoding</A>.

 class Base64Encoder : public SimpleProxyFilter

 {

 public:

@@ -21,9 +21,9 @@ public:
 	//! \param attachment a BufferedTrasformation to attach to this object

 	//! \param insertLineBreaks a BufferedTrasformation to attach to this object

 	//! \param maxLineLength the lenght of a line if line breaks are used

-	//! \details Base64Encoder() constructs a default encoder. The constructor lacks parameters for padding.

-	//!    You must use IsolatedInitialize() to modify the Base64Encoder after construction.

-	//! \sa Base64URLEncoder(), and IsolatedInitialize() for an example of modifying a Base64Encoder after construction.

+	//! \details Base64Encoder constructs a default encoder. The constructor lacks a parameter for padding, and you must

+	//!   use IsolatedInitialize() to modify the Base64Encoder after construction.

+	//! \sa IsolatedInitialize() for an example of modifying an encoder after construction.

 	Base64Encoder(BufferedTransformation *attachment = NULL, bool insertLineBreaks = true, int maxLineLength = 72)

 		: SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment)

 	{

@@ -39,31 +39,29 @@ public:
 	//!   <pre>

 	//!     Base64Encoder encoder;

 	//!     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);

-	//!     encoder.IsolatedInitialize(params);

-	//!   </pre>

-	//! \details The default encoding alpahbet is DUDE. You can change the encoding to RFC 4648 web safe alphabet

-	//!   by performing the following:

+	//!     encoder.IsolatedInitialize(params);</pre>

+	//! \details You can change the encoding to RFC 4648 web safe alphabet by performing the following:

 	//!   <pre>

 	//!     Base64Encoder encoder;

 	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

 	//!     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);

-	//!     encoder.IsolatedInitialize(params);

-	//!   </pre>

+	//!     encoder.IsolatedInitialize(params);</pre>

 	//! \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and

 	//!   the decoder's lookup table.

-	//! \sa Base64URLEncoder(), and IsolatedInitialize() for an example of modifying a Base64Encoder after construction.

+	//! \sa Base64URLEncoder for an encoder that provides the web safe alphabet, and Base64Decoder::IsolatedInitialize()

+	//!   for an example of modifying a decoder's lookup table after construction.

 	void IsolatedInitialize(const NameValuePairs &parameters);

 };

 

 //! \class Base64Decoder

 //! \brief Base64 decodes data

-//! \details Base64 decodes data per RFC 4648 (http://tools.ietf.org/html/rfc4648#section-4)

+//! \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-4">RFC 4648, Base 64 Encoding</A>.

 class Base64Decoder : public BaseN_Decoder

 {

 public:

 	//! \brief Construct a Base64Decoder

 	//! \param attachment a BufferedTrasformation to attach to this object

-	//! \sa Base64URLDecoder(), and IsolatedInitialize() for an example of modifying a Base64Decoder after construction.

+	//! \sa IsolatedInitialize() for an example of modifying an encoder after construction.

 	Base64Decoder(BufferedTransformation *attachment = NULL)

 		: BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {}

     

@@ -81,9 +79,9 @@ public:
 	//!

 	//!     Base64Decoder decoder;

 	//!     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);

-	//!     decoder.IsolatedInitialize(params);

-	//!   </pre>

-	//! \sa Base64URLDecoder(), and IsolatedInitialize() for an example of modifying a Base64Decoder after construction.

+	//!     decoder.IsolatedInitialize(params);</pre>

+	//! \sa Base64URLDecoder for a decoder that provides the web safe alphabet, and Base64Encoder::IsolatedInitialize()

+	//!   for an example of modifying an encoder's alphabet after construction.

 	void IsolatedInitialize(const NameValuePairs &parameters);

 

 private:

@@ -94,7 +92,8 @@ private:
 

 //! \class Base64URLEncoder

 //! \brief Base64 encodes data using a web safe alphabet

-//! \details Base64 encodes data using a web safe alphabet per RFC 4648 (http://tools.ietf.org/html/rfc4648#section-5)

+//! \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-5">RFC 4648, Base 64 Encoding

+//!   with URL and Filename Safe Alphabet</A>.

 class Base64URLEncoder : public SimpleProxyFilter

 {

 public:

@@ -102,13 +101,14 @@ public:
 	//! \param attachment a BufferedTrasformation to attach to this object

 	//! \param insertLineBreaks a BufferedTrasformation to attach to this object

 	//! \param maxLineLength the lenght of a line if line breaks are used

-	//! \details Base64URLEncoder() constructs a default encoder. The constructor ignores insertLineBreaks

-	//!   and maxLineLength because the web and URL safe specifications don't use them. They are present

-	//!   in the constructor for API compatibility with Base64Encoder (drop-in replacement). The

+	//! \details Base64URLEncoder() constructs a default encoder using a web safe alphabet. The constructor ignores

+	//!   insertLineBreaks and maxLineLength because the web and URL safe specifications don't use them. They are

+	//!   present in the constructor for API compatibility with Base64Encoder so it is a drop-in replacement. The

 	//!   constructor also disables padding on the encoder for the same reason.

 	//! \details If you need line breaks or padding, then you must use IsolatedInitialize() to set them

 	//!   after constructing a Base64URLEncoder.

-	//! \sa Base64Encoder(), and IsolatedInitialize() for an example of modifying a Base64URLEncoder after construction.

+	//! \sa Base64Encoder for an encoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize

+	//!   for an example of modifying an encoder after construction.

 	Base64URLEncoder(BufferedTransformation *attachment = NULL, bool insertLineBreaks = false, int maxLineLength = -1)

 		: SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment)

 	{

@@ -123,21 +123,22 @@ public:
 	//!   <pre>

 	//!     Base64URLEncoder encoder;

 	//!     AlgorithmParameters params = MakeParameters(Name::Pad(), true)(Name::InsertLineBreaks(), true);

-	//!     encoder.IsolatedInitialize(params);

-	//!   </pre>

-	//! \sa Base64Encoder(), and IsolatedInitialize() for an example of modifying a Base64URLEncoder after construction.

+	//!     encoder.IsolatedInitialize(params);</pre>

+	//! \sa Base64Encoder for an encoder that provides a classic alphabet.

 	void IsolatedInitialize(const NameValuePairs &parameters);

 };

 

 //! \class Base64URLDecoder

 //! \brief Base64 decodes data using a web safe alphabet

-//! \details Base64 decodes data using a web safe alphabet per RFC 4648 (http://tools.ietf.org/html/rfc4648#section-5)

+//! \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-5">RFC 4648, Base 64 Encoding

+//!   with URL and Filename Safe Alphabet</A>.

 class Base64URLDecoder : public BaseN_Decoder

 {

 public:

 	//! \brief Construct a Base64URLDecoder

 	//! \param attachment a BufferedTrasformation to attach to this object

-	//! \sa Base64Decoder(), and IsolatedInitialize() for an example of modifying a Base64Decoder() after construction.

+	//! \details Base64URLDecoder() constructs a default decoder using a web safe alphabet.

+	//! \sa Base64Decoder for a decoder that provides a classic alphabet.

 	Base64URLDecoder(BufferedTransformation *attachment = NULL)

 		: BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {}

     

@@ -146,7 +147,8 @@ public:
 	//! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable

 	//!   number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on

 	//!  attached transformations. If initialization should be propagated, then use the Initialize() function.

-	//! \sa Base64Decoder(), and IsolatedInitialize() for an example of modifying a Base64Decoder() after construction.

+	//! \sa Base64Decoder for a decoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize

+	//!   for an example of modifying an encoder after construction.

 	void IsolatedInitialize(const NameValuePairs &parameters);

     

 private:

diff --git a/cryptlib.h b/cryptlib.h
index 1c72b24a..191e6bb9 100644
--- a/cryptlib.h
+++ b/cryptlib.h
@@ -2579,6 +2579,7 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Verifier : public PK_SignatureScheme, p
 {

 public:

 	//! \brief Create a new HashTransformation to accumulate the message to be verified

+	//! \return a pointer to a PK_MessageAccumulator

 	//! \details NewVerificationAccumulator() can be used with all verification methods. Verify() will autimatically delete

 	//!   the accumulator pointer. The caller is responsible for deletion if a method is called that takes a reference.

 	virtual PK_MessageAccumulator * NewVerificationAccumulator() const =0;

@@ -2591,6 +2592,7 @@ public:
 

 	//! \brief Check whether messageAccumulator contains a valid signature and message

 	//! \param messageAccumulator a pointer to a PK_MessageAccumulator derived class

+	//! \return true if the signature is valid, false otherwise

 	//! \details Verify() deletes the messageAccumulator, even if an exception is thrown.

 	virtual bool Verify(PK_MessageAccumulator *messageAccumulator) const;

 

diff --git a/rng.h b/rng.h
index b10f69ea..4a070857 100644
--- a/rng.h
+++ b/rng.h
@@ -42,7 +42,8 @@ private:
 

 //! \class X917RNG

 //! \brief ANSI X9.17 RNG

-//! \details X917RNG is from ANSI X9.17 Appendix C.

+//! \details X917RNG is from ANSI X9.17 Appendix C, and it uses a 64-bit block cipher, like TripleDES.

+//!   If you use a 128-bit block cipher, like AES, then you are effectively using an ANSI X9.31 generator.

 //! \sa AutoSeededX917RNG, DefaultAutoSeededRNG

 class CRYPTOPP_DLL X917RNG : public RandomNumberGenerator, public NotCopyable

 {

@@ -54,15 +55,14 @@ public:
 	//! \details <tt>cipher</tt> will be deleted by the destructor. <tt>seed</tt> must be at least

 	//!   BlockSize() in length. <tt>deterministicTimeVector = 0</tt> means obtain time vector

 	//!   from the system.

-	//! \details When constructing an AutoSeededX917RNG, the generator must be keyed or an

-	//!   access violation will occur because the time vector is encrypted using the block cipher.

+	//! \details When constructing a X917RNG, the generator must be keyed or an access

+	//!   violation will occur because the time vector is encrypted using the block cipher.

 	//!   To key the generator during constructions, perform the following:

 	//! <pre>

 	//!   SecByteBlock key(AES::DEFAULT_KEYLENGTH), seed(AES::BLOCKSIZE);

 	//!   OS_GenerateRandomBlock(false, key, key.size());

 	//!   OS_GenerateRandomBlock(false, seed, seed.size());

-	//!   X917RNG prng(new AES::Encryption(key, AES::DEFAULT_KEYLENGTH), seed, NULL);

-	//! </pre>

+	//!   X917RNG prng(new AES::Encryption(key, AES::DEFAULT_KEYLENGTH), seed, NULL);</pre>

 	//! \sa AutoSeededX917RNG

 	X917RNG(BlockTransformation *cipher, const byte *seed, const byte *deterministicTimeVector = 0);