Crypto++  6.1
Free C++ class library of cryptographic schemes
nbtheory.h
Go to the documentation of this file.
1 // nbtheory.h - originally written and placed in the public domain by Wei Dai
2 
3 /// \file nbtheory.h
4 /// \brief Classes and functions for number theoretic operations
5 
6 #ifndef CRYPTOPP_NBTHEORY_H
7 #define CRYPTOPP_NBTHEORY_H
8 
9 #include "cryptlib.h"
10 #include "integer.h"
11 #include "algparam.h"
12 
13 NAMESPACE_BEGIN(CryptoPP)
14 
15 // obtain pointer to small prime table and get its size
16 CRYPTOPP_DLL const word16 * CRYPTOPP_API GetPrimeTable(unsigned int &size);
17 
18 // ************ primality testing ****************
19 
20 /// \brief Generates a provable prime
21 /// \param rng a RandomNumberGenerator to produce keying material
22 /// \param bits the number of bits in the prime number
23 /// \returns Integer() meeting Maurer's tests for primality
24 CRYPTOPP_DLL Integer CRYPTOPP_API MaurerProvablePrime(RandomNumberGenerator &rng, unsigned int bits);
25 
26 /// \brief Generates a provable prime
27 /// \param rng a RandomNumberGenerator to produce keying material
28 /// \param bits the number of bits in the prime number
29 /// \returns Integer() meeting Mihailescu's tests for primality
30 /// \details Mihailescu's methods performs a search using algorithmic progressions.
31 CRYPTOPP_DLL Integer CRYPTOPP_API MihailescuProvablePrime(RandomNumberGenerator &rng, unsigned int bits);
32 
33 /// \brief Tests whether a number is a small prime
34 /// \param p a candidate prime to test
35 /// \returns true if p is a small prime, false otherwise
36 /// \details Internally, the library maintains a table fo the first 32719 prime numbers
37 /// in sorted order. IsSmallPrime() searches the table and returns true if p is
38 /// in the table.
39 CRYPTOPP_DLL bool CRYPTOPP_API IsSmallPrime(const Integer &p);
40 
41 ///
42 /// \returns true if p is divisible by some prime less than bound.
43 /// \details TrialDivision() true if p is divisible by some prime less than bound. bound not be
44 /// greater than the largest entry in the prime table, which is 32719.
45 CRYPTOPP_DLL bool CRYPTOPP_API TrialDivision(const Integer &p, unsigned bound);
46 
47 // returns true if p is NOT divisible by small primes
48 CRYPTOPP_DLL bool CRYPTOPP_API SmallDivisorsTest(const Integer &p);
49 
50 // These is no reason to use these two, use the ones below instead
51 CRYPTOPP_DLL bool CRYPTOPP_API IsFermatProbablePrime(const Integer &n, const Integer &b);
52 CRYPTOPP_DLL bool CRYPTOPP_API IsLucasProbablePrime(const Integer &n);
53 
54 CRYPTOPP_DLL bool CRYPTOPP_API IsStrongProbablePrime(const Integer &n, const Integer &b);
55 CRYPTOPP_DLL bool CRYPTOPP_API IsStrongLucasProbablePrime(const Integer &n);
56 
57 // Rabin-Miller primality test, i.e. repeating the strong probable prime test
58 // for several rounds with random bases
59 CRYPTOPP_DLL bool CRYPTOPP_API RabinMillerTest(RandomNumberGenerator &rng, const Integer &w, unsigned int rounds);
60 
61 /// \brief Verifies a prime number
62 /// \param p a candidate prime to test
63 /// \returns true if p is a probable prime, false otherwise
64 /// \details IsPrime() is suitable for testing candidate primes when creating them. Internally,
65 /// IsPrime() utilizes SmallDivisorsTest(), IsStrongProbablePrime() and IsStrongLucasProbablePrime().
66 CRYPTOPP_DLL bool CRYPTOPP_API IsPrime(const Integer &p);
67 
68 /// \brief Verifies a prime number
69 /// \param rng a RandomNumberGenerator for randomized testing
70 /// \param p a candidate prime to test
71 /// \param level the level of thoroughness of testing
72 /// \returns true if p is a strong probable prime, false otherwise
73 /// \details VerifyPrime() is suitable for testing candidate primes created by others. Internally,
74 /// VerifyPrime() utilizes IsPrime() and one-round RabinMillerTest(). If the candiate passes and
75 /// level is greater than 1, then 10 round RabinMillerTest() primality testing is performed.
76 CRYPTOPP_DLL bool CRYPTOPP_API VerifyPrime(RandomNumberGenerator &rng, const Integer &p, unsigned int level = 1);
77 
78 /// \brief Application callback to signal suitability of a cabdidate prime
79 class CRYPTOPP_DLL PrimeSelector
80 {
81 public:
82  const PrimeSelector *GetSelectorPointer() const {return this;}
83  virtual bool IsAcceptable(const Integer &candidate) const =0;
84 };
85 
86 /// \brief Finds a random prime of special form
87 /// \param p an Integer reference to receive the prime
88 /// \param max the maximum value
89 /// \param equiv the equivalence class based on the parameter mod
90 /// \param mod the modulus used to reduce the equivalence class
91 /// \param pSelector pointer to a PrimeSelector function for the application to signal suitability
92 /// \returns true if and only if FirstPrime() finds a prime and returns the prime through p. If FirstPrime()
93 /// returns false, then no such prime exists and the value of p is undefined
94 /// \details FirstPrime() uses a fast sieve to find the first probable prime
95 /// in <tt>{x | p<=x<=max and x%mod==equiv}</tt>
96 CRYPTOPP_DLL bool CRYPTOPP_API FirstPrime(Integer &p, const Integer &max, const Integer &equiv, const Integer &mod, const PrimeSelector *pSelector);
97 
98 CRYPTOPP_DLL unsigned int CRYPTOPP_API PrimeSearchInterval(const Integer &max);
99 
100 CRYPTOPP_DLL AlgorithmParameters CRYPTOPP_API MakeParametersForTwoPrimesOfEqualSize(unsigned int productBitLength);
101 
102 // ********** other number theoretic functions ************
103 
104 inline Integer GCD(const Integer &a, const Integer &b)
105  {return Integer::Gcd(a,b);}
106 inline bool RelativelyPrime(const Integer &a, const Integer &b)
107  {return Integer::Gcd(a,b) == Integer::One();}
108 inline Integer LCM(const Integer &a, const Integer &b)
109  {return a/Integer::Gcd(a,b)*b;}
110 inline Integer EuclideanMultiplicativeInverse(const Integer &a, const Integer &b)
111  {return a.InverseMod(b);}
112 
113 // use Chinese Remainder Theorem to calculate x given x mod p and x mod q, and u = inverse of p mod q
114 CRYPTOPP_DLL Integer CRYPTOPP_API CRT(const Integer &xp, const Integer &p, const Integer &xq, const Integer &q, const Integer &u);
115 
116 // if b is prime, then Jacobi(a, b) returns 0 if a%b==0, 1 if a is quadratic residue mod b, -1 otherwise
117 // check a number theory book for what Jacobi symbol means when b is not prime
118 CRYPTOPP_DLL int CRYPTOPP_API Jacobi(const Integer &a, const Integer &b);
119 
120 // calculates the Lucas function V_e(p, 1) mod n
121 CRYPTOPP_DLL Integer CRYPTOPP_API Lucas(const Integer &e, const Integer &p, const Integer &n);
122 // calculates x such that m==Lucas(e, x, p*q), p q primes, u=inverse of p mod q
123 CRYPTOPP_DLL Integer CRYPTOPP_API InverseLucas(const Integer &e, const Integer &m, const Integer &p, const Integer &q, const Integer &u);
124 
125 inline Integer ModularExponentiation(const Integer &a, const Integer &e, const Integer &m)
126  {return a_exp_b_mod_c(a, e, m);}
127 // returns x such that x*x%p == a, p prime
128 CRYPTOPP_DLL Integer CRYPTOPP_API ModularSquareRoot(const Integer &a, const Integer &p);
129 // returns x such that a==ModularExponentiation(x, e, p*q), p q primes,
130 // and e relatively prime to (p-1)*(q-1)
131 // dp=d%(p-1), dq=d%(q-1), (d is inverse of e mod (p-1)*(q-1))
132 // and u=inverse of p mod q
133 CRYPTOPP_DLL Integer CRYPTOPP_API ModularRoot(const Integer &a, const Integer &dp, const Integer &dq, const Integer &p, const Integer &q, const Integer &u);
134 
135 // find r1 and r2 such that ax^2 + bx + c == 0 (mod p) for x in {r1, r2}, p prime
136 // returns true if solutions exist
137 CRYPTOPP_DLL bool CRYPTOPP_API SolveModularQuadraticEquation(Integer &r1, Integer &r2, const Integer &a, const Integer &b, const Integer &c, const Integer &p);
138 
139 // returns log base 2 of estimated number of operations to calculate discrete log or factor a number
140 CRYPTOPP_DLL unsigned int CRYPTOPP_API DiscreteLogWorkFactor(unsigned int bitlength);
141 CRYPTOPP_DLL unsigned int CRYPTOPP_API FactoringWorkFactor(unsigned int bitlength);
142 
143 // ********************************************************
144 
145 /// \brief Generator of prime numbers of special forms
146 class CRYPTOPP_DLL PrimeAndGenerator
147 {
148 public:
149  /// \brief Construct a PrimeAndGenerator
151 
152  /// \brief Construct a PrimeAndGenerator
153  /// \param delta +1 or -1
154  /// \param rng a RandomNumberGenerator derived class
155  /// \param pbits the number of bits in the prime p
156  /// \details PrimeAndGenerator() generates a random prime p of the form <tt>2*q+delta</tt>, where delta is 1 or -1 and q is
157  /// also prime. Internally the constructor calls <tt>Generate(delta, rng, pbits, pbits-1)</tt>.
158  /// \pre <tt>pbits > 5</tt>
159  /// \warning This PrimeAndGenerator() is slow because primes of this form are harder to find.
160  PrimeAndGenerator(signed int delta, RandomNumberGenerator &rng, unsigned int pbits)
161  {Generate(delta, rng, pbits, pbits-1);}
162 
163  /// \brief Construct a PrimeAndGenerator
164  /// \param delta +1 or -1
165  /// \param rng a RandomNumberGenerator derived class
166  /// \param pbits the number of bits in the prime p
167  /// \param qbits the number of bits in the prime q
168  /// \details PrimeAndGenerator() generates a random prime p of the form <tt>2*r*q+delta</tt>, where q is also prime.
169  /// Internally the constructor calls <tt>Generate(delta, rng, pbits, qbits)</tt>.
170  /// \pre <tt>qbits > 4 && pbits > qbits</tt>
171  PrimeAndGenerator(signed int delta, RandomNumberGenerator &rng, unsigned int pbits, unsigned qbits)
172  {Generate(delta, rng, pbits, qbits);}
173 
174  /// \brief Generate a Prime and Generator
175  /// \param delta +1 or -1
176  /// \param rng a RandomNumberGenerator derived class
177  /// \param pbits the number of bits in the prime p
178  /// \param qbits the number of bits in the prime q
179  /// \details Generate() generates a random prime p of the form <tt>2*r*q+delta</tt>, where q is also prime.
180  void Generate(signed int delta, RandomNumberGenerator &rng, unsigned int pbits, unsigned qbits);
181 
182  /// \brief Retrieve first prime
183  /// \returns Prime() returns the prime p.
184  const Integer& Prime() const {return p;}
185 
186  /// \brief Retrieve second prime
187  /// \returns SubPrime() returns the prime q.
188  const Integer& SubPrime() const {return q;}
189 
190  /// \brief Retrieve the generator
191  /// \returns Generator() returns the the generator g.
192  const Integer& Generator() const {return g;}
193 
194 private:
195  Integer p, q, g;
196 };
197 
198 NAMESPACE_END
199 
200 #endif
Classes for working with NameValuePairs.
bool FirstPrime(Integer &p, const Integer &max, const Integer &equiv, const Integer &mod, const PrimeSelector *pSelector)
Finds a random prime of special form.
Definition: nbtheory.cpp:379
static Integer Gcd(const Integer &a, const Integer &n)
greatest common divisor
Definition: integer.cpp:4373
Abstract base classes that provide a uniform interface to this library.
Integer MaurerProvablePrime(RandomNumberGenerator &rng, unsigned int bits)
Generates a provable prime.
Definition: nbtheory.cpp:510
bool IsSmallPrime(const Integer &p)
Tests whether a number is a small prime.
Definition: nbtheory.cpp:60
Interface for random number generators.
Definition: cryptlib.h:1330
PrimeAndGenerator(signed int delta, RandomNumberGenerator &rng, unsigned int pbits)
Construct a PrimeAndGenerator.
Definition: nbtheory.h:160
Generator of prime numbers of special forms.
Definition: nbtheory.h:146
static const Integer & One()
Integer representing 1.
Definition: integer.cpp:4800
Integer MihailescuProvablePrime(RandomNumberGenerator &rng, unsigned int bits)
Generates a provable prime.
Definition: nbtheory.cpp:470
const Integer & SubPrime() const
Retrieve second prime.
Definition: nbtheory.h:188
const Integer & Prime() const
Retrieve first prime.
Definition: nbtheory.h:184
bool VerifyPrime(RandomNumberGenerator &rng, const Integer &p, unsigned int level=1)
Verifies a prime number.
Definition: nbtheory.cpp:247
Application callback to signal suitability of a cabdidate prime.
Definition: nbtheory.h:79
Multiple precision integer with arithmetic operations.
Definition: integer.h:49
bool IsPrime(const Integer &p)
Verifies a prime number.
Definition: nbtheory.cpp:237
PrimeAndGenerator(signed int delta, RandomNumberGenerator &rng, unsigned int pbits, unsigned qbits)
Construct a PrimeAndGenerator.
Definition: nbtheory.h:171
bool TrialDivision(const Integer &p, unsigned bound)
Definition: nbtheory.cpp:71
An object that implements NameValuePairs.
Definition: algparam.h:419
Multiple precision integer with arithmetic operations.
Crypto++ library namespace.
PrimeAndGenerator()
Construct a PrimeAndGenerator.
Definition: nbtheory.h:150
const Integer & Generator() const
Retrieve the generator.
Definition: nbtheory.h:192