/security/nss/lib/freebl/mpi/utils/README

http://github.com/zpao/v8monkey · #! · 241 lines · 170 code · 71 blank · 0 comment · 0 complexity · c4228e73b827581b968581e168466a91 MD5 · raw file

  1. ***** BEGIN LICENSE BLOCK *****
  2. Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3. The contents of this file are subject to the Mozilla Public License Version
  4. 1.1 (the "License"); you may not use this file except in compliance with
  5. the License. You may obtain a copy of the License at
  6. http://www.mozilla.org/MPL/
  7. Software distributed under the License is distributed on an "AS IS" basis,
  8. WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  9. for the specific language governing rights and limitations under the
  10. License.
  11. The Original Code is the MPI Arbitrary Precision Integer Arithmetic
  12. library.
  13. The Initial Developer of the Original Code is
  14. Michael J. Fromberger <sting@linguist.dartmouth.edu>
  15. Portions created by the Initial Developer are Copyright (C) 1998, 2000
  16. the Initial Developer. All Rights Reserved.
  17. Contributor(s):
  18. Alternatively, the contents of this file may be used under the terms of
  19. either the GNU General Public License Version 2 or later (the "GPL"), or
  20. the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  21. in which case the provisions of the GPL or the LGPL are applicable instead
  22. of those above. If you wish to allow use of your version of this file only
  23. under the terms of either the GPL or the LGPL, and not to allow others to
  24. use your version of this file under the terms of the MPL, indicate your
  25. decision by deleting the provisions above and replace them with the notice
  26. and other provisions required by the GPL or the LGPL. If you do not delete
  27. the provisions above, a recipient may use your version of this file under
  28. the terms of any one of the MPL, the GPL or the LGPL.
  29. ***** END LICENSE BLOCK *****
  30. Additional MPI utilities
  31. ------------------------
  32. The files 'mpprime.h' and 'mpprime.c' define some useful extensions to
  33. the MPI library for dealing with prime numbers (in particular, testing
  34. for divisbility, and the Rabin-Miller probabilistic primality test).
  35. The files 'mplogic.h' and 'mplogic.c' define extensions to the MPI
  36. library for doing bitwise logical operations and shifting.
  37. This document assumes you have read the help file for the MPI library
  38. and understand its conventions.
  39. Divisibility (mpprime.h)
  40. ------------
  41. To test a number for divisibility by another number:
  42. mpp_divis(a, b) - test if b|a
  43. mpp_divis_d(a, d) - test if d|a
  44. Each of these functions returns MP_YES if its initial argument is
  45. divisible by its second, or MP_NO if it is not. Other errors may be
  46. returned as appropriate (such as MP_RANGE if you try to test for
  47. divisibility by zero).
  48. Randomness (mpprime.h)
  49. ----------
  50. To generate random data:
  51. mpp_random(a) - fill a with random data
  52. mpp_random_size(a, p) - fill a with p digits of random data
  53. The mpp_random_size() function increases the precision of a to at
  54. least p, then fills all those digits randomly. The mp_random()
  55. function fills a to its current precision (as determined by the number
  56. of significant digits, USED(a))
  57. Note that these functions simply use the C library's rand() function
  58. to fill a with random digits up to its precision. This should be
  59. adequate for primality testing, but should not be used for
  60. cryptographic applications where truly random values are required for
  61. security.
  62. You should call srand() in your driver program in order to seed the
  63. random generator; this function doesn't call it.
  64. Primality Testing (mpprime.h)
  65. -----------------
  66. mpp_divis_vector(a, v, s, w) - is a divisible by any of the s values
  67. in v, and if so, w = which.
  68. mpp_divis_primes(a, np) - is a divisible by any of the first np primes?
  69. mpp_fermat(a, w) - is a pseudoprime with respect to witness w?
  70. mpp_pprime(a, nt) - run nt iterations of Rabin-Miller on a.
  71. The mpp_divis_vector() function tests a for divisibility by each
  72. member of an array of digits. The array is v, the size of that array
  73. is s. Returns MP_YES if a is divisible, and stores the index of the
  74. offending digit in w. Returns MP_NO if a is not divisible by any of
  75. the digits in the array.
  76. A small table of primes is compiled into the library (typically the
  77. first 128 primes, although you can change this by editing the file
  78. 'primes.c' before you build). The global variable prime_tab_size
  79. contains the number of primes in the table, and the values themselves
  80. are in the array prime_tab[], which is an array of mp_digit.
  81. The mpp_divis_primes() function is basically just a wrapper around
  82. mpp_divis_vector() that uses prime_tab[] as the test vector. The np
  83. parameter is a pointer to an mp_digit -- on input, it should specify
  84. the number of primes to be tested against. If a is divisible by any
  85. of the primes, MP_YES is returned and np is given the prime value that
  86. divided a (you can use this if you're factoring, for example).
  87. Otherwise, MP_NO is returned and np is untouched.
  88. The function mpp_fermat() performs Fermat's test, using w as a
  89. witness. This test basically relies on the fact that if a is prime,
  90. and w is relatively prime to a, then:
  91. w^a = w (mod a)
  92. That is,
  93. w^(a - 1) = 1 (mod a)
  94. The function returns MP_YES if the test passes, MP_NO if it fails. If
  95. w is relatively prime to a, and the test fails, a is definitely
  96. composite. If w is relatively prime to a and the test passes, then a
  97. is either prime, or w is a false witness (the probability of this
  98. happening depends on the choice of w and of a ... consult a number
  99. theory textbook for more information about this).
  100. Note: If (w, a) != 1, the output of this test is meaningless.
  101. ----
  102. The function mpp_pprime() performs the Rabin-Miller probabilistic
  103. primality test for nt rounds. If all the tests pass, MP_YES is
  104. returned, and a is probably prime. The probability that an answer of
  105. MP_YES is incorrect is no greater than 1 in 4^nt, and in fact is
  106. usually much less than that (this is a pessimistic estimate). If any
  107. test fails, MP_NO is returned, and a is definitely composite.
  108. Bruce Schneier recommends at least 5 iterations of this test for most
  109. cryptographic applications; Knuth suggests that 25 are reasonable.
  110. Run it as many times as you feel are necessary.
  111. See the programs 'makeprime.c' and 'isprime.c' for reasonable examples
  112. of how to use these functions for primality testing.
  113. Bitwise Logic (mplogic.c)
  114. -------------
  115. The four commonest logical operations are implemented as:
  116. mpl_not(a, b) - Compute bitwise (one's) complement, b = ~a
  117. mpl_and(a, b, c) - Compute bitwise AND, c = a & b
  118. mpl_or(a, b, c) - Compute bitwise OR, c = a | b
  119. mpl_xor(a, b, c) - Compute bitwise XOR, c = a ^ b
  120. Left and right shifts are available as well. These take a number to
  121. shift, a destination, and a shift amount. The shift amount must be a
  122. digit value between 0 and DIGIT_BIT inclusive; if it is not, MP_RANGE
  123. will be returned and the shift will not happen.
  124. mpl_rsh(a, b, d) - Compute logical right shift, b = a >> d
  125. mpl_lsh(a, b, d) - Compute logical left shift, b = a << d
  126. Since these are logical shifts, they fill with zeroes (the library
  127. uses a signed magnitude representation, so there are no sign bits to
  128. extend anyway).
  129. Command-line Utilities
  130. ----------------------
  131. A handful of interesting command-line utilities are provided. These
  132. are:
  133. lap.c - Find the order of a mod m. Usage is 'lap <a> <m>'.
  134. This uses a dumb algorithm, so don't use it for
  135. a really big modulus.
  136. invmod.c - Find the inverse of a mod m, if it exists. Usage
  137. is 'invmod <a> <m>'
  138. sieve.c - A simple bitmap-based implementation of the Sieve
  139. of Eratosthenes. Used to generate the table of
  140. primes in primes.c. Usage is 'sieve <nbits>'
  141. prng.c - Uses the routines in bbs_rand.{h,c} to generate
  142. one or more 32-bit pseudo-random integers. This
  143. is mainly an example, not intended for use in a
  144. cryptographic application (the system time is
  145. the only source of entropy used)
  146. dec2hex.c - Convert decimal to hexadecimal
  147. hex2dec.c - Convert hexadecimal to decimal
  148. basecvt.c - General radix conversion tool (supports 2-64)
  149. isprime.c - Probabilistically test an integer for primality
  150. using the Rabin-Miller pseudoprime test combined
  151. with division by small primes.
  152. primegen.c - Generate primes at random.
  153. exptmod.c - Perform modular exponentiation
  154. ptab.pl - A Perl script to munge the output of the sieve
  155. program into a compilable C structure.
  156. Other Files
  157. -----------
  158. PRIMES - Some randomly generated numbers which are prime with
  159. extremely high probability.
  160. README - You're reading me already.
  161. About the Author
  162. ----------------
  163. This software was written by Michael J. Fromberger. You can contact
  164. the author as follows:
  165. E-mail: <sting@linguist.dartmouth.edu>
  166. Postal: 8000 Cummings Hall, Thayer School of Engineering
  167. Dartmouth College, Hanover, New Hampshire, USA
  168. PGP key: http://linguist.dartmouth.edu/~sting/keys/mjf.html
  169. 9736 188B 5AFA 23D6 D6AA BE0D 5856 4525 289D 9907
  170. Last updated: $Id: README,v 1.3 2005/02/02 22:28:23 gerv%gerv.net Exp $