From 7cc8ad1a1d6b9fdfea6ac3695ac50f45150ce05e Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Sat, 3 Dec 2016 14:46:52 -0500 Subject: [PATCH] Updated documentation (Issue 328) --- eccrypto.h | 14 ++++++++++++++ esign.h | 8 +++++++- gfpcrypt.h | 31 +++++++++++++++++++++++++++++++ luc.h | 8 ++++++++ rabin.h | 24 +++++++++++++++++++----- rsa.h | 7 ++++++- rw.h | 19 +++++++++++++------ 7 files changed, 98 insertions(+), 13 deletions(-) diff --git a/eccrypto.h b/eccrypto.h index a20a9647..8a4aa420 100644 --- a/eccrypto.h +++ b/eccrypto.h @@ -181,8 +181,22 @@ public: {this->AccessGroupParameters() = params; this->SetPrivateExponent(x);} void Initialize(const EC &ec, const Element &G, const Integer &n, const Integer &x) {this->AccessGroupParameters().Initialize(ec, G, n); this->SetPrivateExponent(x);} + //! \brief Create an EC private key + //! \param rng a RandomNumberGenerator derived class + //! \param params the EC group parameters + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const DL_GroupParameters_EC ¶ms) {this->GenerateRandom(rng, params);} + //! \brief Create an EC private key + //! \param rng a RandomNumberGenerator derived class + //! \param ec the elliptic curve + //! \param G the base point + //! \param n the cofactor + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const EC &ec, const Element &G, const Integer &n) {this->GenerateRandom(rng, DL_GroupParameters_EC(ec, G, n));} diff --git a/esign.h b/esign.h index fa6bd2f4..c76129fd 100644 --- a/esign.h +++ b/esign.h @@ -64,7 +64,13 @@ class InvertibleESIGNFunction : public ESIGNFunction, public RandomizedTrapdoorF public: void Initialize(const Integer &n, const Integer &e, const Integer &p, const Integer &q) {m_n = n; m_e = e; m_p = p; m_q = q;} - // generate a random private key + + //! \brief Create a RSA private key + //! \param rng a RandomNumberGenerator derived class + //! \param modulusBits the size of the modulud, in bits + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits) {GenerateRandomWithKeySize(rng, modulusBits);} diff --git a/gfpcrypt.h b/gfpcrypt.h index 4e4b38b7..da09eebe 100644 --- a/gfpcrypt.h +++ b/gfpcrypt.h @@ -39,6 +39,12 @@ public: void Initialize(const DL_GroupParameters_IntegerBased ¶ms) {Initialize(params.GetModulus(), params.GetSubgroupOrder(), params.GetSubgroupGenerator());} + //! \brief Create a trapdoor function keypair + //! \param rng a RandomNumberGenerator derived class + //! \param pbits the size of p, in bits + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int pbits) {GenerateRandom(rng, MakeParameters("ModulusSize", (int)pbits));} void Initialize(const Integer &p, const Integer &g) @@ -271,14 +277,39 @@ class DL_PrivateKey_GFP : public DL_PrivateKeyImpl public: virtual ~DL_PrivateKey_GFP() {} + //! \brief Create a private key + //! \param rng a RandomNumberGenerator derived class + //! \param modulusBits the size of the modulus, in bits + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits) {this->GenerateRandomWithKeySize(rng, modulusBits);} + + //! \brief Create a private key + //! \param rng a RandomNumberGenerator derived class + //! \param p TODO + //! \param g TODO + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const Integer &p, const Integer &g) {this->GenerateRandom(rng, MakeParameters("Modulus", p)("SubgroupGenerator", g));} + + //! \brief Create a private key + //! \param rng a RandomNumberGenerator derived class + //! \param p TODO + //! \param q TODO + //! \param g TODO + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const Integer &p, const Integer &q, const Integer &g) {this->GenerateRandom(rng, MakeParameters("Modulus", p)("SubgroupOrder", q)("SubgroupGenerator", g));} + void Initialize(const DL_GroupParameters_IntegerBased ¶ms, const Integer &x) {this->AccessGroupParameters().Initialize(params); this->SetPrivateExponent(x);} + void Initialize(const Integer &p, const Integer &g, const Integer &x) {this->AccessGroupParameters().Initialize(p, g); this->SetPrivateExponent(x);} void Initialize(const Integer &p, const Integer &q, const Integer &g, const Integer &x) diff --git a/luc.h b/luc.h index ea16a44a..5d114274 100644 --- a/luc.h +++ b/luc.h @@ -76,6 +76,14 @@ class InvertibleLUCFunction : public LUCFunction, public TrapdoorFunctionInverse public: virtual ~InvertibleLUCFunction() {} + //! \brief Create a LUC private key + //! \param rng a RandomNumberGenerator derived class + //! \param modulusBits the size of the modulus, in bits + //! \param eStart the desired starting public exponent + //! \details Initialize() creates a new keypair using a starting public exponent of 17. + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits, const Integer &eStart=17); void Initialize(const Integer &n, const Integer &e, const Integer &p, const Integer &q, const Integer &u) {m_n = n; m_e = e; m_p = p; m_q = q; m_u = u;} diff --git a/rabin.h b/rabin.h index 799676d6..41cc6780 100644 --- a/rabin.h +++ b/rabin.h @@ -13,7 +13,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! _ +//! \class RabinFunction +//! \brief Rabin trapdoor function using the public key +//! \since Crypto++ 2.0 class RabinFunction : public TrapdoorFunction, public PublicKey { typedef RabinFunction ThisClass; @@ -45,7 +47,9 @@ protected: Integer m_n, m_r, m_s; }; -//! _ +//! \class InvertibleRabinFunction +//! \brief Rabin trapdoor function using the private key +//! \since Crypto++ 2.0 class InvertibleRabinFunction : public RabinFunction, public TrapdoorFunctionInverse, public PrivateKey { typedef InvertibleRabinFunction ThisClass; @@ -54,6 +58,13 @@ public: void Initialize(const Integer &n, const Integer &r, const Integer &s, const Integer &p, const Integer &q, const Integer &u) {m_n = n; m_r = r; m_s = s; m_p = p; m_q = q; m_u = u;} + + //! \brief Create a Rabin private key + //! \param rng a RandomNumberGenerator derived class + //! \param keybits the size of the key, in bits + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int keybits) {GenerateRandomWithKeySize(rng, keybits);} @@ -80,7 +91,7 @@ protected: Integer m_p, m_q, m_u; }; -//! Rabin +//! \brief Rabin keys struct Rabin { static std::string StaticAlgorithmName() {return "Rabin-Crypto++Variant";} @@ -88,13 +99,16 @@ struct Rabin typedef InvertibleRabinFunction PrivateKey; }; -//! Rabin encryption +//! \brief Rabin encryption scheme +//! \tparam STANDARD encryption standard template struct RabinES : public TF_ES { }; -//! Rabin signature +//! \brief Rabin signature scheme +//! \tparam STANDARD signature standard +//! \tparam H hash transformation template struct RabinSS : public TF_SS { diff --git a/rsa.h b/rsa.h index eacb97c4..972fea2b 100644 --- a/rsa.h +++ b/rsa.h @@ -68,8 +68,12 @@ class CRYPTOPP_DLL InvertibleRSAFunction : public RSAFunction, public TrapdoorFu public: //! \brief Create a RSA private key //! \param rng a RandomNumberGenerator derived class - //! \param modulusBits the size of the modulud, in bits + //! \param modulusBits the size of the modulus, in bits //! \param e the desired public exponent + //! \details Initialize() creates a new keypair using a public exponent of 17. + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits, const Integer &e = 17); //! \brief Initialize a RSA private key with {n,e,d,p,q,dp,dq,u} @@ -83,6 +87,7 @@ public: //! \param u q-1 mod p void Initialize(const Integer &n, const Integer &e, const Integer &d, const Integer &p, const Integer &q, const Integer &dp, const Integer &dq, const Integer &u) {m_n = n; m_e = e; m_d = d; m_p = p; m_q = q; m_dp = dp; m_dq = dq; m_u = u;} + //! \brief Initialize a RSA private key with {n,e,d} //! \param n modulus //! \param e public exponent diff --git a/rw.h b/rw.h index 1a70736c..9a890297 100644 --- a/rw.h +++ b/rw.h @@ -19,6 +19,7 @@ NAMESPACE_BEGIN(CryptoPP) //! \class RWFunction //! \brief Rabin-Williams trapdoor function using the public key +//! \since Crypto++ 2.0, Tweaked roots using e and f since Crypto++ 5.6.4 class CRYPTOPP_DLL RWFunction : public TrapdoorFunction, public PublicKey { typedef RWFunction ThisClass; @@ -52,7 +53,7 @@ protected: //! \class InvertibleRWFunction //! \brief Rabin-Williams trapdoor function using the private key -//! \since Tweaked roots using e and f since Crypto++ 5.6.4 +//! \since Crypto++ 2.0, Tweaked roots using e and f since Crypto++ 5.6.4 class CRYPTOPP_DLL InvertibleRWFunction : public RWFunction, public TrapdoorFunctionInverse, public PrivateKey { typedef InvertibleRWFunction ThisClass; @@ -61,7 +62,13 @@ public: InvertibleRWFunction() : m_precompute(false) {} void Initialize(const Integer &n, const Integer &p, const Integer &q, const Integer &u); - // generate a random private key + + //! \brief Create a Rabin-Williams private key + //! \param rng a RandomNumberGenerator derived class + //! \param modulusBits the size of the modulus, in bits + //! \details This function overload of Initialize() creates a new keypair because it + //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + //! then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits) {GenerateRandomWithKeySize(rng, modulusBits);} @@ -107,17 +114,17 @@ protected: mutable bool m_precompute; }; -//! \class RW -//! \brief Rabin-Williams algorithm +//! \brief Rabin-Williams keys struct RW { - static std::string StaticAlgorithmName() {return "RW";} + CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RW";} typedef RWFunction PublicKey; typedef InvertibleRWFunction PrivateKey; }; -//! \class RWSS //! \brief Rabin-Williams signature scheme +//! \tparam STANDARD signature standard +//! \tparam H hash transformation template struct RWSS : public TF_SS {