Botan 2.19.5 Crypto and TLS for C&

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

`#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 , ANSI_X9_42_DH_PARAMETERS = ANSI_X9_42 , PKCS3_DH_PARAMETERS = PKCS_3 }
enum | PrimeType { Strong , Prime_Subgroup , DSA_Kosherizer }

## Public Member Functions
void | BER_decode (const std::vector< uint8_t > &ber, Format format)
std::vector< uint8_t > | DER_encode (Format format) const
| DL_Group ()=default
| DL_Group (const BigInt &p, const BigInt &g)
| DL_Group (const BigInt &p, const BigInt &q, const BigInt &g)
| DL_Group (const std::string &name)
template<typename Alloc >
| DL_Group (const std::vector< uint8_t, Alloc > &ber, Format format)
| DL_Group (const uint8_t ber[], size_t ber_len, Format format)
| DL_Group (RandomNumberGenerator &rng, const std::vector< uint8_t > &seed, size_t pbits=1024, size_t qbits=0)
| DL_Group (RandomNumberGenerator &rng, PrimeType type, size_t pbits, size_t qbits=0)
size_t | estimated_strength () const
size_t | exponent_bits () const
const BigInt & | get_g () const
const BigInt & | get_p () const
const BigInt & | get_q () const
BigInt | inverse_mod_p (const BigInt &x) const
BigInt | inverse_mod_q (const BigInt &x) const
BigInt | mod_p (const BigInt &x) const
BigInt | mod_q (const BigInt &x) const
std::shared_ptr< const Montgomery_Params > | monty_params_p () const
BigInt | multi_exponentiate (const BigInt &x, const BigInt &y, const BigInt &z) const
BigInt | multiply_mod_p (const BigInt &x, const BigInt &y) const
BigInt | multiply_mod_q (const BigInt &x, const BigInt &y) const
BigInt | multiply_mod_q (const BigInt &x, const BigInt &y, const BigInt &z) const
size_t | p_bits () const
size_t | p_bytes () const
void | PEM_decode (const std::string &pem)
std::string | PEM_encode (Format format) const
BigInt | power_g_p (const BigInt &x) const
BigInt | power_g_p (const BigInt &x, size_t max_x_bits) const
size_t | q_bits () const
size_t | q_bytes () const
DL_Group_Source | source () const
BigInt | square_mod_q (const BigInt &x) const
bool | verify_element_pair (const BigInt &y, const BigInt &x) const
bool | verify_group (RandomNumberGenerator &rng, bool strong=true) const
bool | verify_public_element (const BigInt &y) const

## Static Public Member Functions
static DL_Group | DL_Group_from_PEM (const std::string &pem)
static std::shared_ptr< DL_Group_Data > | DL_group_info (const std::string &name)
static std::string | PEM_for_named_group (const std::string &name)

## Detailed Description

This class represents discrete logarithm groups. It holds a prime modulus p, a generator g, and (optionally) a prime q which is a factor of (p-1). In most cases g generates the order-q subgroup.

Definition at line 29 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 |
ANSI_X9_42_DH_PARAMETERS |
PKCS3_DH_PARAMETERS |

Definition at line 40 of file dl_group.h.

40 {
41 ANSI_X9_42,
42 ANSI_X9_57,
43 PKCS_3,
44
45 DSA_PARAMETERS = ANSI_X9_57,
46 DH_PARAMETERS = ANSI_X9_42,
47 ANSI_X9_42_DH_PARAMETERS = ANSI_X9_42,
48 PKCS3_DH_PARAMETERS = PKCS_3
49 };
Botan::DL_Group::DSA_PARAMETERS
@ DSA_PARAMETERS
Definition: dl_group.h:45
Botan::DL_Group::DH_PARAMETERS
@ DH_PARAMETERS
Definition: dl_group.h:46
Botan::DL_Group::ANSI_X9_57
@ ANSI_X9_57
Definition: dl_group.h:42
Botan::DL_Group::PKCS3_DH_PARAMETERS
@ PKCS3_DH_PARAMETERS
Definition: dl_group.h:48
Botan::DL_Group::ANSI_X9_42_DH_PARAMETERS
@ ANSI_X9_42_DH_PARAMETERS
Definition: dl_group.h:47
Botan::DL_Group::ANSI_X9_42
@ ANSI_X9_42
Definition: dl_group.h:41
Botan::DL_Group::PKCS_3
@ PKCS_3
Definition: dl_group.h:43

## ◆ PrimeType

enum Botan::DL_Group::PrimeType

Determine the prime creation for DL groups.

Enumerator
Strong |
Prime_Subgroup |
DSA_Kosherizer |

Definition at line 35 of file dl_group.h.

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

## Constructor & Destructor Documentation

## ◆ DL_Group() [1/8]

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

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.

Referenced by DL_Group_from_PEM().

## ◆ DL_Group() [2/8]

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

Construct a DL group that is registered in the configuration.

Parameters

  name | the name of the group, for example "modp/ietf/3072"

Warning
  This constructor also accepts PEM inputs. This behavior is deprecated and will be removed in a future major release. Instead use DL_Group_from_PEM function

Definition at line 189 of file dl_group.cpp.

190 {
191 // Either a name or a PEM block, try name first
192 m_data = DL_group_info(str);
193
194 if(m_data == nullptr)
195 {
196 try
197 {
198 std::string label;
199 const std::vector<uint8_t> ber = unlock(PEM_Code::decode(str, label));
200 Format format = pem_label_to_dl_format(label);
201
202 m_data = BER_decode_DL_group(ber.data(), ber.size(), format, DL_Group_Source::ExternalSource);
203 }
204 catch(...) {}
205 }
206
207 if(m_data == nullptr)
208 throw Invalid_Argument("DL_Group: Unknown group " + str);
209 }
Botan::DL_Group::DL_group_info
static std::shared_ptr< DL_Group_Data > DL_group_info(const std::string &name)
Definition: dl_named.cpp:13
Botan::DL_Group::Format
Format
Definition: dl_group.h:40
Botan::PEM_Code::decode
secure_vector< uint8_t > decode(DataSource &source, std::string &label)
Definition: pem.cpp:68
Botan::DL_Group_Source::ExternalSource
@ ExternalSource
Botan::unlock
std::vector< T > unlock(const secure_vector< T > &in)
Definition: secmem.h:72

References Botan::PEM_Code::decode(), DL_group_info(), Botan::ExternalSource, and Botan::unlock().

## ◆ DL_Group() [3/8]

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 240 of file dl_group.cpp.

242 {
243 if(pbits < 1024)
244 throw Invalid_Argument("DL_Group: prime size " + std::to_string(pbits) + " is too small");
245
246 if(type == Strong)
247 {
248 if(qbits != 0 && qbits != pbits - 1)
249 throw Invalid_Argument("Cannot create strong-prime DL_Group with specified q bits");
250
251 const BigInt p = random_safe_prime(rng, pbits);
252 const BigInt q = (p - 1) / 2;
253
254 /*
255 Always choose a generator that is quadratic reside mod p,
256 this forces g to be a generator of the subgroup of size q.
257 */
258 BigInt g = 2;
259 if(jacobi(g, p) != 1)
260 {
261 // prime table does not contain 2
262 for(size_t i = 0; i < PRIME_TABLE_SIZE; ++i)
263 {
264 g = PRIMES[i];
265 if(jacobi(g, p) == 1)
266 break;
267 }
268 }
269
270 m_data = std::make_shared<DL_Group_Data>(p, q, g, DL_Group_Source::RandomlyGenerated);
271 }
272 else if(type == Prime_Subgroup)
273 {
274 if(qbits == 0)
275 qbits = dl_exponent_size(pbits);
276
277 const BigInt q = random_prime(rng, qbits);
278 Modular_Reducer mod_2q(2*q);
279 BigInt X;
280 BigInt p;
281 while(p.bits() != pbits || !is_prime(p, rng, 128, true))
282 {
283 X.randomize(rng, pbits);
284 p = X - mod_2q.reduce(X) + 1;
285 }
286
287 const BigInt g = make_dsa_generator(p, q);
288 m_data = std::make_shared<DL_Group_Data>(p, q, g, DL_Group_Source::RandomlyGenerated);
289 }
290 else if(type == DSA_Kosherizer)
291 {
292 if(qbits == 0)
293 qbits = ((pbits <= 1024) ? 160 : 256);
294
295 BigInt p, q;
296 generate_dsa_primes(rng, p, q, pbits, qbits);
297 const BigInt g = make_dsa_generator(p, q);
298 m_data = std::make_shared<DL_Group_Data>(p, q, g, DL_Group_Source::RandomlyGenerated);
299 }
300 else
301 {
302 throw Invalid_Argument("DL_Group unknown PrimeType");
303 }
304 }
X
fe X
Definition: ge.cpp:27
Botan::ASN1::to_string
std::string to_string(const BER_Object &obj)
Definition: asn1_obj.cpp:213
Botan::random_prime
BigInt random_prime(RandomNumberGenerator &rng, size_t bits, const BigInt &coprime, size_t equiv, size_t modulo, size_t prob)
Definition: make_prm.cpp:77
Botan::PRIMES
const uint16_t PRIMES[]
Definition: primes.cpp:12
Botan::PRIME_TABLE_SIZE
const size_t PRIME_TABLE_SIZE
Definition: numthry.h:287
Botan::DL_Group_Source::RandomlyGenerated
@ RandomlyGenerated
Botan::dl_exponent_size
size_t dl_exponent_size(size_t bits)
Definition: workfactor.cpp:52
Botan::is_prime
bool is_prime(const BigInt &n, RandomNumberGenerator &rng, size_t prob, bool is_random)
Definition: numthry.cpp:218
Botan::generate_dsa_primes
bool generate_dsa_primes(RandomNumberGenerator &rng, BigInt &p, BigInt &q, size_t pbits, size_t qbits, const std::vector< uint8_t > &seed_c, size_t offset)
Definition: dsa_gen.cpp:39
Botan::jacobi
int32_t jacobi(const BigInt &a, const BigInt &n)
Definition: jacobi.cpp:15
Botan::random_safe_prime
BigInt random_safe_prime(RandomNumberGenerator &rng, size_t bits)
Definition: make_prm.cpp:268
type
MechanismType type
Definition: p11_mechanism.cpp:44

References Botan::BigInt::bits(), Botan::dl_exponent_size(), DSA_Kosherizer, Botan::generate_dsa_primes(), Botan::is_prime(), Botan::jacobi(), Prime_Subgroup, Botan::PRIME_TABLE_SIZE, Botan::PRIMES, Botan::random_prime(), Botan::random_safe_prime(), Botan::RandomlyGenerated, Botan::Modular_Reducer::reduce(), Strong, Botan::ASN1::to_string(), type, and X.

## ◆ DL_Group() [4/8]

Botan::DL_Group::DL_Group | ( | RandomNumberGenerator & | rng,
|  | const std::vector< uint8_t > & | 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 309 of file dl_group.cpp.

312 {
313 BigInt p, q;
314
315 if(!generate_dsa_primes(rng, p, q, pbits, qbits, seed))
316 throw Invalid_Argument("DL_Group: The seed given does not generate a DSA group");
317
318 BigInt g = make_dsa_generator(p, q);
319
320 m_data = std::make_shared<DL_Group_Data>(p, q, g, DL_Group_Source::RandomlyGenerated);
321 }

References Botan::generate_dsa_primes(), and Botan::RandomlyGenerated.

## ◆ DL_Group() [5/8]

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

Create a DL group.

Parameters

  p | the prime p
  g | the base g

Definition at line 326 of file dl_group.cpp.

327 {
328 m_data = std::make_shared<DL_Group_Data>(p, 0, g, DL_Group_Source::ExternalSource);
329 }

References Botan::ExternalSource.

## ◆ DL_Group() [6/8]

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 334 of file dl_group.cpp.

335 {
336 m_data = std::make_shared<DL_Group_Data>(p, q, g, DL_Group_Source::ExternalSource);
337 }

References Botan::ExternalSource.

## ◆ DL_Group() [7/8]

Botan::DL_Group::DL_Group | ( | const uint8_t | ber[],
|  | size_t | ber_len,
|  | Format | format
| ) |  |

Decode a BER-encoded DL group param

Definition at line 607 of file dl_group.cpp.

608 {
609 m_data = BER_decode_DL_group(ber, ber_len, format, DL_Group_Source::ExternalSource);
610 }

References Botan::ExternalSource.

## ◆ DL_Group() [8/8]

template<typename Alloc >

Botan::DL_Group::DL_Group | ( | const std::vector< uint8_t, Alloc > & | ber,
|  | Format | format
| ) |  |
| inline

Decode a BER-encoded DL group param

Definition at line 124 of file dl_group.h.

124 :
125 DL_Group(ber.data(), ber.size(), format) {}
Botan::DL_Group::DL_Group
DL_Group()=default

## Member Function Documentation

## ◆ BER_decode()

void Botan::DL_Group::BER_decode | ( | const std::vector< uint8_t > & | ber,
|  | Format | format
| ) |  |

Decode a DER/BER encoded group into this instance.

Parameters

  ber | a vector containing the DER/BER encoded group
  format | the format of the encoded group

Warning
  avoid this. Instead use the DL_Group constructor

Definition at line 612 of file dl_group.cpp.

613 {
614 m_data = BER_decode_DL_group(ber.data(), ber.size(), format, DL_Group_Source::ExternalSource);
615 }

References Botan::ExternalSource.

Referenced by Botan::DL_Scheme_PrivateKey::DL_Scheme_PrivateKey().

## ◆ DER_encode()

std::vector< uint8_t > 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 553 of file dl_group.cpp.

554 {
555 if(get_q().is_zero() && (format == ANSI_X9_57 || format == ANSI_X9_42))
556 throw Encoding_Error("Cannot encode DL_Group in ANSI formats when q param is missing");
557
558 std::vector<uint8_t> output;
559 DER_Encoder der(output);
560
561 if(format == ANSI_X9_57)
562 {
563 der.start_cons(SEQUENCE)
564 .encode(get_p())
565 .encode(get_q())
566 .encode(get_g())
567 .end_cons();
568 }
569 else if(format == ANSI_X9_42)
570 {
571 der.start_cons(SEQUENCE)
572 .encode(get_p())
573 .encode(get_g())
574 .encode(get_q())
575 .end_cons();
576 }
577 else if(format == PKCS_3)
578 {
579 der.start_cons(SEQUENCE)
580 .encode(get_p())
581 .encode(get_g())
582 .end_cons();
583 }
584 else
585 throw Invalid_Argument("Unknown DL_Group encoding " + std::to_string(format));
586
587 return output;
588 }
Botan::DL_Group::get_p
const BigInt & get_p() const
Definition: dl_group.cpp:425
Botan::DL_Group::get_g
const BigInt & get_g() const
Definition: dl_group.cpp:433
Botan::DL_Group::get_q
const BigInt & get_q() const
Definition: dl_group.cpp:441
Botan::SEQUENCE
@ SEQUENCE
Definition: asn1_obj.h:42

References ANSI_X9_42, ANSI_X9_57, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), get_g(), get_p(), get_q(), PKCS_3, Botan::SEQUENCE, Botan::DER_Encoder::start_cons(), and Botan::ASN1::to_string().

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

## ◆ DL_Group_from_PEM()

DL_Group Botan::DL_Group::DL_Group_from_PEM | ( | const std::string & | pem | ) |
| static

Definition at line 618 of file dl_group.cpp.

619 {
620 std::string label;
621 const std::vector<uint8_t> ber = unlock(PEM_Code::decode(pem, label));
622 Format format = pem_label_to_dl_format(label);
623 return DL_Group(ber, format);
624 }

References Botan::PEM_Code::decode(), DL_Group(), and Botan::unlock().

## ◆ DL_group_info()

std::shared_ptr< DL_Group_Data > Botan::DL_Group::DL_group_info | ( | const std::string & | name | ) |
| static

Definition at line 13 of file dl_named.cpp.

14 {
15 /* TLS FFDHE groups */
16
17 if(name == "ffdhe/ietf/2048")
18 {
19 return load_DL_group_info(" ",
20 "0x2");
21 }
22
23 if(name == "ffdhe/ietf/3072")
24 {
25 return load_DL_group_info(" ",
26 "0x2");
27 }
28
29 if(name == "ffdhe/ietf/4096")
30 {
31 return load_DL_group_info(" ",
32 "0x2");
33 }
34
35 if(name == "ffdhe/ietf/6144")
36 {
37 return load_DL_group_info(" ",
38 "0x2");
39 }
40
41 if(name == "ffdhe/ietf/8192")
42 {
43 return load_DL_group_info(" ",
44 "0x2");
45 }
46
47 /* IETF IPsec groups */
48
49 if(name == "modp/ietf/1024")
50 {
51 return load_DL_group_info("0xFFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE649286651ECE65381FFFFFFFFFFFFFFFF",
52 "0x2");
53 }
54
55 if(name == "modp/ietf/1536")
56 {
57 return load_DL_group_info("0xFFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3DC2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F83655D23DCA3AD961C62F356208552BB9ED529077096966D670C354E4ABC9804F1746C08CA237327FFFFFFFFFFFFFFFF",
58 "0x2");
59 }
60
61 if(name == "modp/ietf/2048")
62 {
63 return load_DL_group_info(" ",
64 "0x2");
65 }
66
67 if(name == "modp/ietf/3072")
68 {
69 return load_DL_group_info(" ",
70 "0x2");
71 }
72
73 if(name == "modp/ietf/4096")
74 {
75 return load_DL_group_info(" ",
76 "0x2");
77 }
78
79 if(name == "modp/ietf/6144")
80 {
81 return load_DL_group_info(" ",
82 "0x2");
83 }
84
85 if(name == "modp/ietf/8192")
86 {
87 return load_DL_group_info(" ",
88 "0x2");
89 }
90
91 /* SRP groups
92
93 SRP groups have a p st (p-1)/2 is prime, but g is not a generator
94 of subgroup of size q, so set q == 0 to bypass generator check
95
96 Missing q doesn't matter for SRP, and nothing but SRP should be
97 using these parameters.
98 */
99
100 if(name == "modp/srp/1024")
101 {
102 return load_DL_group_info("0xEEAF0AB9ADB38DD69C33F80AFA8FC5E86072618775FF3C0B9EA2314C9C256576D674DF7496EA81D3383B4813D692C6E0E0D5D8E250B98BE48E495C1D6089DAD15DC7D7B46154D6B6CE8EF4AD69B15D4982559B297BCF1885C529F566660E57EC68EDBC3C05726CC02FD4CBF4976EAA9AFD5138FE8376435B9FC61D2FC0EB06E3",
103 "0",
104 "0x2");
105 }
106
107 if(name == "modp/srp/1536")
108 {
109 return load_DL_group_info("0x9DEF3CAFB939277AB1F12A8617A47BBBDBA51DF499AC4C80BEEEA9614B19CC4D5F4F5F556E27CBDE51C6A94BE4607A291558903BA0D0F84380B655BB9A22E8DCDF028A7CEC67F0D08134B1C8B97989149B609E0BE3BAB63D47548381DBC5B1FC764E3F4B53DD9DA1158BFD3E2B9C8CF56EDF019539349627DB2FD53D24B7C48665772E437D6C7F8CE442734AF7CCB7AE837C264AE3A9BEB87F8A2FE9B8B5292E5A021FFF5E91479E8CE7A28C2442C6F315180F93499A234DCF76E3FED135F9BB",
110 "0",
111 "0x2");
112 }
113
114 if(name == "modp/srp/2048")
115 {
116 return load_DL_group_info(" ",
117 "0",
118 "0x2");
119 }
120
121 if(name == "modp/srp/3072")
122 {
123 return load_DL_group_info(" ",
124 "0",
125 "0x5");
126 }
127
128 if(name == "modp/srp/4096")
129 {
130 return load_DL_group_info(" ",
131 "0",
132 "0x5");
133 }
134
135 if(name == "modp/srp/6144")
136 {
137 return load_DL_group_info(" ",
138 "0",
139 "0x5");
140 }
141
142 if(name == "modp/srp/8192")
143 {
144 return load_DL_group_info(" ",
145 "0",
146 "0x13");
147 }
148
149 /* DSA groups */
150
151 if(name == "dsa/jce/1024")
152 {
153 return load_DL_group_info("0xFD7F53811D75122952DF4A9C2EECE4E7F611B7523CEF4400C31E3F80B6512669455D402251FB593D8D58FABFC5F5BA30F6CB9B556CD7813B801D346FF26660B76B9950A5A49F9FE8047B1022C24FBBA9D7FEB7C61BF83B57E7C6A8A6150F04FB83F6D3C51EC3023554135A169132F675F3AE2B61D72AEFF22203199DD14801C7",
154 "0x9760508F15230BCCB292B982A2EB840BF0581CF5",
155 "0x469603512E30278CD3947595DB22EEC9826A6322ADC97344F41D740C325724C8F9EFBAA7D4D803FF8C609DCD100EBC5BDFCFAD7C6A425FAEA786EA2050EBE98351EA1FDA1FDF24D6947AA6B9AA23766953802F4D7D4A8ECBA06D19768A2491FFB16D0EF9C43A99B5F71672FF6F0A24B444D0736D04D38A1A1322DAF6CDD88C9D");
156 }
157
158 if(name == "dsa/botan/2048")
159 {
160 return load_DL_group_info(" ",
161 "0x8CD7D450F86F0AD94EEE4CE469A8756D1EBD1058241943EAFFB0B354585E924D",
162 " ");
163 }
164
165 if(name == "dsa/botan/3072")
166 {
167 return load_DL_group_info(" ",
168 "0xB3EBD364EC69EF8CF3BAF643B75734B16339B2E49E5CDE1B59C1E9FB40EE0C5B",
169 " ");
170 }
171
172 return std::shared_ptr<DL_Group_Data>();
173 }
name
std::string name
Definition: commoncrypto_hash.cpp:24

References name.

Referenced by DL_Group().

## ◆ estimated_strength()

size_t Botan::DL_Group::estimated_strength | ( |  | ) | const

Return an estimate of the strength of this group against discrete logarithm attacks (eg NFS). Warning: since this only takes into account known attacks it is by necessity an overestimate of the actual strength.

Definition at line 473 of file dl_group.cpp.

474 {
475 return data().estimated_strength();
476 }

Referenced by Botan::DL_Scheme_PublicKey::estimated_strength().

## ◆ exponent_bits()

size_t Botan::DL_Group::exponent_bits | ( |  | ) | const

Return size in bits of a secret exponent

This attempts to balance between the attack costs of NFS (which depends on the size of the modulus) and Pollard's rho (which depends on the size of the exponent).

It may vary over time for a particular group, if the attack costs change.

Definition at line 478 of file dl_group.cpp.

479 {
480 return data().exponent_bits();
481 }

Referenced by Botan::DH_PrivateKey::DH_PrivateKey(), Botan::ElGamal_PrivateKey::ElGamal_PrivateKey(), Botan::srp6_client_agree(), and Botan::SRP6_Server_Session::step1().

## ◆ get_g()

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

Get the base g.

Returns
  base g

Definition at line 433 of file dl_group.cpp.

434 {
435 return data().g();
436 }

Referenced by DER_encode(), multi_exponentiate(), Botan::TLS::Server_Key_Exchange::Server_Key_Exchange(), Botan::srp6_client_agree(), Botan::srp6_group_identifier(), Botan::SRP6_Server_Session::step1(), and verify_group().

## ◆ get_p()

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

Get the prime p.

Returns
  prime p

Definition at line 425 of file dl_group.cpp.

426 {
427 return data().p();
428 }

Referenced by DER_encode(), inverse_mod_p(), Botan::TLS::Server_Key_Exchange::Server_Key_Exchange(), Botan::srp6_client_agree(), Botan::srp6_group_identifier(), Botan::SRP6_Server_Session::step1(), verify_element_pair(), verify_group(), and verify_public_element().

## ◆ get_q()

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

Get the prime q, returns zero if q is not used

Returns
  prime q

Definition at line 441 of file dl_group.cpp.

442 {
443 return data().q();
444 }

Referenced by DER_encode(), inverse_mod_q(), PEM_for_named_group(), verify_group(), and verify_public_element().

## ◆ inverse_mod_p()

BigInt Botan::DL_Group::inverse_mod_p | ( | const BigInt & | x | ) | const

Return the inverse of x mod p

Definition at line 483 of file dl_group.cpp.

484 {
485 // precompute??
486 return inverse_mod(x, get_p());
487 }
Botan::inverse_mod
BigInt inverse_mod(const BigInt &n, const BigInt &mod)
Definition: mod_inv.cpp:250

References get_p(), and Botan::inverse_mod().

## ◆ inverse_mod_q()

BigInt Botan::DL_Group::inverse_mod_q | ( | const BigInt & | x | ) | const

Return the inverse of x mod q Throws if q is unset on this DL_Group

Definition at line 499 of file dl_group.cpp.

500 {
501 data().assert_q_is_set("inverse_mod_q");
502 // precompute??
503 return inverse_mod(x, get_q());
504 }

References get_q(), and Botan::inverse_mod().

## ◆ mod_p()

BigInt Botan::DL_Group::mod_p | ( | const BigInt & | x | ) | const

Reduce an integer modulo p

Returns
  x % p

Definition at line 489 of file dl_group.cpp.

490 {
491 return data().mod_p(x);
492 }

Referenced by Botan::srp6_client_agree(), and Botan::SRP6_Server_Session::step1().

## ◆ mod_q()

BigInt Botan::DL_Group::mod_q | ( | const BigInt & | x | ) | const

Reduce an integer modulo q Throws if q is unset on this DL_Group

Returns
  x % q

Definition at line 506 of file dl_group.cpp.

507 {
508 data().assert_q_is_set("mod_q");
509 return data().mod_q(x);
510 }

## ◆ monty_params_p()

std::shared_ptr< const Montgomery_Params > Botan::DL_Group::monty_params_p | ( |  | ) | const

Return parameters for Montgomery reduction/exponentiation mod p

Definition at line 446 of file dl_group.cpp.

447 {
448 return data().monty_params_p();
449 }

Referenced by multi_exponentiate().

## ◆ multi_exponentiate()

BigInt Botan::DL_Group::multi_exponentiate | ( | const BigInt & | x,
|  | const BigInt & | y,
|  | const BigInt & | z
| ) |  | const

Multi-exponentiate Return (g^x * y^z) % p

Definition at line 530 of file dl_group.cpp.

531 {
532 return monty_multi_exp(data().monty_params_p(), get_g(), x, y, z);
533 }
Botan::DL_Group::monty_params_p
std::shared_ptr< const Montgomery_Params > monty_params_p() const
Definition: dl_group.cpp:446
Botan::monty_multi_exp
BigInt monty_multi_exp(std::shared_ptr< const Montgomery_Params > params_p, const BigInt &x_bn, const BigInt &z1, const BigInt &y_bn, const BigInt &z2)
Definition: monty_exp.cpp:177

References get_g(), Botan::monty_multi_exp(), and monty_params_p().

## ◆ multiply_mod_p()

BigInt Botan::DL_Group::multiply_mod_p | ( | const BigInt & | x,
|  | const BigInt & | y
| ) |  | const

Multiply and reduce an integer modulo p

Returns
  (x*y) % p

Definition at line 494 of file dl_group.cpp.

495 {
496 return data().multiply_mod_p(x, y);
497 }

## ◆ multiply_mod_q() [1/2]

BigInt Botan::DL_Group::multiply_mod_q | ( | const BigInt & | x,
|  | const BigInt & | y
| ) |  | const

Multiply and reduce an integer modulo q Throws if q is unset on this DL_Group

Returns
  (x*y) % q

Definition at line 512 of file dl_group.cpp.

513 {
514 data().assert_q_is_set("multiply_mod_q");
515 return data().multiply_mod_q(x, y);
516 }

Referenced by multiply_mod_q().

## ◆ multiply_mod_q() [2/2]

BigInt Botan::DL_Group::multiply_mod_q | ( | const BigInt & | x,
|  | const BigInt & | y,
|  | const BigInt & | z
| ) |  | const

Multiply and reduce an integer modulo q Throws if q is unset on this DL_Group

Returns
  (x*y*z) % q

Definition at line 518 of file dl_group.cpp.

519 {
520 data().assert_q_is_set("multiply_mod_q");
521 return data().multiply_mod_q(data().multiply_mod_q(x, y), z);
522 }
Botan::DL_Group::multiply_mod_q
BigInt multiply_mod_q(const BigInt &x, const BigInt &y) const
Definition: dl_group.cpp:512

References multiply_mod_q().

## ◆ p_bits()

size_t Botan::DL_Group::p_bits | ( |  | ) | const

Return the size of p in bits Same as get_p().bits()

Definition at line 451 of file dl_group.cpp.

452 {
453 return data().p_bits();
454 }

Referenced by Botan::DH_PrivateKey::DH_PrivateKey(), Botan::ElGamal_PrivateKey::ElGamal_PrivateKey(), and Botan::DL_Scheme_PublicKey::key_length().

## ◆ p_bytes()

size_t Botan::DL_Group::p_bytes | ( |  | ) | const

Return the size of p in bytes Same as get_p().bytes()

Definition at line 456 of file dl_group.cpp.

457 {
458 return data().p_bytes();
459 }

Referenced by Botan::srp6_client_agree().

## ◆ PEM_decode()

void Botan::DL_Group::PEM_decode | ( | const std::string & | pem | ) |

Decode a PEM encoded group into this instance.

Parameters

  pem | the PEM encoding of the group

Definition at line 629 of file dl_group.cpp.

630 {
631 std::string label;
632 const std::vector<uint8_t> ber = unlock(PEM_Code::decode(pem, label));
633 Format format = pem_label_to_dl_format(label);
634
635 m_data = BER_decode_DL_group(ber.data(), ber.size(), format, DL_Group_Source::ExternalSource);
636 }

References Botan::PEM_Code::decode(), Botan::ExternalSource, and Botan::unlock().

## ◆ 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 593 of file dl_group.cpp.

594 {
595 const std::vector<uint8_t> encoding = DER_encode(format);
596
597 if(format == PKCS_3)
598 return PEM_Code::encode(encoding, "DH PARAMETERS");
599 else if(format == ANSI_X9_57)
600 return PEM_Code::encode(encoding, "DSA PARAMETERS");
601 else if(format == ANSI_X9_42)
602 return PEM_Code::encode(encoding, "X9.42 DH PARAMETERS");
603 else
604 throw Invalid_Argument("Unknown DL_Group encoding " + std::to_string(format));
605 }
Botan::DL_Group::DER_encode
std::vector< uint8_t > DER_encode(Format format) const
Definition: dl_group.cpp:553
Botan::PEM_Code::encode
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43

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

Referenced by PEM_for_named_group().

## ◆ PEM_for_named_group()

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

Return PEM representation of named DL group

Definition at line 639 of file dl_group.cpp.

640 {
641 DL_Group group(name);
642 DL_Group::Format format = group.get_q().is_zero() ? DL_Group::PKCS_3 : DL_Group::ANSI_X9_42;
643 return group.PEM_encode(format);
644 }

References ANSI_X9_42, get_q(), Botan::BigInt::is_zero(), name, PEM_encode(), and PKCS_3.

## ◆ power_g_p() [1/2]

BigInt Botan::DL_Group::power_g_p | ( | const BigInt & | x | ) | const

Modular exponentiation

Warning
  this function leaks the size of x via the number of loop iterations. Use the version taking the maximum size to avoid this.

Returns
  (g^x) % p

Definition at line 535 of file dl_group.cpp.

536 {
537 return data().power_g_p(x, x.bits());
538 }

References Botan::BigInt::bits().

Referenced by Botan::DH_PrivateKey::DH_PrivateKey(), Botan::DSA_PrivateKey::DSA_PrivateKey(), Botan::ElGamal_PrivateKey::ElGamal_PrivateKey(), Botan::generate_srp6_verifier(), Botan::srp6_client_agree(), Botan::SRP6_Server_Session::step1(), verify_element_pair(), and verify_group().

## ◆ power_g_p() [2/2]

BigInt Botan::DL_Group::power_g_p | ( | const BigInt & | x,
|  | size_t | max_x_bits
| ) |  | const

Modular exponentiation

Parameters

  x | the exponent
  max_x_bits | x is assumed to be at most this many bits long.

Returns
  (g^x) % p

Definition at line 540 of file dl_group.cpp.

541 {
542 return data().power_g_p(x, max_x_bits);
543 }

## ◆ q_bits()

size_t Botan::DL_Group::q_bits | ( |  | ) | const

Return the size of q in bits Same as get_q().bits() Throws if q is unset

Definition at line 461 of file dl_group.cpp.

462 {
463 data().assert_q_is_set("q_bits");
464 return data().q_bits();
465 }

Referenced by Botan::DSA_PrivateKey::DSA_PrivateKey().

## ◆ q_bytes()

size_t Botan::DL_Group::q_bytes | ( |  | ) | const

Return the size of q in bytes Same as get_q().bytes() Throws if q is unset

Definition at line 467 of file dl_group.cpp.

468 {
469 data().assert_q_is_set("q_bytes");
470 return data().q_bytes();
471 }

## ◆ source()

DL_Group_Source Botan::DL_Group::source | ( |  | ) | const

Definition at line 545 of file dl_group.cpp.

546 {
547 return data().source();
548 }

Referenced by verify_group().

## ◆ square_mod_q()

BigInt Botan::DL_Group::square_mod_q | ( | const BigInt & | x | ) | const

Square and reduce an integer modulo q Throws if q is unset on this DL_Group

Returns
  (x*x) % q

Definition at line 524 of file dl_group.cpp.

525 {
526 data().assert_q_is_set("square_mod_q");
527 return data().square_mod_q(x);
528 }

## ◆ verify_element_pair()

bool Botan::DL_Group::verify_element_pair | ( | const BigInt & | y,
|  | const BigInt & | x
| ) |  | const

Verify a pair of elements y = g^x

This verifies that 1 < x,y < p and that y=g^x mod p

Definition at line 364 of file dl_group.cpp.

365 {
366 const BigInt& p = get_p();
367
368 if(y <= 1 || y >= p || x <= 1 || x >= p)
369 return false;
370
371 if(y != power_g_p(x))
372 return false;
373
374 return true;
375 }
Botan::DL_Group::power_g_p
BigInt power_g_p(const BigInt &x) const
Definition: dl_group.cpp:535

References get_p(), and power_g_p().

Referenced by Botan::DL_Scheme_PrivateKey::check_key().

## ◆ verify_group()

bool Botan::DL_Group::verify_group | ( | RandomNumberGenerator & | rng,
|  | bool | strong = `true`
| ) |  | 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 380 of file dl_group.cpp.

382 {
383 const bool from_builtin = (source() == DL_Group_Source::Builtin);
384
385 if(!strong && from_builtin)
386 return true;
387
388 const BigInt& p = get_p();
389 const BigInt& q = get_q();
390 const BigInt& g = get_g();
391
392 if(g < 2 || p < 3 || q < 0)
393 return false;
394
395 const size_t test_prob = 128;
396 const bool is_randomly_generated = (source() != DL_Group_Source::ExternalSource);
397
398 if(q != 0)
399 {
400 if((p - 1) % q != 0)
401 {
402 return false;
403 }
404 if(this->power_g_p(q) != 1)
405 {
406 return false;
407 }
408 if(!is_prime(q, rng, test_prob, is_randomly_generated))
409 {
410 return false;
411 }
412 }
413
414 if(!is_prime(p, rng, test_prob, is_randomly_generated))
415 {
416 return false;
417 }
418
419 return true;
420 }
Botan::DL_Group::source
DL_Group_Source source() const
Definition: dl_group.cpp:545
Botan::DL_Group_Source::Builtin
@ Builtin

References Botan::Builtin, Botan::ExternalSource, get_g(), get_p(), get_q(), Botan::is_prime(), power_g_p(), and source().

Referenced by Botan::DL_Scheme_PublicKey::check_key(), Botan::DL_Scheme_PrivateKey::check_key(), and Botan::TLS::Callbacks::tls_dh_agree().

## ◆ verify_public_element()

bool Botan::DL_Group::verify_public_element | ( | const BigInt & | y | ) | const

Verify a public element, ie check if y = g^x for some x.

This is not a perfect test. It verifies that 1 < y < p and (if q is set) that y is in the subgroup of size q.

Definition at line 347 of file dl_group.cpp.

348 {
349 const BigInt& p = get_p();
350 const BigInt& q = get_q();
351
352 if(y <= 1 || y >= p)
353 return false;
354
355 if(q.is_zero() == false)
356 {
357 if(power_mod(y, q, p) != 1)
358 return false;
359 }
360
361 return true;
362 }
Botan::power_mod
BigInt power_mod(const BigInt &base, const BigInt &exp, const BigInt &mod)
Definition: numthry.cpp:141

References get_p(), get_q(), Botan::BigInt::is_zero(), and Botan::power_mod().

Referenced by Botan::DL_Scheme_PublicKey::check_key().

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

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