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 BigInt &p, const BigInt &g)
	DL_Group (const BigInt &p, const BigInt &q, const BigInt &g)
	DL_Group (const std::string &name)
	DL_Group (RandomNumberGenerator &rng, const MemoryRegion< byte > &seed, size_t pbits=1024, size_t qbits=0)
	DL_Group (RandomNumberGenerator &rng, PrimeType type, size_t pbits, size_t qbits=0)
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.

                  {
         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
      };

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.

{ Strong, Prime_Subgroup, DSA_Kosherizer };

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.

   {
   initialized = false;
   }

Referenced by Botan::TLS_Policy::dh_group(), and Botan::Server_Key_Exchange::key().

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.

   {
   std::string grp_contents = global_state().get("dl", type);
 
   if(grp_contents == "")
      throw Invalid_Argument("DL_Group: Unknown group " + type);
 
   DataSource_Memory pem(grp_contents);
   PEM_decode(pem);
   }

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

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.

   {
   if(pbits < 512)
      throw Invalid_Argument("DL_Group: prime size " + to_string(pbits) +
                             " is too small");
 
   if(type == Strong)
      {
      p = random_safe_prime(rng, pbits);
      q = (p - 1) / 2;
      g = 2;
      }
   else if(type == Prime_Subgroup)
      {
      if(!qbits)
         qbits = 2 * dl_work_factor(pbits);
 
      q = random_prime(rng, qbits);
      BigInt X;
      while(p.bits() != pbits || !check_prime(p, rng))
         {
         X.randomize(rng, pbits);
         p = X - (X % (2*q) - 1);
         }
 
      g = make_dsa_generator(p, q);
      }
   else if(type == DSA_Kosherizer)
      {
      qbits = qbits ? qbits : ((pbits <= 1024) ? 160 : 256);
 
      generate_dsa_primes(rng,
                          global_state().algorithm_factory(),
                          p, q,
                          pbits, qbits);
 
      g = make_dsa_generator(p, q);
      }
 
   initialized = true;
   }

References Botan::check_prime(), Botan::dl_work_factor(), DSA_Kosherizer, Botan::generate_dsa_primes(), Botan::global_state(), Prime_Subgroup, Botan::random_prime(), Botan::random_safe_prime(), Botan::BigInt::randomize(), Strong, and Botan::to_string().

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.

   {
   if(!generate_dsa_primes(rng,
                           global_state().algorithm_factory(),
                           p, q, pbits, qbits, seed))
      throw Invalid_Argument("DL_Group: The seed given does not "
                             "generate a DSA group");
 
   g = make_dsa_generator(p, q);
 
   initialized = true;
   }

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

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.

   {
   initialize(p1, 0, g1);
   }

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.

   {
   initialize(p1, q1, g1);
   }

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.

   {
   BigInt new_p, new_q, new_g;
 
   BER_Decoder decoder(source);
   BER_Decoder ber = decoder.start_cons(SEQUENCE);
 
   if(format == ANSI_X9_57)
      {
      ber.decode(new_p)
         .decode(new_q)
         .decode(new_g)
         .verify_end();
      }
   else if(format == ANSI_X9_42)
      {
      ber.decode(new_p)
         .decode(new_g)
         .decode(new_q)
         .discard_remaining();
      }
   else if(format == PKCS_3)
      {
      ber.decode(new_p)
         .decode(new_g)
         .discard_remaining();
      }
   else
      throw Invalid_Argument("Unknown DL_Group encoding " + to_string(format));
 
   initialize(new_p, new_q, new_g);
   }

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().

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.

   {
   init_check();
 
   if((q == 0) && (format != PKCS_3))
      throw Encoding_Error("The ANSI DL parameter formats require a subgroup");
 
   if(format == ANSI_X9_57)
      {
      return DER_Encoder()
         .start_cons(SEQUENCE)
            .encode(p)
            .encode(q)
            .encode(g)
         .end_cons()
      .get_contents();
      }
   else if(format == ANSI_X9_42)
      {
      return DER_Encoder()
         .start_cons(SEQUENCE)
            .encode(p)
            .encode(g)
            .encode(q)
         .end_cons()
      .get_contents();
      }
   else if(format == PKCS_3)
      {
      return DER_Encoder()
         .start_cons(SEQUENCE)
            .encode(p)
            .encode(g)
         .end_cons()
      .get_contents();
      }
 
   throw Invalid_Argument("Unknown DL_Group encoding " + to_string(format));
   }

References ANSI_X9_42, ANSI_X9_57, Botan::DER_Encoder::encode(), Botan::Encoding_Error::Encoding_Error(), 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().

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.

   {
   init_check();
   return g;
   }

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

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.

   {
   init_check();
   return p;
   }

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

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.

   {
   init_check();
   if(q == 0)
      throw Invalid_State("DLP group has no q prime specified");
   return q;
   }

References Botan::Invalid_State::Invalid_State().

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.

   {
   std::string label;
   DataSource_Memory ber(PEM_Code::decode(source, label));
 
   if(label == "DH PARAMETERS")
      BER_decode(ber, PKCS_3);
   else if(label == "DSA PARAMETERS")
      BER_decode(ber, ANSI_X9_57);
   else if(label == "X942 DH PARAMETERS")
      BER_decode(ber, ANSI_X9_42);
   else
      throw Decoding_Error("DL_Group: Invalid PEM label " + label);
   }

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

Referenced by DL_Group().

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.

   {
   SecureVector<byte> encoding = DER_encode(format);
   if(format == PKCS_3)
      return PEM_Code::encode(encoding, "DH PARAMETERS");
   else if(format == ANSI_X9_57)
      return PEM_Code::encode(encoding, "DSA PARAMETERS");
   else if(format == ANSI_X9_42)
      return PEM_Code::encode(encoding, "X942 DH PARAMETERS");
   else
      throw Invalid_Argument("Unknown DL_Group encoding " + to_string(format));
   }

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

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.

   {
   init_check();
 
   if(g < 2 || p < 3 || q < 0)
      return false;
   if((q != 0) && ((p - 1) % q != 0))
      return false;
 
   if(!strong)
      return true;
 
   if(!check_prime(p, rng))
      return false;
   if((q > 0) && !check_prime(q, rng))
      return false;
   return true;
   }

References Botan::check_prime().

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

---

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