math/mpreduce.h: Missing include files.

[u/mdw/catacomb] / math / rho.h

/* -*-c-*-
 *
 * Pollard's rho algorithm for discrete logs
 *
 * (c) 2000 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * Catacomb is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

#ifndef CATACOMB_RHO_H
#define CATACOMB_RHO_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#ifndef CATACOMB_MP_H
#  include "mp.h"
#endif

/*----- Data structures ---------------------------------------------------*/

/* --- The group operations table --- */

typedef struct rho_ops {
  void (*sqr)(void *x, void *c);
  void (*mul)(void *x, void *y, void *c);
  int (*eq)(void *x, void *y);
  int (*split)(void *x);
  void (*drop)(void *x);
} rho_ops;

/* --- The Pollard's rho context structure --- */

typedef struct rho_ctx {
  const rho_ops *ops;			/* Group operations table */
  void *c;				/* Context for group operations */
  void *g, *a;				/* Generator and argument for log */
  mp *n;				/* Cyclic group order */
} rho_ctx;

/*----- Functions provided ------------------------------------------------*/

/* --- @rho@ --- *
 *
 * Arguments:	@rho_ctx *cc@ = pointer to the context structure
 *		@void *x, *y@ = two (equal) base values (try 1)
 *		@mp *a, *b@ = logs of %$x$% (see below)
 *
 * Returns:	The discrete logarithm %$\log_g a$%, or null if the algorithm
 *		failed.  (This is unlikely, though possible.)
 *
 * Use:		Uses Pollard's rho algorithm to compute discrete logs in the
 *		group %$G$% generated by %$g$%.
 *
 *		The algorithm works by finding a cycle in a pseudo-random
 *		walk.  The function @ops->split@ should return an element
 *		from %$\{\,0, 1, 2\,\}$% according to its argument, in order
 *		to determine the walk.  At each step in the walk, we know a
 *		group element %$x \in G$% together with its representation as
 *		a product of powers of %$g$% and $%a$% (i.e., we know that
 *		%$x = g^\alpha a^\beta$% for some %$\alpha$%, %$\beta$%).
 *
 *		Locating a cycle gives us a collision
 *
 *		  %$g^{\alpha} a^{\beta} = g^{\alpha'} a^{\beta'}$%
 *
 *		Taking logs of both sides (to base %$g$%) gives us that
 *
 *		  %$\log a\equiv\frac{\alpha-\alpha'}{\beta'-\beta}\bmod{n}$%
 *
 *		Good initial values are %$x = y = 1$% (the multiplicative
 *		identity of %$G$%) and %$\alpha\equiv\beta\equiv0\bmod{n}$%.
 *		If that doesn't work then start choosing more `interesting'
 *		values.
 *
 *		Note that the algorithm requires minimal space but
 *		%$O(\sqrt{n})$% time.  Don't do this on large groups,
 *		particularly if you can find a decent factor base.
 *
 *		Finally, note that this function will free the input values
 *		when it's finished with them.  This probably isn't a great
 *		problem.
 */

extern mp *rho(rho_ctx */*cc*/, void */*x*/, void */*y*/,
	       mp */*a*/, mp */*b*/);

/* --- @rho_prime@ --- *
 *
 * Arguments:	@mp *g@ = generator for the group
 *		@mp *a@ = value to find the logarithm of
 *		@mp *n@ = order of the group
 *		@mp *p@ = prime size of the underlying prime field
 *
 * Returns:	The discrete logarithm %$\log_g a$%.
 *
 * Use:		Computes discrete logarithms in a subgroup of a prime field.
 */

extern mp *rho_prime(mp */*g*/, mp */*a*/, mp */*n*/, mp */*p*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif