Crypto++  5.6.3
Free C++ class library of cryptographic schemes
dh.h
Go to the documentation of this file.
1 // dh.h - written and placed in the public domain by Wei Dai
2 
3 //! \file dh.h
4 //! \brief Classes for Diffie-Hellman key exchange
5 
6 #ifndef CRYPTOPP_DH_H
7 #define CRYPTOPP_DH_H
8 
9 #include "cryptlib.h"
10 #include "gfpcrypt.h"
11 #include "algebra.h"
12 
13 NAMESPACE_BEGIN(CryptoPP)
14 
15 //! \class DH_Domain
16 //! \brief Diffie-Hellman domain
17 //! \tparam GROUP_PARAMETERS group parameters
18 //! \tparam COFACTOR_OPTION \ref CofactorMultiplicationOption "cofactor multiplication option"
19 //! \details A Diffie-Hellman domain is a set of parameters that must be shared
20 //! by two parties in a key agreement protocol, along with the algorithms
21 //! for generating key pairs and deriving agreed values.
22 template <class GROUP_PARAMETERS, class COFACTOR_OPTION = CPP_TYPENAME GROUP_PARAMETERS::DefaultCofactorOption>
23 class DH_Domain : public DL_SimpleKeyAgreementDomainBase<typename GROUP_PARAMETERS::Element>
24 {
26 
27 public:
28  typedef GROUP_PARAMETERS GroupParameters;
29  typedef typename GroupParameters::Element Element;
32 
33  //! \brief Construct a Diffie-Hellman domain
34  DH_Domain() {}
35 
36  //! \brief Construct a Diffie-Hellman domain
37  //! \param params group parameters and options
38  DH_Domain(const GroupParameters &params)
39  : m_groupParameters(params) {}
40 
41  //! \brief Construct a Diffie-Hellman domain
42  //! \param bt BufferedTransformation with group parameters and options
44  {m_groupParameters.BERDecode(bt);}
45 
46  //! \brief Construct a Diffie-Hellman domain
47  //! \tparam T2 template parameter used as a constructor parameter
48  //! \param v1 RandomNumberGenerator derived class
49  //! \param v2 second parameter
50  //! \details v1 and v2 are passed directly to the GROUP_PARAMETERS object.
51  template <class T2>
52  DH_Domain(RandomNumberGenerator &v1, const T2 &v2)
53  {m_groupParameters.Initialize(v1, v2);}
54 
55  //! \brief Construct a Diffie-Hellman domain
56  //! \tparam T2 template parameter used as a constructor parameter
57  //! \tparam T3 template parameter used as a constructor parameter
58  //! \param v1 RandomNumberGenerator derived class
59  //! \param v2 second parameter
60  //! \param v3 third parameter
61  //! \details v1, v2 and v3 are passed directly to the GROUP_PARAMETERS object.
62  template <class T2, class T3>
63  DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3)
64  {m_groupParameters.Initialize(v1, v2, v3);}
65 
66  //! \brief Construct a Diffie-Hellman domain
67  //! \tparam T2 template parameter used as a constructor parameter
68  //! \tparam T3 template parameter used as a constructor parameter
69  //! \tparam T4 template parameter used as a constructor parameter
70  //! \param v1 RandomNumberGenerator derived class
71  //! \param v2 second parameter
72  //! \param v3 third parameter
73  //! \param v4 fourth parameter
74  //! \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object.
75  template <class T2, class T3, class T4>
76  DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3, const T4 &v4)
77  {m_groupParameters.Initialize(v1, v2, v3, v4);}
78 
79  //! \brief Construct a Diffie-Hellman domain
80  //! \tparam T1 template parameter used as a constructor parameter
81  //! \tparam T2 template parameter used as a constructor parameter
82  //! \param v1 first parameter
83  //! \param v2 second parameter
84  //! \details v1 and v2 are passed directly to the GROUP_PARAMETERS object.
85  template <class T1, class T2>
86  DH_Domain(const T1 &v1, const T2 &v2)
87  {m_groupParameters.Initialize(v1, v2);}
88 
89  //! \brief Construct a Diffie-Hellman domain
90  //! \tparam T1 template parameter used as a constructor parameter
91  //! \tparam T2 template parameter used as a constructor parameter
92  //! \tparam T3 template parameter used as a constructor parameter
93  //! \param v1 first parameter
94  //! \param v2 second parameter
95  //! \param v3 third parameter
96  //! \details v1, v2 and v3 are passed directly to the GROUP_PARAMETERS object.
97  template <class T1, class T2, class T3>
98  DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3)
99  {m_groupParameters.Initialize(v1, v2, v3);}
100 
101  //! \brief Construct a Diffie-Hellman domain
102  //! \tparam T1 template parameter used as a constructor parameter
103  //! \tparam T2 template parameter used as a constructor parameter
104  //! \tparam T3 template parameter used as a constructor parameter
105  //! \tparam T4 template parameter used as a constructor parameter
106  //! \param v1 first parameter
107  //! \param v2 second parameter
108  //! \param v3 third parameter
109  //! \param v4 fourth parameter
110  //! \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object.
111  template <class T1, class T2, class T3, class T4>
112  DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3, const T4 &v4)
113  {m_groupParameters.Initialize(v1, v2, v3, v4);}
114 
115  //! \brief Retrieves the group parameters for this domain
116  //! \return the group parameters for this domain as a const reference
117  const GroupParameters & GetGroupParameters() const {return m_groupParameters;}
118  //! \brief Retrieves the group parameters for this domain
119  //! \return the group parameters for this domain as a non-const reference
120  GroupParameters & AccessGroupParameters() {return m_groupParameters;}
121 
122  //! \brief Generate a public key from a private key in this domain
123  //! \param rng RandomNumberGenerator derived class
124  //! \param privateKey byte buffer with the previously generated private key
125  //! \param publicKey byte buffer for the generated public key in this domain
126  //! \details If using a FIPS 140-2 validated library on Windows, then this class will perform
127  //! a self test to ensure the key pair is pairwise consistent. Non-FIPS and non-Windows
128  //! builds of the library do not provide FIPS validated cryptography, so the code should be
129  //! removed by the optimizer.
130  //! \pre <tt>COUNTOF(publicKey) == PublicKeyLength()</tt>
131  void GeneratePublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
132  {
133  Base::GeneratePublicKey(rng, privateKey, publicKey);
134 
136  {
137  SecByteBlock privateKey2(this->PrivateKeyLength());
138  this->GeneratePrivateKey(rng, privateKey2);
139 
140  SecByteBlock publicKey2(this->PublicKeyLength());
141  Base::GeneratePublicKey(rng, privateKey2, publicKey2);
142 
143  SecByteBlock agreedValue(this->AgreedValueLength()), agreedValue2(this->AgreedValueLength());
144  bool agreed1 = this->Agree(agreedValue, privateKey, publicKey2);
145  bool agreed2 = this->Agree(agreedValue2, privateKey2, publicKey);
146 
147  if (!agreed1 || !agreed2 || agreedValue != agreedValue2)
148  throw SelfTestFailure(this->AlgorithmName() + ": pairwise consistency test failed");
149  }
150  }
151 
152  static std::string CRYPTOPP_API StaticAlgorithmName()
153  {return GroupParameters::StaticAlgorithmNamePrefix() + DH_Algorithm::StaticAlgorithmName();}
154  std::string AlgorithmName() const {return StaticAlgorithmName();}
155 
156 #ifndef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562
157  virtual ~DH_Domain() {}
158 #endif
159 
160 private:
161  const DL_KeyAgreementAlgorithm<Element> & GetKeyAgreementAlgorithm() const
162  {return Singleton<DH_Algorithm>().Ref();}
163  DL_GroupParameters<Element> & AccessAbstractGroupParameters()
164  {return m_groupParameters;}
165 
166  GroupParameters m_groupParameters;
167 };
168 
169 CRYPTOPP_DLL_TEMPLATE_CLASS DH_Domain<DL_GroupParameters_GFP_DefaultSafePrime>;
170 
171 //! <a href="http://www.weidai.com/scan-mirror/ka.html#DH">Diffie-Hellman</a> in GF(p) with key validation
173 
174 NAMESPACE_END
175 
176 #endif
void GeneratePublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
Generate a public key from a private key in this domain.
Definition: dh.h:131
Restricts the instantiation of a class to one static object without locks.
Definition: misc.h:238
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition: dh.h:154
Interface for Discrete Log (DL) group parameters.
Definition: pubkey.h:748
DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3, const T4 &v4)
Construct a Diffie-Hellman domain.
Definition: dh.h:76
DH_Domain(BufferedTransformation &bt)
Construct a Diffie-Hellman domain.
Definition: dh.h:43
Abstract base classes that provide a uniform interface to this library.
Interface for random number generators.
Definition: cryptlib.h:1176
SecBlock typedef.
Definition: secblock.h:723
Classes for performing mathematics over different fields.
Interface for buffered transformations.
Definition: cryptlib.h:1342
DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3, const T4 &v4)
Construct a Diffie-Hellman domain.
Definition: dh.h:112
bool FIPS_140_2_ComplianceEnabled()
Determines whether the library provides FIPS validated cryptography.
Definition: fips140.cpp:29
DH_Domain(RandomNumberGenerator &v1, const T2 &v2)
Construct a Diffie-Hellman domain.
Definition: dh.h:52
Exception thrown when a crypto algorithm is used after a self test fails.
Definition: fips140.h:23
Implementation of schemes based on DL over GF(p)
DH_Domain(const T1 &v1, const T2 &v2, const T3 &v3)
Construct a Diffie-Hellman domain.
Definition: dh.h:98
Diffie-Hellman domain.
Definition: dh.h:23
DH_Domain(const GroupParameters &params)
Construct a Diffie-Hellman domain.
Definition: dh.h:38
DH_Domain< DL_GroupParameters_GFP_DefaultSafePrime > DH
Diffie-Hellman in GF(p) with key validation
Definition: dh.h:172
const GroupParameters & GetGroupParameters() const
Retrieves the group parameters for this domain.
Definition: dh.h:117
DH_Domain()
Construct a Diffie-Hellman domain.
Definition: dh.h:34
DH_Domain(RandomNumberGenerator &v1, const T2 &v2, const T3 &v3)
Construct a Diffie-Hellman domain.
Definition: dh.h:63
Crypto++ library namespace.
GroupParameters & AccessGroupParameters()
Retrieves the group parameters for this domain.
Definition: dh.h:120
Interface for DL key agreement algorithms.
Definition: pubkey.h:1292
DH_Domain(const T1 &v1, const T2 &v2)
Construct a Diffie-Hellman domain.
Definition: dh.h:86