Botan 1.10.17

Public Types | Public Member Functions | List of all members
Botan::DL_Group Class Reference

`#include <dl_group.h>`

## Public Types
enum | Format { ANSI_X9_42, ANSI_X9_57, PKCS_3, DSA_PARAMETERS = ANSI_X9_57, DH_PARAMETERS = ANSI_X9_42, X942_DH_PARAMETERS = ANSI_X9_42, PKCS3_DH_PARAMETERS = PKCS_3 }
enum | PrimeType { Strong, Prime_Subgroup, DSA_Kosherizer }

## Public Member Functions
void | BER_decode (DataSource &src, Format format)
SecureVector< byte > | DER_encode (Format format) const
| DL_Group ()
| DL_Group (const std::string &name)
| DL_Group (RandomNumberGenerator &rng, PrimeType type, size_t pbits, size_t qbits=0)
| DL_Group (RandomNumberGenerator &rng, const MemoryRegion< byte > &seed, size_t pbits=1024, size_t qbits=0)
| DL_Group (const BigInt &p, const BigInt &g)
| DL_Group (const BigInt &p, const BigInt &q, const BigInt &g)
const BigInt & | get_g () const
const BigInt & | get_p () const
const BigInt & | get_q () const
void | PEM_decode (DataSource &src)
std::string | PEM_encode (Format format) const
bool | verify_group (RandomNumberGenerator &rng, bool strong) const

## Detailed Description

This class represents discrete logarithm groups. It holds a prime p, a prime q = (p-1)/2 and g = x^((p-1)/q) mod p.

Definition at line 20 of file dl_group.h.

## Member Enumeration Documentation

## ◆ Format

enum Botan::DL_Group::Format

The DL group encoding format variants.

Enumerator
ANSI_X9_42 |
ANSI_X9_57 |
PKCS_3 |
DSA_PARAMETERS |
DH_PARAMETERS |
X942_DH_PARAMETERS |
PKCS3_DH_PARAMETERS |

Definition at line 44 of file dl_group.h.

44 {
45 ANSI_X9_42,
46 ANSI_X9_57,
47 PKCS_3,
48
49 DSA_PARAMETERS = ANSI_X9_57,
50 DH_PARAMETERS = ANSI_X9_42,
51 X942_DH_PARAMETERS = ANSI_X9_42,
52 PKCS3_DH_PARAMETERS = PKCS_3
53 };
Botan::DL_Group::PKCS3_DH_PARAMETERS
Definition: dl_group.h:52
Botan::DL_Group::X942_DH_PARAMETERS
Definition: dl_group.h:51
Botan::DL_Group::PKCS_3
Definition: dl_group.h:47
Botan::DL_Group::ANSI_X9_57
Definition: dl_group.h:46
Botan::DL_Group::DH_PARAMETERS
Definition: dl_group.h:50
Botan::DL_Group::ANSI_X9_42
Definition: dl_group.h:45
Botan::DL_Group::DSA_PARAMETERS
Definition: dl_group.h:49

## ◆ PrimeType

enum Botan::DL_Group::PrimeType

Determine the prime creation for DL groups.

Enumerator
Strong |
Prime_Subgroup |
DSA_Kosherizer |

Definition at line 58 of file dl_group.h.

58 { Strong, Prime_Subgroup, DSA_Kosherizer };
Botan::DL_Group::Prime_Subgroup
Definition: dl_group.h:58
Botan::DL_Group::Strong
Definition: dl_group.h:58
Botan::DL_Group::DSA_Kosherizer
Definition: dl_group.h:58

## Constructor & Destructor Documentation

## ◆ DL_Group() [1/6]

Botan::DL_Group::DL_Group | ( |  | ) |

Construct a DL group with uninitialized internal value. Use this constructor is you wish to set the groups values from a DER or PEM encoded group.

Definition at line 24 of file dl_group.cpp.

25 {
26 initialized = false;
27 }

