From 2e6946381e1b412f6a8a8707a0290fc32aaf9892 Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Tue, 19 Jan 2016 13:05:54 -0500 Subject: [PATCH] Updated documentation --- cryptlib.h | 20 +++--- pubkey.h | 206 ++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 191 insertions(+), 35 deletions(-) diff --git a/cryptlib.h b/cryptlib.h index 191e6bb9..ab190f55 100644 --- a/cryptlib.h +++ b/cryptlib.h @@ -2036,9 +2036,9 @@ public: //!
  • 2 - ensure this object will function correctly, and perform reasonable security checks //!
  • 3 - perform reasonable security checks, and do checks that may take a long time //! - //! \details Level 0 does not require a RandomNumberGenerator. A NullRNG() can be used for level 0. - //! \details Level 1 may not check for weak keys and such. - //! \details Levels 2 and 3 are recommended. + //! \details Level 0 does not require a RandomNumberGenerator. A NullRNG() can be used for level 0. + //! Level 1 may not check for weak keys and such. Levels 2 and 3 are recommended. + //! \sa ThrowIfInvalid() virtual bool Validate(RandomNumberGenerator &rng, unsigned int level) const =0; //! \brief Check this object for errors @@ -2046,13 +2046,14 @@ public: //! \param level the level of thoroughness //! \throws InvalidMaterial //! \details Internally, ThrowIfInvalid() calls Validate() and throws InvalidMaterial() if validation fails. + //! \sa Validate() virtual void ThrowIfInvalid(RandomNumberGenerator &rng, unsigned int level) const {if (!Validate(rng, level)) throw InvalidMaterial("CryptoMaterial: this object contains invalid values");} //! \brief Saves a key to a BufferedTransformation //! \param bt the destination BufferedTransformation //! \throws NotImplemented - //! \details Save writes the material to a BufferedTransformation. + //! \details Save() writes the material to a BufferedTransformation. //! \details If the material is a key, then the key is written with ASN.1 DER encoding. The key //! includes an object identifier with an algorthm id, like a subjectPublicKeyInfo. //! \details A "raw" key without the "key info" can be saved using a key's DEREncode() method. @@ -2064,7 +2065,7 @@ public: //! \brief Loads a key from a BufferedTransformation //! \param bt the source BufferedTransformation //! \throws KeyingErr - //! \details Load attempts to read material from a BufferedTransformation. If the + //! \details Load() attempts to read material from a BufferedTransformation. If the //! material is a key that was generated outside the library, then the following //! usually applies: //! //! \details "key info" means the key should have an object identifier with an algorthm id, //! like a subjectPublicKeyInfo. - //! \details To read a "raw" key without the "key info", then call the key's BERDecode method. + //! \details To read a "raw" key without the "key info", then call the key's BERDecode() method. //! \note Load generally does not check that the key is valid. Call Validate(), if needed. virtual void Load(BufferedTransformation &bt) {CRYPTOPP_UNUSED(bt); throw NotImplemented("CryptoMaterial: this object does not support loading");} //! \brief Determines whether the object supports precomputation //! \return true if the object supports precomputation, false otherwise + //! \sa Precompute() virtual bool SupportsPrecomputation() const {return false;} //! \brief Perform precomputation @@ -2089,7 +2091,7 @@ public: //! a table of n objects that can be used later to speed up computation. //! \details If a derived class does not override Precompute(), then the base class throws //! NotImplemented. - //! \sa SupportsPrecomputation() + //! \sa SupportsPrecomputation(), LoadPrecomputation(), SavePrecomputation() virtual void Precompute(unsigned int precomputationStorage) { CRYPTOPP_UNUSED(precomputationStorage); assert(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation"); @@ -2098,13 +2100,13 @@ public: //! \brief Retrieve previously saved precomputation //! \param storedPrecomputation BufferedTransformation with the saved precomputation //! \throws NotImplemented - //! \sa SupportsPrecomputation() + //! \sa SupportsPrecomputation(), Precompute() virtual void LoadPrecomputation(BufferedTransformation &storedPrecomputation) {CRYPTOPP_UNUSED(storedPrecomputation); assert(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation");} //! \brief Save precomputation for later use //! \param storedPrecomputation BufferedTransformation to write the precomputation //! \throws NotImplemented - //! \sa SupportsPrecomputation() + //! \sa SupportsPrecomputation(), Precompute() virtual void SavePrecomputation(BufferedTransformation &storedPrecomputation) const {CRYPTOPP_UNUSED(storedPrecomputation); assert(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation");} diff --git a/pubkey.h b/pubkey.h index 8cdabe56..ad49085e 100644 --- a/pubkey.h +++ b/pubkey.h @@ -5,7 +5,7 @@ //! \file //! \brief This file contains helper classes/functions for implementing public key algorithms. -//! \details the class hierachies in this header file tend to look like this: +//! \details The class hierachies in this header file tend to look like this: //! //! 
     //!                   x1
