Botan  2.6.0
Crypto and TLS for C++11
dl_group.h
Go to the documentation of this file.
1 /*
2 * Discrete Logarithm Group
3 * (C) 1999-2008,2018 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7 
8 #ifndef BOTAN_DL_PARAM_H_
9 #define BOTAN_DL_PARAM_H_
10 
11 #include <botan/bigint.h>
12 
13 namespace Botan {
14 
15 class Montgomery_Params;
16 class DL_Group_Data;
17 
18 /**
19 * This class represents discrete logarithm groups. It holds a prime
20 * modulus p, a generator g, and (optionally) a prime q which is a
21 * factor of (p-1). In most cases g generates the order-q subgroup.
22 */
23 class BOTAN_PUBLIC_API(2,0) DL_Group final
24  {
25  public:
26  /**
27  * Determine the prime creation for DL groups.
28  */
29  enum PrimeType { Strong, Prime_Subgroup, DSA_Kosherizer };
30 
31  /**
32  * The DL group encoding format variants.
33  */
34  enum Format {
38 
39  DSA_PARAMETERS = ANSI_X9_57,
40  DH_PARAMETERS = ANSI_X9_42,
41  ANSI_X9_42_DH_PARAMETERS = ANSI_X9_42,
42  PKCS3_DH_PARAMETERS = PKCS_3
43  };
44 
45  /**
46  * Construct a DL group with uninitialized internal value.
47  * Use this constructor is you wish to set the groups values
48  * from a DER or PEM encoded group.
49  */
50  DL_Group() = default;
51 
52  /**
53  * Construct a DL group that is registered in the configuration.
54  * @param name the name that is configured in the global configuration
55  * for the desired group. If no configuration file is specified,
56  * the default values from the file policy.cpp will be used. For instance,
57  * use "modp/ietf/3072".
58  */
59  DL_Group(const std::string& name);
60 
61  /**
62  * Create a new group randomly.
63  * @param rng the random number generator to use
64  * @param type specifies how the creation of primes p and q shall
65  * be performed. If type=Strong, then p will be determined as a
66  * safe prime, and q will be chosen as (p-1)/2. If
67  * type=Prime_Subgroup and qbits = 0, then the size of q will be
68  * determined according to the estimated difficulty of the DL
69  * problem. If type=DSA_Kosherizer, DSA primes will be created.
70  * @param pbits the number of bits of p
71  * @param qbits the number of bits of q. Leave it as 0 to have
72  * the value determined according to pbits.
73  */
74  DL_Group(RandomNumberGenerator& rng, PrimeType type,
75  size_t pbits, size_t qbits = 0);
76 
77  /**
78  * Create a DSA group with a given seed.
79  * @param rng the random number generator to use
80  * @param seed the seed to use to create the random primes
81  * @param pbits the desired bit size of the prime p
82  * @param qbits the desired bit size of the prime q.
83  */
85  const std::vector<uint8_t>& seed,
86  size_t pbits = 1024, size_t qbits = 0);
87 
88  /**
89  * Create a DL group.
90  * @param p the prime p
91  * @param g the base g
92  */
93  DL_Group(const BigInt& p, const BigInt& g);
94 
95  /**
96  * Create a DL group.
97  * @param p the prime p
98  * @param q the prime q
99  * @param g the base g
100  */
101  DL_Group(const BigInt& p, const BigInt& q, const BigInt& g);
102 
103  /**
104  * Decode a BER-encoded DL group param
105  */
106  DL_Group(const uint8_t ber[], size_t ber_len, Format format);
107 
108  /**
109  * Decode a BER-encoded DL group param
110  */
111  template<typename Alloc>
112  DL_Group(const std::vector<uint8_t, Alloc>& ber, Format format) :
113  DL_Group(ber.data(), ber.size(), format) {}
114 
115  /**
116  * Get the prime p.
117  * @return prime p
118  */
119  const BigInt& get_p() const;
120 
121  /**
122  * Get the prime q, returns zero if q is not used
123  * @return prime q
124  */
125  const BigInt& get_q() const;
126 
127  /**
128  * Get the base g.
129  * @return base g
130  */
131  const BigInt& get_g() const;
132 
133  /**
134  * Perform validity checks on the group.
135  * @param rng the rng to use
136  * @param strong whether to perform stronger by lengthier tests
137  * @return true if the object is consistent, false otherwise
138  */
139  bool verify_group(RandomNumberGenerator& rng, bool strong = true) const;
140 
141  /**
142  * Verify a public element, ie check if y = g^x for some x.
143  *
144  * This is not a perfect test. It verifies that 1 < y < p and (if q is set)
145  * that y is in the subgroup of size q.
146  */
147  bool verify_public_element(const BigInt& y) const;
148 
149  /**
150  * Verify a pair of elements y = g^x
151  *
152  * This verifies that 1 < x,y < p and that y=g^x mod p
153  */
154  bool verify_element_pair(const BigInt& y, const BigInt& x) const;
155 
156  /**
157  * Encode this group into a string using PEM encoding.
158  * @param format the encoding format
159  * @return string holding the PEM encoded group
160  */
161  std::string PEM_encode(Format format) const;
162 
163  /**
164  * Encode this group into a string using DER encoding.
165  * @param format the encoding format
166  * @return string holding the DER encoded group
167  */
168  std::vector<uint8_t> DER_encode(Format format) const;
169 
170  /**
171  * Reduce an integer modulo p
172  * @return x % p
173  */
174  BigInt mod_p(const BigInt& x) const;
175 
176  /**
177  * Multiply and reduce an integer modulo p
178  * @return (x*y) % p
179  */
180  BigInt multiply_mod_p(const BigInt& x, const BigInt& y) const;
181 
182  BigInt inverse_mod_p(const BigInt& x) const;
183 
184  /**
185  * Modular exponentiation
186  * @return (g^x) % p
187  */
188  BigInt power_g_p(const BigInt& x) const;
189 
190  /**
191  * Multi-exponentiate
192  * Return (g^x * y^z) % p
193  */
194  BigInt multi_exponentiate(const BigInt& x, const BigInt& y, const BigInt& z) const;
195 
196  /**
197  * Return parameters for Montgomery reduction/exponentiation mod p
198  */
199  std::shared_ptr<const Montgomery_Params> monty_params_p() const;
200 
201  /**
202  * Return the size of p in bits
203  * Same as get_p().bits()
204  */
205  size_t p_bits() const;
206 
207  /**
208  * Return the size of p in bytes
209  * Same as get_p().bytes()
210  */
211  size_t p_bytes() const;
212 
213  /**
214  * Return size in bits of a secret exponent
215  *
216  * This attempts to balance between the attack costs of NFS
217  * (which depends on the size of the modulus) and Pollard's rho
218  * (which depends on the size of the exponent).
219  *
220  * It may vary over time for a particular group, if the attack
221  * costs change.
222  */
223  size_t exponent_bits() const;
224 
225  /**
226  * Return an estimate of the strength of this group against
227  * discrete logarithm attacks (eg NFS). Warning: since this only
228  * takes into account known attacks it is by necessity an
229  * overestimate of the actual strength.
230  */
231  size_t estimated_strength() const;
232 
233  /**
234  * Decode a DER/BER encoded group into this instance.
235  * @param ber a vector containing the DER/BER encoded group
236  * @param format the format of the encoded group
237  */
238  void BER_decode(const std::vector<uint8_t>& ber, Format format);
239 
240  /**
241  * Decode a PEM encoded group into this instance.
242  * @param pem the PEM encoding of the group
243  */
244  void PEM_decode(const std::string& pem);
245 
246  /**
247  * Return PEM representation of named DL group
248  */
249  static std::string BOTAN_DEPRECATED("Use DL_Group(name).PEM_encode()")
250  PEM_for_named_group(const std::string& name);
251 
252  /*
253  * For internal use only
254  */
255  static std::shared_ptr<DL_Group_Data> DL_group_info(const std::string& name);
256 
257  private:
258  static std::shared_ptr<DL_Group_Data> load_DL_group_info(const char* p_str,
259  const char* q_str,
260  const char* g_str);
261 
262  static std::shared_ptr<DL_Group_Data> load_DL_group_info(const char* p_str,
263  const char* g_str);
264 
265  static std::shared_ptr<DL_Group_Data>
266  BER_decode_DL_group(const uint8_t data[], size_t data_len, DL_Group::Format format);
267 
268  const DL_Group_Data& data() const;
269  std::shared_ptr<DL_Group_Data> m_data;
270  };
271 
272 }
273 
274 #endif
DL_Group(const std::vector< uint8_t, Alloc > &ber, Format format)
Definition: dl_group.h:112
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
Definition: bigint.h:719
MechanismType type
std::string PEM_encode(const Private_Key &key)
Definition: pkcs8.cpp:148
Definition: alg_id.cpp:13
PointGFp multi_exponentiate(const PointGFp &p1, const BigInt &z1, const PointGFp &p2, const BigInt &z2)
Definition: point_mul.cpp:14