dh.h
Go to the documentation of this file.
// dh.h - originally written and placed in the public domain by Wei Dai
/// \file dh.h
/// \brief Classes for Diffie-Hellman key exchange
#ifndef CRYPTOPP_DH_H
#define CRYPTOPP_DH_H
#include "cryptlib.h"
#include "gfpcrypt.h"
#include "algebra.h"
NAMESPACE_BEGIN(CryptoPP)
/// \brief Diffie-Hellman domain
/// \tparam GROUP_PARAMETERS group parameters
/// \tparam COFACTOR_OPTION cofactor multiplication option
/// \details A Diffie-Hellman domain is a set of parameters that must be shared
/// by two parties in a key agreement protocol, along with the algorithms
/// for generating key pairs and deriving agreed values.
/// \details For COFACTOR_OPTION, see CofactorMultiplicationOption.
/// \sa DL_SimpleKeyAgreementDomainBase
/// \since Crypto++ 1.0
template <class GROUP_PARAMETERS, class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption>
class DH_Domain : public DL_SimpleKeyAgreementDomainBase<typename GROUP_PARAMETERS::Element>
{
typedef DL_SimpleKeyAgreementDomainBase<typename GROUP_PARAMETERS::Element> Base;
public:
typedef GROUP_PARAMETERS GroupParameters;
typedef typename GroupParameters::Element Element;
typedef DL_KeyAgreementAlgorithm_DH<Element, COFACTOR_OPTION> DH_Algorithm;
typedef DH_Domain<GROUP_PARAMETERS, COFACTOR_OPTION> Domain;
virtual ~DH_Domain() {}
/// \brief Construct a Diffie-Hellman domain
DH_Domain() {}
/// \brief Construct a Diffie-Hellman domain
/// \param params group parameters and options
DH_Domain(const GroupParameters &params)
: m_groupParameters(params) {}
/// \brief Construct a Diffie-Hellman domain
/// \param bt BufferedTransformation with group parameters and options
DH_Domain(BufferedTransformation &bt)
{m_groupParameters.BERDecode(bt);}
/// \brief Create a Diffie-Hellman domain
/// \tparam T2 template parameter used as a constructor parameter
/// \param v1 RandomNumberGenerator derived class
/// \param v2 second parameter
/// \details v1 and v2 are passed directly to the GROUP_PARAMETERS object.
template <class T2>
DH_Domain(RandomNumberGenerator &v1, const T2 &v2)
{m_groupParameters.Initialize(v1, v2);}
/// \brief Create a Diffie-Hellman domain
/// \tparam T2 template parameter used as a constructor parameter
/// \tparam T3 template parameter used as a constructor parameter
/// \param v1 RandomNumberGenerator derived class
/// \param v2 second parameter
/// \param v3 third parameter
/// \details v1, v2 and v3 are passed directly to the GROUP_PARAMETERS object.
template <class T2, class T3>
DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3)
{m_groupParameters.Initialize(v1, v2, v3);}
/// \brief Create a Diffie-Hellman domain
/// \tparam T2 template parameter used as a constructor parameter
/// \tparam T3 template parameter used as a constructor parameter
/// \tparam T4 template parameter used as a constructor parameter
/// \param v1 RandomNumberGenerator derived class
/// \param v2 second parameter
/// \param v3 third parameter
/// \param v4 fourth parameter
/// \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object.
template <class T2, class T3, class T4>
DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3, const T4 &v4)
{m_groupParameters.Initialize(v1, v2, v3, v4);}
/// \brief Construct a Diffie-Hellman domain
/// \tparam T1 template parameter used as a constructor parameter
/// \tparam T2 template parameter used as a constructor parameter
/// \param v1 first parameter
/// \param v2 second parameter
/// \details v1 and v2 are passed directly to the GROUP_PARAMETERS object.
template <class T1, class T2>
DH_Domain(const T1 &v1, const T2 &v2)
{m_groupParameters.Initialize(v1, v2);}
/// \brief Construct a Diffie-Hellman domain
/// \tparam T1 template parameter used as a constructor parameter
/// \tparam T2 template parameter used as a constructor parameter
/// \tparam T3 template parameter used as a constructor parameter
/// \param v1 first parameter
/// \param v2 second parameter
/// \param v3 third parameter
/// \details v1, v2 and v3 are passed directly to the GROUP_PARAMETERS object.
template <class T1, class T2, class T3>
DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3)
{m_groupParameters.Initialize(v1, v2, v3);}
/// \brief Construct a Diffie-Hellman domain
/// \tparam T1 template parameter used as a constructor parameter
/// \tparam T2 template parameter used as a constructor parameter
/// \tparam T3 template parameter used as a constructor parameter
/// \tparam T4 template parameter used as a constructor parameter
/// \param v1 first parameter
/// \param v2 second parameter
/// \param v3 third parameter
/// \param v4 fourth parameter
/// \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object.
template <class T1, class T2, class T3, class T4>
DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3, const T4 &v4)
{m_groupParameters.Initialize(v1, v2, v3, v4);}
/// \brief Retrieves the group parameters for this domain
/// \return the group parameters for this domain as a const reference
const GroupParameters & GetGroupParameters() const {return m_groupParameters;}
/// \brief Retrieves the group parameters for this domain
/// \return the group parameters for this domain as a non-const reference
GroupParameters & AccessGroupParameters() {return m_groupParameters;}
/// \brief Generate a public key from a private key in this domain
/// \param rng RandomNumberGenerator derived class
/// \param privateKey byte buffer with the previously generated private key
/// \param publicKey byte buffer for the generated public key in this domain
/// \details If using a FIPS 140-2 validated library on Windows, then this class will perform
/// a self test to ensure the key pair is pairwise consistent. Non-FIPS and non-Windows
/// builds of the library do not provide FIPS validated cryptography, so the code should be
/// removed by the optimizer.
/// \pre <tt>COUNTOF(publicKey) == PublicKeyLength()</tt>
void GeneratePublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
{
Base::GeneratePublicKey(rng, privateKey, publicKey);
if (FIPS_140_2_ComplianceEnabled())
{
SecByteBlock privateKey2(this->PrivateKeyLength());
this->GeneratePrivateKey(rng, privateKey2);
SecByteBlock publicKey2(this->PublicKeyLength());
Base::GeneratePublicKey(rng, privateKey2, publicKey2);
SecByteBlock agreedValue(this->AgreedValueLength()), agreedValue2(this->AgreedValueLength());
bool agreed1 = this->Agree(agreedValue, privateKey, publicKey2);
bool agreed2 = this->Agree(agreedValue2, privateKey2, publicKey);
if (!agreed1 || !agreed2 || agreedValue != agreedValue2)
throw SelfTestFailure(this->AlgorithmName() + ": pairwise consistency test failed");
}
}
static std::string CRYPTOPP_API StaticAlgorithmName()
{return GroupParameters::StaticAlgorithmNamePrefix() + DH_Algorithm::StaticAlgorithmName();}
std::string AlgorithmName() const {return StaticAlgorithmName();}
private:
const DL_KeyAgreementAlgorithm<Element> & GetKeyAgreementAlgorithm() const
{return Singleton<DH_Algorithm>().Ref();}
DL_GroupParameters<Element> & AccessAbstractGroupParameters()
{return m_groupParameters;}
GroupParameters m_groupParameters;
};
CRYPTOPP_DLL_TEMPLATE_CLASS DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime>;
/// \brief Diffie-Hellman in GF(p)
/// \details DH() class is a typedef of DH_Domain(). The documentation that follows
/// does not exist. Rather the documentation was created in response to <a href="https://github.com/weidai11/cryptopp/issues/328">Issue
/// 328, Diffie-Hellman example code not compiling</a>.
/// \details Generally speaking, a DH() object is ephemeral and is intended to execute one instance of the Diffie-Hellman protocol. The
/// private and public key parts are not intended to be set or persisted. Rather, a new set of domain parameters are generated each
/// time an object is created.
/// \details Once a DH() object is created, once can retrieve the ephemeral public key for the other party with code similar to the
/// following.
/// <pre> AutoSeededRandomPool prng;
/// Integer p, q, g;
/// PrimeAndGenerator pg;
///
/// pg.Generate(1, prng, 512, 511);
/// p = pg.Prime();
/// q = pg.SubPrime();
/// g = pg.Generator();
///
/// DH dh(p, q, g);
/// SecByteBlock t1(dh.PrivateKeyLength()), t2(dh.PublicKeyLength());
/// dh.GenerateKeyPair(prng, t1, t2);
/// Integer k1(t1, t1.size()), k2(t2, t2.size());
///
/// cout << "Private key:\n";
/// cout << hex << k1 << endl;
///
/// cout << "Public key:\n";
/// cout << hex << k2 << endl;</pre>
///
/// \details Output of the program above will be similar to the following.
/// <pre> $ ./cryptest.exe
/// Private key:
/// 72b45a42371545e9d4880f48589aefh
/// Public key:
/// 45fdb13f97b1840626f0250cec1dba4a23b894100b51fb5d2dd13693d789948f8bfc88f9200014b2
/// ba8dd8a6debc471c69ef1e2326c61184a2eca88ec866346bh</pre>
/// \sa <a href="http://www.cryptopp.com/wiki/Diffie-Hellman">Diffie-Hellman on the Crypto++ wiki</a> and
/// <a href="http://www.weidai.com/scan-mirror/ka.html#DH">Diffie-Hellman</a> in GF(p) with key validation
/// \since Crypto++ 1.0
#if defined(CRYPTOPP_DOXYGEN_PROCESSING)
struct DH : public DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime>
{
typedef DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime> GroupParameters;
typedef GroupParameters::Element Element;
virtual ~DH() {}
/// \brief Create an uninitialized Diffie-Hellman object
DH() : DH_Domain() {}
/// \brief Initialize a Diffie-Hellman object
/// \param bt BufferedTransformation with group parameters and options
DH(BufferedTransformation &bt) : DH_Domain(bt) {}
/// \brief Initialize a Diffie-Hellman object
/// \param params group parameters and options
DH(const GroupParameters &params) : DH_Domain(params) {}
/// \brief Create a Diffie-Hellman object
/// \param rng a RandomNumberGenerator derived class
/// \param modulusBits the size of the modulus, in bits
/// \details This function overload of Initialize() creates a new Diffie-Hellman object because it
/// takes a RandomNumberGenerator() as a parameter.
DH(RandomNumberGenerator &rng, unsigned int modulusBits) : DH_Domain(rng, modulusBits) {}
/// \brief Initialize a Diffie-Hellman object
/// \param p the modulus
/// \param g the generator
DH(const Integer &p, const Integer &g) : DH_Domain(p, g) {}
/// \brief Initialize a Diffie-Hellman object
/// \param p the modulus
/// \param q the subgroup order
/// \param g the generator
DH(const Integer &p, const Integer &q, const Integer &g) : DH_Domain(p, q, g) {}
/// \brief Creates a Diffie-Hellman object
/// \param rng a RandomNumberGenerator derived class
/// \param modulusBits the size of the modulus, in bits
/// \details This function overload of Initialize() creates a new Diffie-Hellman object because it
/// takes a RandomNumberGenerator() as a parameter.
void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits)
{AccessGroupParameters().Initialize(rng, modulusBits);}
/// \brief Initialize a Diffie-Hellman object
/// \param p the modulus
/// \param g the generator
void Initialize(const Integer &p, const Integer &g)
{AccessGroupParameters().Initialize(p, g);}
/// \brief Initialize a Diffie-Hellman object
/// \param p the modulus
/// \param q the subgroup order
/// \param g the generator
void Initialize(const Integer &p, const Integer &q, const Integer &g)
{AccessGroupParameters().Initialize(p, q, g);}
};
#else
// The real DH class is a typedef.
typedef DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime> DH;
#endif
NAMESPACE_END
#endif
algebra.h
Classes for performing mathematics over different fields.
BufferedTransformation
Interface for buffered transformations.
Definition cryptlib.h:1657
DH_Domain
Diffie-Hellman domain.
Definition dh.h:26
DH_Domain::GetGroupParameters
const GroupParameters & GetGroupParameters() const
Retrieves the group parameters for this domain.
Definition dh.h:121
DH_Domain::DH_Domain
DH_Domain(BufferedTransformation &bt)
Construct a Diffie-Hellman domain.
Definition dh.h:47
DH_Domain::DH_Domain
DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3)
Create a Diffie-Hellman domain.
Definition dh.h:67
DH_Domain::AlgorithmName
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition dh.h:158
DH_Domain::DH_Domain
DH_Domain(const GroupParameters &params)
Construct a Diffie-Hellman domain.
Definition dh.h:42
DH_Domain::DH_Domain
DH_Domain(RandomNumberGenerator &v1, const T2 &v2)
Create a Diffie-Hellman domain.
Definition dh.h:56
DH_Domain::DH_Domain
DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3, const T4 &v4)
Create a Diffie-Hellman domain.
Definition dh.h:80
DH_Domain::GeneratePublicKey
void GeneratePublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
Generate a public key from a private key in this domain.
Definition dh.h:135
DH_Domain::DH_Domain
DH_Domain()
Construct a Diffie-Hellman domain.
Definition dh.h:38
DH_Domain::DH_Domain
DH_Domain(const T1 &v1, const T2 &v2)
Construct a Diffie-Hellman domain.
Definition dh.h:90
DH_Domain::AccessGroupParameters
GroupParameters & AccessGroupParameters()
Retrieves the group parameters for this domain.
Definition dh.h:124
DH_Domain::DH_Domain
DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3, const T4 &v4)
Construct a Diffie-Hellman domain.
Definition dh.h:116
DH_Domain::DH_Domain
DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3)
Construct a Diffie-Hellman domain.
Definition dh.h:102
DL_GroupParameters
Interface for Discrete Log (DL) group parameters.
Definition pubkey.h:782
DL_KeyAgreementAlgorithm_DH
Diffie-Hellman key agreement algorithm.
Definition pubkey.h:2142
DL_KeyAgreementAlgorithm
Interface for DL key agreement algorithms.
Definition pubkey.h:1477
DL_SimpleKeyAgreementDomainBase
Discrete Log (DL) simple key agreement base implementation.
Definition pubkey.h:2064
DL_SimpleKeyAgreementDomainBase< GROUP_PARAMETERS::Element >::AgreedValueLength
unsigned int AgreedValueLength() const
Definition pubkey.h:2071
DL_SimpleKeyAgreementDomainBase< GROUP_PARAMETERS::Element >::Agree
bool Agree(byte *agreedValue, const byte *privateKey, const byte *otherPublicKey, bool validateOtherPublicKey=true) const
Definition pubkey.h:2090
DL_SimpleKeyAgreementDomainBase< GROUP_PARAMETERS::Element >::GeneratePrivateKey
void GeneratePrivateKey(RandomNumberGenerator &rng, byte *privateKey) const
Definition pubkey.h:2075
DL_SimpleKeyAgreementDomainBase::GeneratePublicKey
void GeneratePublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
Generate a public key from a private key in this domain.
Definition pubkey.h:2081
DL_SimpleKeyAgreementDomainBase< GROUP_PARAMETERS::Element >::PrivateKeyLength
unsigned int PrivateKeyLength() const
Definition pubkey.h:2072
DL_SimpleKeyAgreementDomainBase< GROUP_PARAMETERS::Element >::PublicKeyLength
unsigned int PublicKeyLength() const
Definition pubkey.h:2073
Integer
Multiple precision integer with arithmetic operations.
Definition integer.h:50
RandomNumberGenerator
Interface for random number generators.
Definition cryptlib.h:1440
SecByteBlock
SecBlock<byte> typedef.
Definition secblock.h:1226
SelfTestFailure
Exception thrown when a crypto algorithm is used after a self test fails.
Definition fips140.h:23
Singleton
Restricts the instantiation of a class to one static object without locks.
Definition misc.h:309
Singleton::Ref
const T & Ref(...) const
Return a reference to the inner Singleton object.
Definition misc.h:329
CRYPTOPP_API
#define CRYPTOPP_API
Win32 calling convention.
Definition config_dll.h:119
CRYPTOPP_DLL_TEMPLATE_CLASS
#define CRYPTOPP_DLL_TEMPLATE_CLASS
Instantiate templates in a dynamic library.
Definition config_dll.h:72
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
FIPS_140_2_ComplianceEnabled
CRYPTOPP_DLL bool FIPS_140_2_ComplianceEnabled()
Determines whether the library provides FIPS validated cryptography.
gfpcrypt.h
Classes and functions for schemes based on Discrete Logs (DL) over GF(p)
CryptoPP
Crypto++ library namespace.
DH
Diffie-Hellman in GF(p)
Definition dh.h:212
DH::DH
DH(BufferedTransformation &bt)
Initialize a Diffie-Hellman object.
Definition dh.h:223
DH::DH
DH(const Integer &p, const Integer &g)
Initialize a Diffie-Hellman object.
Definition dh.h:239
DH::DH
DH()
Create an uninitialized Diffie-Hellman object.
Definition dh.h:219
DH::DH
DH(RandomNumberGenerator &rng, unsigned int modulusBits)
Create a Diffie-Hellman object.
Definition dh.h:234
DH::DH
DH(const GroupParameters &params)
Initialize a Diffie-Hellman object.
Definition dh.h:227
DH::Initialize
void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits)
Creates a Diffie-Hellman object.
Definition dh.h:252
DH::Initialize
void Initialize(const Integer &p, const Integer &q, const Integer &g)
Initialize a Diffie-Hellman object.
Definition dh.h:265
DH::Initialize
void Initialize(const Integer &p, const Integer &g)
Initialize a Diffie-Hellman object.
Definition dh.h:258
DH::DH
DH(const Integer &p, const Integer &q, const Integer &g)
Initialize a Diffie-Hellman object.
Definition dh.h:245