@@ -251,7 +251,7 @@ protected:
 // ********************************************************
 
 //! \class PK_FixedLengthCryptoSystemImpl
-//! \brief Public key trapdoor function base class
+//! \brief Public key trapdoor function default implementation
 //! \tparam BASE public key cryptosystem with a fixed length
 template 
 class CRYPTOPP_NO_VTABLE PK_FixedLengthCryptoSystemImpl : public BASE
@@ -336,7 +336,7 @@ public:
 	virtual size_t MaxRecoverableLength(size_t representativeBitLength, size_t hashIdentifierLength, size_t digestLength) const
 		{CRYPTOPP_UNUSED(representativeBitLength); CRYPTOPP_UNUSED(representativeBitLength); CRYPTOPP_UNUSED(hashIdentifierLength); CRYPTOPP_UNUSED(digestLength); return 0;}
 
-	bool IsProbabilistic() const 
+	bool IsProbabilistic() const
 		{return true;}
 	bool AllowNonrecoverablePart() const
 		{throw NotImplemented("PK_MessageEncodingMethod: this signature scheme does not support message recovery");}
@@ -674,17 +674,37 @@ class TF_VerifierImpl : public TF_ObjectImpl
 class P1363_KDF2
 {
@@ -711,14 +733,17 @@ public:
 
 // ********************************************************
 
-//! to be thrown by DecodeElement and AgreeWithStaticPrivateKey
+//! \brief Exception thrown when an invalid group element is encountered
+//! \details Thrown by DecodeElement and AgreeWithStaticPrivateKey
 class DL_BadElement : public InvalidDataFormat
 {
 public:
 	DL_BadElement() : InvalidDataFormat("CryptoPP: invalid group element") {}
 };
 
-//! interface for DL group parameters
+//! \brief Interface for Discrete Log (DL) group parameters
+//! \tparam T element in the group
+//! \details The element can be an Integer, \ref ECP "ECP::Point" or \ref EC2N "EC2N::Point"
 template 
 class CRYPTOPP_NO_VTABLE DL_GroupParameters : public CryptoParameters
 {
@@ -772,13 +797,29 @@ public:
 		GetBasePrecomputation().Save(GetGroupPrecomputation(), storedPrecomputation);
 	}
 
-	// non-inherited
+	//! \brief Retrieves the subgroup generator
+	//! \return the subgroup generator
+	//! \details The subgroup generator is retrieved from the base precomputation
 	virtual const Element & GetSubgroupGenerator() const {return GetBasePrecomputation().GetBase(GetGroupPrecomputation());}
+
+	//! \brief Set the subgroup generator
+	//! \param base the new subgroup generator
+	//! \details The subgroup generator is set in the base precomputation
 	virtual void SetSubgroupGenerator(const Element &base) {AccessBasePrecomputation().SetBase(GetGroupPrecomputation(), base);}
+
+	//! \brief Retrieves the subgroup generator
+	//! \return the subgroup generator
+	//! \details The subgroup generator is retrieved from the base precomputation.
 	virtual Element ExponentiateBase(const Integer &exponent) const
 	{
 		return GetBasePrecomputation().Exponentiate(GetGroupPrecomputation(), exponent);
 	}
+
+	//! \brief Exponentiates an element
+	//! \param base the base elemenet
+	//! \param exponent the exponent to raise the base
+	//! \return the result of the exponentiation
+	//! \details Internally, ExponentiateElement() calls SimultaneousExponentiate().
 	virtual Element ExponentiateElement(const Element &base, const Integer &exponent) const
 	{
 		Element result;
@@ -786,21 +827,119 @@ public:
 		return result;
 	}
 
+	//! \brief Retrieves the group precomputation
+	//! \return a const reference to the precomputation
 	virtual const DL_GroupPrecomputation & GetGroupPrecomputation() const =0;
+
+	//! \brief Retrieves the group precomputation
+	//! \return a const reference to the precomputation using a fixed base
 	virtual const DL_FixedBasePrecomputation & GetBasePrecomputation() const =0;
+
+	//! \brief Retrieves the group precomputation
+	//! \return a non-const reference to the precomputation using a fixed base
 	virtual DL_FixedBasePrecomputation & AccessBasePrecomputation() =0;
-	virtual const Integer & GetSubgroupOrder() const =0;	// order of subgroup generated by base element
+
+	//! \brief Retrieves the subgroup order
+	//! \return the order of subgroup generated by the base element
+	virtual const Integer & GetSubgroupOrder() const =0;
+
+	//! \brief Retrieves the maximum exponent for the group
+	//! \return the maximum exponent for the group
 	virtual Integer GetMaxExponent() const =0;
-	virtual Integer GetGroupOrder() const {return GetSubgroupOrder()*GetCofactor();}	// one of these two needs to be overriden
+
+	//! \brief Retrieves the order of the group
+	//! \return the order of the group
+	//! \details Either GetGroupOrder() or GetCofactor() must be overriden in a derived class.
+	virtual Integer GetGroupOrder() const {return GetSubgroupOrder()*GetCofactor();}
+
+	//! \brief Retrieves the cofactor
+	//! \return the cofactor
+	//! \details Either GetGroupOrder() or GetCofactor() must be overriden in a derived class.
 	virtual Integer GetCofactor() const {return GetGroupOrder()/GetSubgroupOrder();}
+
+	//! \brief Retrieves the encoded element's size
+	//! \param reversible flag indicating the encoding format
+	//! \return encoded element's size, in bytes
+	//! \details The format of the encoded element varies by the underlyinhg type of the element and the
+	//!   reversible flag. GetEncodedElementSize() must be implemented in a derived class.
+	//! \sa GetEncodedElementSize(), EncodeElement(), DecodeElement()
 	virtual unsigned int GetEncodedElementSize(bool reversible) const =0;
+
+	//! \brief Encodes the element
+	//! \param reversible flag indicating the encoding format
+	//! \param element reference to the element to encode
+	//! \param encoded destination byte array for the encoded element
+	//! \details EncodeElement() must be implemented in a derived class.
+	//! \pre COUNTOF(encoded) == GetEncodedElementSize()
 	virtual void EncodeElement(bool reversible, const Element &element, byte *encoded) const =0;
+
+	//! \brief Decodes the element
+	//! \param encoded byte array with the encoded element
+	//! \param checkForGroupMembership flag indicating if the element should be validated
+	//! \return Element after decoding
+	//! \details DecodeElement() must be implemented in a derived class.
+	//! \pre COUNTOF(encoded) == GetEncodedElementSize()
 	virtual Element DecodeElement(const byte *encoded, bool checkForGroupMembership) const =0;
+
+	//! \brief Converts an element to an Integer
+	//! \param element the element to convert to an Integer
+	//! \return Element after converting to an Integer
+	//! \details ConvertElementToInteger() must be implemented in a derived class.
 	virtual Integer ConvertElementToInteger(const Element &element) const =0;
+
+	//! \brief Check the group for errors
+	//! \param rng RandomNumberGenerator for objects which use randomized testing
+	//! \param level level of thoroughness
+	//! \return true if the tests succeed, false otherwise
+	//! \details There are four levels of thoroughness:
+	//!   
      
+	//!   
    • 0 - using this object won't cause a crash or exception
+	//!   
    • 1 - this object will probably function, and encrypt, sign, other operations correctly
+	//!   
    • 2 - ensure this object will function correctly, and perform reasonable security checks
+	//!   
    • 3 - perform reasonable security checks, and do checks that may take a long time
+	//!   
    
+	//! \details Level 0 does not require a RandomNumberGenerator. A NullRNG() can be used for level 0.
+	//!   Level 1 may not check for weak keys and such. Levels 2 and 3 are recommended.
+	//! \details ValidateGroup() must be implemented in a derived class.
 	virtual bool ValidateGroup(RandomNumberGenerator &rng, unsigned int level) const =0;
+
+	//! \brief Check the element for errors
+	//! \param level level of thoroughness
+	//! \param element element to check
+	//! \param precomp optional pointer to DL_FixedBasePrecomputation
+	//! \return true if the tests succeed, false otherwise
+	//! \details There are four levels of thoroughness:
+	//!   
      
+	//!   
    • 0 - using this object won't cause a crash or exception
+	//!   
    • 1 - this object will probably function, and encrypt, sign, other operations correctly
+	//!   
    • 2 - ensure this object will function correctly, and perform reasonable security checks
+	//!   
    • 3 - perform reasonable security checks, and do checks that may take a long time
+	//!   
    
+	//! \details Level 0 performs group membership checks. Level 1 may not check for weak keys and such.
+	//!   Levels 2 and 3 are recommended.
+	//! \details ValidateElement() must be implemented in a derived class.
 	virtual bool ValidateElement(unsigned int level, const Element &element, const DL_FixedBasePrecomputation *precomp) const =0;
+
 	virtual bool FastSubgroupCheckAvailable() const =0;
+	
+	//! \brief Determines if an element is an identity
+	//! \param element element to check
+	//! \return true if the element is an identity, false otherwise
+	//! \details The identity element or or neutral element is a special element in a group that leaves
+	//!   other elements unchanged when combined with it.
+	//! \details IsIdentity() must be implemented in a derived class.
 	virtual bool IsIdentity(const Element &element) const =0;
+
+	//! \brief Exponentiates a base to multiple exponents
+	//! \param results an array of Elements
+	//! \param base the base to raise to the exponents
+	//! \param exponents an array of exponents
+	//! \param exponentsCount the number of exponents in the array
+	//! \details SimultaneousExponentiate() raises the base to each exponent in the exponents array and stores the
+	//!   result at the respective position in the results array.
+	//! \details SimultaneousExponentiate() must be implemented in a derived class.
+	//! \pre COUNTOF(results) == exponentsCount
+	//! \pre COUNTOF(exponents) == exponentsCount
 	virtual void SimultaneousExponentiate(Element *results, const Element &base, const Integer *exponents, unsigned int exponentsCount) const =0;
 
 #ifndef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562
@@ -845,7 +984,7 @@ public:
 	virtual DL_GroupParameters & AccessAbstractGroupParameters() =0;
 };
 
-//! interface for DL public keys
+//! \brief Interface for DL public keys
 template 
 class CRYPTOPP_NO_VTABLE DL_PublicKey : public DL_Key
 {
@@ -884,7 +1023,7 @@ public:
 #endif
 };
 
-//! interface for DL private keys
+//! \brief Interface for DL private keys
 template 
 class CRYPTOPP_NO_VTABLE DL_PrivateKey : public DL_Key
 {
@@ -1113,7 +1252,7 @@ private:
 	typename GP::BasePrecomputation m_ypc;
 };
 
-//! interface for Elgamal-like signature algorithms
+//! \brief Interface for Elgamal-like signature algorithms
 template 
 class CRYPTOPP_NO_VTABLE DL_ElgamalLikeSignatureAlgorithm
 {
@@ -1131,7 +1270,7 @@ public:
 		{return params.GetSubgroupOrder().ByteCount();}
 };
 
-//! interface for DL key agreement algorithms
+//! \brief Interface for DL key agreement algorithms
 template 
 class CRYPTOPP_NO_VTABLE DL_KeyAgreementAlgorithm
 {
@@ -1146,7 +1285,7 @@ public:
 #endif
 };
 
-//! interface for key derivation algorithms used in DL cryptosystems
+//! \brief Interface for key derivation algorithms used in DL cryptosystems
 template 
 class CRYPTOPP_NO_VTABLE DL_KeyDerivationAlgorithm
 {
@@ -1160,7 +1299,7 @@ public:
 #endif
 };
 
