[svn] gcry - r1140 - trunk/doc

[svn author mo]

Author: mo
Date: 2005-11-26 16:58:08 +0100 (Sat, 26 Nov 2005)
New Revision: 1140

Modified:
   trunk/doc/ChangeLog
   trunk/doc/gcrypt.texi
Log:
2005-11-26  Moritz Schulte  <moritz at g10code.com>

	* gcrypt.texi: New chapter: Prime numbers.


Modified: trunk/doc/ChangeLog
===================================================================
--- trunk/doc/ChangeLog	2005-11-26 11:52:56 UTC (rev 1139)
+++ trunk/doc/ChangeLog	2005-11-26 15:58:08 UTC (rev 1140)
@@ -1,3 +1,7 @@
+2005-11-26  Moritz Schulte  <moritz at g10code.com>
+
+	* gcrypt.texi: New chapter: Prime numbers.
+
 2005-11-12  Moritz Schulte  <moritz at g10code.com>
 
 	* gcrypt.texi (MPI formats): Document that for gcry_mpi_scan and

Modified: trunk/doc/gcrypt.texi
===================================================================
--- trunk/doc/gcrypt.texi	2005-11-26 11:52:56 UTC (rev 1139)
+++ trunk/doc/gcrypt.texi	2005-11-26 15:58:08 UTC (rev 1140)
@@ -71,6 +71,7 @@
 * Random Numbers::               How to work with random numbers.
 * S-expressions::                How to manage S-expressions.
 * MPI library::                  How to work with multi-precision-integers.
+* Prime numbers::                How to use the Prime number related functions.
 * Utilities::                    Utility functions.
 
 Appendices
@@ -155,6 +156,10 @@
 * Bit manipulations::           How to access single bits of MPI values.
 * Miscellaneous::               Miscellaneous MPI functions.
 
+Prime numbers
+* Generation::                  Generation of new prime numbers.
+* Checking::                    Checking if a given number is prime.
+
 Utilities
 * Memory allocation::           Functions related with memory allocation.
 
@@ -3914,11 +3919,65 @@
 boundary.
 @end deftypefun
 
+ at c **********************************************************
+ at c ******************** Prime numbers ***********************
+ at c **********************************************************
+ at node Prime numbers
+ at chapter Prime numbers
+
+ at menu
+* Generation::                  Generation of new prime numbers.
+* Checking::                    Checking if a given number is prime.
+ at end menu
+
+ at node Generation
+ at section Generation
+
+ at deftypefun gcry_error_t gcry_prime_generate (gcry_mpi_t *@var{prime},
+unsigned int @var{prime_bits}, unsigned int @var{factor_bits},
+gcry_mpi_t **@var{factors}, gcry_prime_check_func_t @var{cb_func},
+void *@var{cb_arg}, gcry_random_level_t @var{random_level},
+unsigned int @var{flags})
+
+Generate a new prime number of @var{prime_bits} bits and store it in
+ at var{prime}.  If @var{factor_bits} is non-zero, one of the prime factors
+of (@var{prime} - 1) / 2 must be @var{factor_bits} bits long.  If
+ at var{factors} is non-zero, allocate a new, @code{NULL}-terminated array
+holding the prime factors and store it in @var{factors}.  @var{flags}
+might be used to influence the prime number generation process.
+ at end deftypefun
+
+ at deftypefun gcry_prime_group_generator (gcry_mpi_t *@var{r_g},
+gcry_mpi_t @var{prime}, gcry_mpi_t *@var{factors}, gcry_mpi_t @var{start_g})
+
+Find a generator for @var{prime} where the factorization of (@var{prime}
+- 1) is in the @code{NULL} terminated array @var{factors}.  Return the
+generator as a newly allocated MPI in @var{r_g}.  If @var{start_g} is
+not NULL, use this as the start for the search.
+ at end deftypefun
+
+ at deftypefun void gcry_prime_release_factors (gcry_mpi_t *@var{factors})
+
+Convenience function to release the @var{factors} array.
+ at end deftypefun
+
+ at node Checking
+ at section Checking
+
+ at deftypefun gcry_error_t gcry_prime_check (gcry_mpi_t @var{p},
+unsigned int @var{flags})
+
+Check wether the number @var{p} is prime.  Returns zero in case @var{p}
+is indeed a prime, returns @code{GPG_ERR_NO_PRIME} in case @var{p} is
+not a prime and a different error code in case something went horribly
+wrong.
+ at end deftypefun
+
 @node Utilities
 @chapter Utilities
 
 @menu
-* Memory allocation::           Functions related with memory allocation.
+* Memory allocation:: Functions related with memory allocation.
 @end menu
 
 @node Memory allocation