git.distorted.org.uk Git - u/mdw/catacomb/blob - rho.h

   1 /* -*-c-*-
   2  *
   3  * $Id: rho.h,v 1.2 2004/04/02 01:03:49 mdw Exp $
   4  *
   5  * Pollard's rho algorithm for discrete logs
   6  *
   7  * (c) 2000 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of Catacomb.
  13  *
  14  * Catacomb is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU Library General Public License as
  16  * published by the Free Software Foundation; either version 2 of the
  17  * License, or (at your option) any later version.
  18  *
  19  * Catacomb is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with Catacomb; if not, write to the Free
  26  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  27  * MA 02111-1307, USA.
  28  */
  29
  30 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: rho.h,v $
  33  * Revision 1.2  2004/04/02 01:03:49  mdw
  34  * Miscellaneous constification.
  35  *
  36  * Revision 1.1  2000/07/09 21:32:30  mdw
  37  * Pollard's rho algorithm for computing discrete logs.
  38  *
  39  */
  40
  41 #ifndef CATACOMB_RHO_H
  42 #define CATACOMB_RHO_H
  43
  44 #ifdef __cplusplus
  45   extern "C" {
  46 #endif
  47
  48 /*----- Header files ------------------------------------------------------*/
  49
  50 #ifndef CATACOMB_MP_H
  51 #  include "mp.h"
  52 #endif
  53
  54 /*----- Data structures ---------------------------------------------------*/
  55
  56 /* --- The group operations table --- */
  57
  58 typedef struct rho_ops {
  59   void (*sqr)(void *x, void *c);
  60   void (*mul)(void *x, void *y, void *c);
  61   int (*eq)(void *x, void *y);
  62   int (*split)(void *x);
  63   void (*drop)(void *x);
  64 } rho_ops;
  65
  66 /* --- The Pollard's rho context structure --- */
  67
  68 typedef struct rho_ctx {
  69   const rho_ops *ops;                   /* Group operations table */
  70   void *c;                              /* Context for group operations */
  71   void *g, *a;                          /* Generator and argument for log */
  72   mp *n;                                /* Cyclic group order */
  73 } rho_ctx;
  74
  75 /*----- Functions provided ------------------------------------------------*/
  76
  77 /* --- @rho@ --- *
  78  *
  79  * Arguments:   @rho_ctx *cc@ = pointer to the context structure
  80  *              @void *x, *y@ = two (equal) base values (try 1)
  81  *              @mp *a, *b@ = logs of %$x$% (see below)
  82  *
  83  * Returns:     The discrete logarithm %$\log_g a$%, or null if the algorithm
  84  *              failed.  (This is unlikely, though possible.)
  85  *
  86  * Use:         Uses Pollard's rho algorithm to compute discrete logs in the
  87  *              group %$G$% generated by %$g$%.
  88  *
  89  *              The algorithm works by finding a cycle in a pseudo-random
  90  *              walk.  The function @ops->split@ should return an element
  91  *              from %$\{\,0, 1, 2\,\}$% according to its argument, in order
  92  *              to determine the walk.  At each step in the walk, we know a
  93  *              group element %$x \in G$% together with its representation as
  94  *              a product of powers of %$g$% and $%a$% (i.e., we know that
  95  *              %$x = g^\alpha a^\beta$% for some %$\alpha$%, %$\beta$%).
  96  *
  97  *              Locating a cycle gives us a collision
  98  *
  99  *                %$g^{\alpha} a^{\beta} = g^{\alpha'} a^{\beta'}$%
 100  *
 101  *              Taking logs of both sides (to base %$g$%) gives us that
 102  *
 103  *                %$\log a\equiv\frac{\alpha-\alpha'}{\beta'-\beta}\bmod{n}$%
 104  *
 105  *              Good initial values are %$x = y = 1$% (the multiplicative
 106  *              identity of %$G$%) and %$\alpha\equiv\beta\equiv0\bmod{n}$%.
 107  *              If that doesn't work then start choosing more `interesting'
 108  *              values.
 109  *
 110  *              Note that the algorithm requires minimal space but
 111  *              %$O(\sqrt{n})$% time.  Don't do this on large groups,
 112  *              particularly if you can find a decent factor base.
 113  *
 114  *              Finally, note that this function will free the input values
 115  *              when it's finished with them.  This probably isn't a great
 116  *              problem.
 117  */
 118
 119 extern mp *rho(rho_ctx */*cc*/, void */*x*/, void */*y*/,
 120                mp */*a*/, mp */*b*/);
 121
 122 /* --- @rho_prime@ --- *
 123  *
 124  * Arguments:   @mp *g@ = generator for the group
 125  *              @mp *a@ = value to find the logarithm of
 126  *              @mp *n@ = order of the group
 127  *              @mp *p@ = prime size of the underlying prime field
 128  *
 129  * Returns:     The discrete logarithm %$\log_g a$%.
 130  *
 131  * Use:         Computes discrete logarithms in a subgroup of a prime field.
 132  */
 133
 134 extern mp *rho_prime(mp */*g*/, mp */*a*/, mp */*n*/, mp */*p*/);
 135
 136 /*----- That's all, folks -------------------------------------------------*/
 137
 138 #ifdef __cplusplus
 139   }
 140 #endif
 141
 142 #endif