-//! interface for symmetric encryption algorithms used in DL cryptosystems
+//! \brief Interface for symmetric encryption algorithms used in DL cryptosystems
 class CRYPTOPP_NO_VTABLE DL_SymmetricEncryptionAlgorithm
 {
 public:
@@ -1703,12 +1842,27 @@ protected:
 	const DL_GroupParameters & GetAbstractGroupParameters() const {return const_cast *>(this)->AccessAbstractGroupParameters();}
 };
 
-enum CofactorMultiplicationOption {NO_COFACTOR_MULTIPLICTION, COMPATIBLE_COFACTOR_MULTIPLICTION, INCOMPATIBLE_COFACTOR_MULTIPLICTION};
+//! \brief Methods for avoiding "Small-Subgroup" attacks on Diffie-Hellman Key Agreement
+//! \details Additional methods exist and include public key validation and choice of prime p.
+//! \sa Methods for Avoiding the "Small-Subgroup" Attacks on the
+//!   Diffie-Hellman Key Agreement Method for S/MIME
+enum CofactorMultiplicationOption {
+	//! \brief No cofactor multiplication applied
+	NO_COFACTOR_MULTIPLICTION,
+	//! \brief Cofactor multiplication compatible with ordinary Diffie-Hellman
+	//! \details Modifies the computation of ZZ by including j (the cofactor) in the computations and is
+	//!   compatible with ordinary Diffie-Hellman.
+	COMPATIBLE_COFACTOR_MULTIPLICTION,
+	//! \brief Cofactor multiplication incompatible with ordinary Diffie-Hellman
+	//! \details Modifies the computation of ZZ by including j (the cofactor) in the computations but is
+	//!   not compatible with ordinary Diffie-Hellman.
+	INCOMPATIBLE_COFACTOR_MULTIPLICTION};
+
 typedef EnumToType NoCofactorMultiplication;
 typedef EnumToType CompatibleCofactorMultiplication;
 typedef EnumToType IncompatibleCofactorMultiplication;
 