## ◆ DL_Group() [2/6]

Botan::DL_Group::DL_Group | ( | const std::string & | name | ) |

Construct a DL group that is registered in the configuration.

Parameters

  name | the name that is configured in the global configuration for the desired group. If no configuration file is specified, the default values from the file policy.cpp will be used. For instance, use "modp/ietf/768" as name.

Definition at line 32 of file dl_group.cpp.

References Botan::Library_State::get(), Botan::Global_State_Management::global_state(), and PEM_decode().

33 {
34 std::string grp_contents = global_state().get("dl", type);
35
36 if(grp_contents == "")
37 throw Invalid_Argument("DL_Group: Unknown group " + type);
38
39 DataSource_Memory pem(grp_contents);
40 PEM_decode(pem);
41 }
Botan::DL_Group::PEM_decode
void PEM_decode(DataSource &src)
Definition: dl_group.cpp:300
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
Botan::Global_State_Management::global_state
Library_State & global_state()
Definition: global_state.cpp:32
Botan::Library_State::get
std::string get(const std::string &section, const std::string &key) const
Definition: libstate.cpp:114

## ◆ DL_Group() [3/6]

Botan::DL_Group::DL_Group | ( | RandomNumberGenerator & | rng,
|  | PrimeType | type,
|  | size_t | pbits,
|  | size_t | qbits = `0`
| ) |  |

Create a new group randomly.

Parameters

  rng | the random number generator to use
  type | specifies how the creation of primes p and q shall be performed. If type=Strong, then p will be determined as a safe prime, and q will be chosen as (p-1)/2. If type=Prime_Subgroup and qbits = 0, then the size of q will be determined according to the estimated difficulty of the DL problem. If type=DSA_Kosherizer, DSA primes will be created.
  pbits | the number of bits of p
  qbits | the number of bits of q. Leave it as 0 to have the value determined according to pbits.

Definition at line 46 of file dl_group.cpp.

48 {
49 if(pbits < 512)
50 throw Invalid_Argument("DL_Group: prime size " + to_string(pbits) +
51 " is too small");
52
53 if(type == Strong)
54 {
55 p = random_safe_prime(rng, pbits);
56 q = (p - 1) / 2;
57 g = 2;
58 }
59 else if(type == Prime_Subgroup)
60 {
61 if(!qbits)
62 qbits = 2 * dl_work_factor(pbits);
63
64 q = random_prime(rng, qbits);
65 BigInt X;
66 while(p.bits() != pbits || !check_prime(p, rng))
67 {
68 X.randomize(rng, pbits);
69 p = X - (X % (2*q) - 1);
70 }
71
72 g = make_dsa_generator(p, q);
73 }
74 else if(type == DSA_Kosherizer)
75 {
76 qbits = qbits ? qbits : ((pbits <= 1024) ? 160 : 256);
77
78 generate_dsa_primes(rng,
79 global_state().algorithm_factory(),
80 p, q,
81 pbits, qbits);
82
83 g = make_dsa_generator(p, q);
84 }
85
86 initialized = true;
87 }
Botan::DL_Group::Prime_Subgroup
Definition: dl_group.h:58
Botan::BigInt::bits
size_t bits() const
Definition: bigint.cpp:254
Botan::DL_Group::Strong
Definition: dl_group.h:58
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
Botan::Global_State_Management::global_state
Library_State & global_state()
Definition: global_state.cpp:32
Botan::random_safe_prime
BigInt random_safe_prime(RandomNumberGenerator &rng, size_t bits)
Definition: make_prm.cpp:87
Botan::DL_Group::DSA_Kosherizer
Definition: dl_group.h:58
Botan::to_string
std::string to_string(u64bit n, size_t min_len)
Definition: parsing.cpp:42
Botan::dl_work_factor
size_t dl_work_factor(size_t bits)
Definition: workfactor.cpp:14
Botan::generate_dsa_primes
bool generate_dsa_primes(RandomNumberGenerator &rng, Algorithm_Factory &af, BigInt &p, BigInt &q, size_t pbits, size_t qbits, const MemoryRegion< byte > &seed_c)
Definition: dsa_gen.cpp:41
Botan::random_prime
BigInt random_prime(RandomNumberGenerator &rng, size_t bits, const BigInt &coprime, size_t equiv, size_t modulo)
Definition: make_prm.cpp:17
Botan::check_prime
bool check_prime(const BigInt &n, RandomNumberGenerator &rng)
Definition: numthry.h:143

## ◆ DL_Group() [4/6]

Botan::DL_Group::DL_Group | ( | RandomNumberGenerator & | rng,
|  | const MemoryRegion< byte > & | seed,
|  | size_t | pbits = `1024`,
|  | size_t | qbits = `0`
| ) |  |

Create a DSA group with a given seed.

Parameters

  rng | the random number generator to use
  seed | the seed to use to create the random primes
  pbits | the desired bit size of the prime p
  qbits | the desired bit size of the prime q.

Definition at line 92 of file dl_group.cpp.

94 {
95 if(!generate_dsa_primes(rng,
96 global_state().algorithm_factory(),
97 p, q, pbits, qbits, seed))
98 throw Invalid_Argument("DL_Group: The seed given does not "
99 "generate a DSA group");
100
101 g = make_dsa_generator(p, q);
102
103 initialized = true;
104 }
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
Botan::Global_State_Management::global_state
Library_State & global_state()
Definition: global_state.cpp:32
Botan::generate_dsa_primes
bool generate_dsa_primes(RandomNumberGenerator &rng, Algorithm_Factory &af, BigInt &p, BigInt &q, size_t pbits, size_t qbits, const MemoryRegion< byte > &seed_c)
Definition: dsa_gen.cpp:41

## ◆ DL_Group() [5/6]

Botan::DL_Group::DL_Group | ( | const BigInt & | p,
|  | const BigInt & | g
| ) |  |

Create a DL group. The prime q will be determined according to p.

Parameters

  p | the prime p
  g | the base g

Definition at line 109 of file dl_group.cpp.

110 {
111 initialize(p1, 0, g1);
112 }

## ◆ DL_Group() [6/6]

Botan::DL_Group::DL_Group | ( | const BigInt & | p,
|  | const BigInt & | q,
|  | const BigInt & | g
| ) |  |

Create a DL group.

Parameters

  p | the prime p
  q | the prime q
  g | the base g

Definition at line 117 of file dl_group.cpp.

118 {
119 initialize(p1, q1, g1);
120 }

## Member Function Documentation

## ◆ BER_decode()

void Botan::DL_Group::BER_decode | ( | DataSource & | src,
|  | Format | format
| ) |  |

Decode a DER/BER encoded group into this instance.

Parameters

  src | a DataSource providing the encoded group
  format | the format of the encoded group

Definition at line 264 of file dl_group.cpp.

References ANSI_X9_42, ANSI_X9_57, Botan::BER_Decoder::decode(), Botan::BER_Decoder::discard_remaining(), PKCS_3, Botan::SEQUENCE, Botan::BER_Decoder::start_cons(), Botan::to_string(), and Botan::BER_Decoder::verify_end().

Referenced by Botan::DL_Scheme_PrivateKey::DL_Scheme_PrivateKey(), Botan::DL_Scheme_PublicKey::DL_Scheme_PublicKey(), and PEM_decode().

265 {
266 BigInt new_p, new_q, new_g;
267
268 BER_Decoder decoder(source);
269 BER_Decoder ber = decoder.start_cons(SEQUENCE);
270
271 if(format == ANSI_X9_57)
272 {
273 ber.decode(new_p)
274 .decode(new_q)
275 .decode(new_g)
276 .verify_end();
277 }
278 else if(format == ANSI_X9_42)
279 {
280 ber.decode(new_p)
281 .decode(new_g)
282 .decode(new_q)
283 .discard_remaining();
284 }
285 else if(format == PKCS_3)
286 {
287 ber.decode(new_p)
288 .decode(new_g)
289 .discard_remaining();
290 }
291 else
292 throw Invalid_Argument("Unknown DL_Group encoding " + to_string(format));
293
294 initialize(new_p, new_q, new_g);
295 }
Botan::DL_Group::PKCS_3
Definition: dl_group.h:47
Botan::DL_Group::ANSI_X9_57
Definition: dl_group.h:46
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
Botan::SEQUENCE
Definition: asn1_int.h:35
Botan::DL_Group::ANSI_X9_42
Definition: dl_group.h:45
Botan::to_string
std::string to_string(u64bit n, size_t min_len)
Definition: parsing.cpp:42

## ◆ DER_encode()

SecureVector< byte > Botan::DL_Group::DER_encode | ( | Format | format | ) | const

Encode this group into a string using DER encoding.

Parameters

  format | the encoding format

Returns
  string holding the DER encoded group

Definition at line 205 of file dl_group.cpp.

References ANSI_X9_42, ANSI_X9_57, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::DER_Encoder::get_contents(), PKCS_3, Botan::SEQUENCE, Botan::DER_Encoder::start_cons(), and Botan::to_string().

Referenced by Botan::DL_Scheme_PublicKey::algorithm_identifier(), and PEM_encode().

206 {
207 init_check();
208
209 if((q == 0) && (format != PKCS_3))
210 throw Encoding_Error("The ANSI DL parameter formats require a subgroup");
211
212 if(format == ANSI_X9_57)
213 {
214 return DER_Encoder()
215 .start_cons(SEQUENCE)
216 .encode(p)
217 .encode(q)
218 .encode(g)
219 .end_cons()
220 .get_contents();
221 }
222 else if(format == ANSI_X9_42)
223 {
224 return DER_Encoder()
225 .start_cons(SEQUENCE)
226 .encode(p)
227 .encode(g)
228 .encode(q)
229 .end_cons()
230 .get_contents();
231 }
232 else if(format == PKCS_3)
233 {
234 return DER_Encoder()
235 .start_cons(SEQUENCE)
236 .encode(p)
237 .encode(g)
238 .end_cons()
239 .get_contents();
240 }
241
242 throw Invalid_Argument("Unknown DL_Group encoding " + to_string(format));
243 }
Botan::DL_Group::PKCS_3
Definition: dl_group.h:47
Botan::DL_Group::ANSI_X9_57
Definition: dl_group.h:46
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
Botan::SEQUENCE
Definition: asn1_int.h:35
Botan::DL_Group::ANSI_X9_42
Definition: dl_group.h:45
Botan::to_string
std::string to_string(u64bit n, size_t min_len)
Definition: parsing.cpp:42

## ◆ get_g()

const BigInt & Botan::DL_Group::get_g | ( |  | ) | const

Get the base g.

Returns
  base g

Definition at line 185 of file dl_group.cpp.

Referenced by Botan::generate_srp6_verifier().

186 {
187 init_check();
188 return g;
189 }

## ◆ get_p()

const BigInt & Botan::DL_Group::get_p | ( |  | ) | const

Get the prime p.

Returns
  prime p

Definition at line 176 of file dl_group.cpp.

Referenced by Botan::generate_srp6_verifier().

177 {
178 init_check();
179 return p;
180 }

## ◆ get_q()

const BigInt & Botan::DL_Group::get_q | ( |  | ) | const

Get the prime q.

Returns
  prime q

Definition at line 194 of file dl_group.cpp.

195 {
196 init_check();
197 if(q == 0)
198 throw Invalid_State("DLP group has no q prime specified");
199 return q;
200 }

## ◆ PEM_decode()

void Botan::DL_Group::PEM_decode | ( | DataSource & | src | ) |

Decode a PEM encoded group into this instance.

Parameters

  src | a DataSource providing the encoded group

Definition at line 300 of file dl_group.cpp.

References ANSI_X9_42, ANSI_X9_57, BER_decode(), Botan::PEM_Code::decode(), and PKCS_3.

Referenced by DL_Group().

301 {
302 std::string label;
303 DataSource_Memory ber(PEM_Code::decode(source, label));
304
305 if(label == "DH PARAMETERS")
306 BER_decode(ber, PKCS_3);
307 else if(label == "DSA PARAMETERS")
308 BER_decode(ber, ANSI_X9_57);
309 else if(label == "X942 DH PARAMETERS")
310 BER_decode(ber, ANSI_X9_42);
311 else
312 throw Decoding_Error("DL_Group: Invalid PEM label " + label);
313 }
Botan::DL_Group::PKCS_3
Definition: dl_group.h:47
Botan::DL_Group::ANSI_X9_57
Definition: dl_group.h:46
Botan::DL_Group::BER_decode
void BER_decode(DataSource &src, Format format)
Definition: dl_group.cpp:264
Botan::PEM_Code::decode
SecureVector< byte > decode(DataSource &source, std::string &label)
Definition: pem.cpp:56
Botan::DL_Group::ANSI_X9_42
Definition: dl_group.h:45

## ◆ PEM_encode()

std::string Botan::DL_Group::PEM_encode | ( | Format | format | ) | const

Encode this group into a string using PEM encoding.

Parameters

  format | the encoding format

Returns
  string holding the PEM encoded group

Definition at line 248 of file dl_group.cpp.

References ANSI_X9_42, ANSI_X9_57, DER_encode(), Botan::PEM_Code::encode(), PKCS_3, and Botan::to_string().

249 {
250 SecureVector<byte> encoding = DER_encode(format);
251 if(format == PKCS_3)
252 return PEM_Code::encode(encoding, "DH PARAMETERS");
253 else if(format == ANSI_X9_57)
254 return PEM_Code::encode(encoding, "DSA PARAMETERS");
255 else if(format == ANSI_X9_42)
256 return PEM_Code::encode(encoding, "X942 DH PARAMETERS");
257 else
258 throw Invalid_Argument("Unknown DL_Group encoding " + to_string(format));
259 }
Botan::DL_Group::PKCS_3
Definition: dl_group.h:47
Botan::DL_Group::ANSI_X9_57
Definition: dl_group.h:46
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
Botan::DL_Group::ANSI_X9_42
Definition: dl_group.h:45
Botan::PEM_Code::encode
std::string encode(const byte der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:19
Botan::DL_Group::DER_encode
SecureVector< byte > DER_encode(Format format) const
Definition: dl_group.cpp:205
Botan::to_string
std::string to_string(u64bit n, size_t min_len)
Definition: parsing.cpp:42

## ◆ verify_group()

bool Botan::DL_Group::verify_group | ( | RandomNumberGenerator & | rng,
|  | bool | strong
| ) |  | const

Perform validity checks on the group.

Parameters

  rng | the rng to use
  strong | whether to perform stronger by lengthier tests

Returns
  true if the object is consistent, false otherwise

Definition at line 153 of file dl_group.cpp.

155 {
156 init_check();
157
158 if(g < 2 || p < 3 || q < 0)
159 return false;
160 if((q != 0) && ((p - 1) % q != 0))
161 return false;
162
163 if(!strong)
164 return true;
165
166 if(!check_prime(p, rng))
167 return false;
168 if((q > 0) && !check_prime(q, rng))
169 return false;
170 return true;
171 }
Botan::check_prime
bool check_prime(const BigInt &n, RandomNumberGenerator &rng)
Definition: numthry.h:143

The documentation for this class was generated from the following files:

- src/pubkey/dl_group/dl_group.h
- src/pubkey/dl_group/dl_group.cpp