Botan  1.11.15
src/lib/pubkey/dl_group/dl_group.h
Go to the documentation of this file.
00001 /*
00002 * Discrete Logarithm Group
00003 * (C) 1999-2008 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_DL_PARAM_H__
00009 #define BOTAN_DL_PARAM_H__
00010 
00011 #include <botan/bigint.h>
00012 #include <botan/data_src.h>
00013 
00014 namespace Botan {
00015 
00016 /**
00017 * This class represents discrete logarithm groups. It holds a prime p,
00018 * a prime q = (p-1)/2 and g = x^((p-1)/q) mod p.
00019 */
00020 class BOTAN_DLL DL_Group
00021    {
00022    public:
00023 
00024       /**
00025       * Get the prime p.
00026       * @return prime p
00027       */
00028       const BigInt& get_p() const;
00029 
00030       /**
00031       * Get the prime q.
00032       * @return prime q
00033       */
00034       const BigInt& get_q() const;
00035 
00036       /**
00037       * Get the base g.
00038       * @return base g
00039       */
00040       const BigInt& get_g() const;
00041 
00042       /**
00043       * The DL group encoding format variants.
00044       */
00045       enum Format {
00046          ANSI_X9_42,
00047          ANSI_X9_57,
00048          PKCS_3,
00049 
00050          DSA_PARAMETERS = ANSI_X9_57,
00051          DH_PARAMETERS = ANSI_X9_42,
00052          X942_DH_PARAMETERS = ANSI_X9_42,
00053          PKCS3_DH_PARAMETERS = PKCS_3
00054       };
00055 
00056       /**
00057       * Determine the prime creation for DL groups.
00058       */
00059       enum PrimeType { Strong, Prime_Subgroup, DSA_Kosherizer };
00060 
00061       /**
00062       * Perform validity checks on the group.
00063       * @param rng the rng to use
00064       * @param strong whether to perform stronger by lengthier tests
00065       * @return true if the object is consistent, false otherwise
00066       */
00067       bool verify_group(RandomNumberGenerator& rng, bool strong) const;
00068 
00069       /**
00070       * Encode this group into a string using PEM encoding.
00071       * @param format the encoding format
00072       * @return string holding the PEM encoded group
00073       */
00074       std::string PEM_encode(Format format) const;
00075 
00076       /**
00077       * Encode this group into a string using DER encoding.
00078       * @param format the encoding format
00079       * @return string holding the DER encoded group
00080       */
00081       std::vector<byte> DER_encode(Format format) const;
00082 
00083       /**
00084       * Decode a DER/BER encoded group into this instance.
00085       * @param ber a vector containing the DER/BER encoded group
00086       * @param format the format of the encoded group
00087       */
00088       void BER_decode(const std::vector<byte>& ber,
00089                       Format format);
00090 
00091       /**
00092       * Decode a PEM encoded group into this instance.
00093       * @param pem the PEM encoding of the group
00094       */
00095       void PEM_decode(const std::string& pem);
00096 
00097       /**
00098       * Construct a DL group with uninitialized internal value.
00099       * Use this constructor is you wish to set the groups values
00100       * from a DER or PEM encoded group.
00101       */
00102       DL_Group();
00103 
00104       /**
00105       * Construct a DL group that is registered in the configuration.
00106       * @param name the name that is configured in the global configuration
00107       * for the desired group. If no configuration file is specified,
00108       * the default values from the file policy.cpp will be used. For instance,
00109       * use "modp/ietf/768" as name.
00110       */
00111       DL_Group(const std::string& name);
00112 
00113       /**
00114       * Create a new group randomly.
00115       * @param rng the random number generator to use
00116       * @param type specifies how the creation of primes p and q shall
00117       * be performed. If type=Strong, then p will be determined as a
00118       * safe prime, and q will be chosen as (p-1)/2. If
00119       * type=Prime_Subgroup and qbits = 0, then the size of q will be
00120       * determined according to the estimated difficulty of the DL
00121       * problem. If type=DSA_Kosherizer, DSA primes will be created.
00122       * @param pbits the number of bits of p
00123       * @param qbits the number of bits of q. Leave it as 0 to have
00124       * the value determined according to pbits.
00125       */
00126       DL_Group(RandomNumberGenerator& rng, PrimeType type,
00127                size_t pbits, size_t qbits = 0);
00128 
00129       /**
00130       * Create a DSA group with a given seed.
00131       * @param rng the random number generator to use
00132       * @param seed the seed to use to create the random primes
00133       * @param pbits the desired bit size of the prime p
00134       * @param qbits the desired bit size of the prime q.
00135       */
00136       DL_Group(RandomNumberGenerator& rng,
00137                const std::vector<byte>& seed,
00138                size_t pbits = 1024, size_t qbits = 0);
00139 
00140       /**
00141       * Create a DL group. The prime q will be determined according to p.
00142       * @param p the prime p
00143       * @param g the base g
00144       */
00145       DL_Group(const BigInt& p, const BigInt& g);
00146 
00147       /**
00148       * Create a DL group.
00149       * @param p the prime p
00150       * @param q the prime q
00151       * @param g the base g
00152       */
00153       DL_Group(const BigInt& p, const BigInt& q, const BigInt& g);
00154 
00155       /**
00156       * Return PEM representation of named DL group
00157       */
00158       static const char* PEM_for_named_group(const std::string& name);
00159    private:
00160       static BigInt make_dsa_generator(const BigInt&, const BigInt&);
00161 
00162       void init_check() const;
00163       void initialize(const BigInt&, const BigInt&, const BigInt&);
00164       bool initialized;
00165       BigInt p, q, g;
00166    };
00167 
00168 }
00169 
00170 #endif