-//! DH key agreement algorithm
+//! \details Diffie-Hellman key agreement algorithm
 template 
 class DL_KeyAgreementAlgorithm_DH : public DL_KeyAgreementAlgorithm
 {
@@ -1766,7 +1920,7 @@ public:
 
 // ********************************************************
 
-//! A template implementing constructors for public key algorithm classes
+//! \details Template implementing constructors for public key algorithm classes
 template 
 class CRYPTOPP_NO_VTABLE PK_FinalTemplate : public BASE
 {
@@ -1878,18 +2032,18 @@ public:
 
 //! \brief Base class for public key encryption standard classes.
 //! \details These classes are used to select from variants of algorithms.
-//! \note Not all standards apply to all algorithms.
+//!   Not all standards apply to all algorithms.
 struct EncryptionStandard {};
 
 //! \brief Base class for public key signature standard classes.
 //! \details These classes are used to select from variants of algorithms.
-//! \note Not all standards apply to all algorithms.
+//!   Not all standards apply to all algorithms.
 struct SignatureStandard {};
 
 template 
 class TF_ES;
 
-//! Trapdoor Function Based Encryption Scheme
+//! \brief Trapdoor Function Based Encryption Scheme
 template  >
 class TF_ES : public KEYS
 {
@@ -1911,7 +2065,7 @@ public:
 template 	// VC60 workaround: doesn't work if KEYS is first parameter
 class TF_SS;
 
-//! Trapdoor Function Based Signature Scheme
+//! \brief Trapdoor Function Based Signature Scheme
 template  >	// VC60 workaround: doesn't work if KEYS is first parameter
 class TF_SS : public KEYS
 {
@@ -1932,7 +2086,7 @@ public:
 template 
 class DL_SS;
 
-//! Discrete Log Based Signature Scheme
+//! \brief Discrete Log Based Signature Scheme
 template  >
 class DL_SS : public KEYS
 {
@@ -1947,7 +2101,7 @@ public:
 	typedef PK_FinalTemplate > Verifier;
 };
 
-//! Discrete Log Based Encryption Scheme
+//! \brief Discrete Log Based Encryption Scheme
 template 
 class DL_ES : public KEYS
 {