1/* ecm.h - public interface for libecm. 2 3Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 4Paul Zimmermann, Alexander Kruppa, David Cleaver, Cyril Bouvier. 5 6This file is part of the ECM Library. 7 8The ECM Library is free software; you can redistribute it and/or modify 9it under the terms of the GNU Lesser General Public License as published by 10the Free Software Foundation; either version 3 of the License, or (at your 11option) any later version. 12 13The ECM Library is distributed in the hope that it will be useful, but 14WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 15or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 16License for more details. 17 18You should have received a copy of the GNU Lesser General Public License 19along with the ECM Library; see the file COPYING.LIB. If not, see 20http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 2151 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. */ 22 23#ifndef _ECM_H 24#define _ECM_H 1 25 26#include <stdio.h> /* for FILE */ 27#include <gmp.h> 28 29#undef ECM_VERSION 30 31#ifdef __cplusplus 32extern "C" { 33#endif 34 35#define EC_W_NBUFS 9 /* for Hessian form */ 36 37/* More ec forms */ 38#define ECM_EC_TYPE_MONTGOMERY 1 39#define ECM_EC_TYPE_WEIERSTRASS 2 40#define ECM_EC_TYPE_HESSIAN 3 41#define ECM_EC_TYPE_WEIERSTRASS_COMPLETE 4 42 43/* which type of law used */ 44#define ECM_LAW_AFFINE 1 45#define ECM_LAW_HOMOGENEOUS 2 46 47typedef struct 48{ 49 int type; 50 int law; 51 mpz_t a4; /* for MONTGOMERY: b*y^2=x^3+A*x^2+x 52 for WEIERSTRASS: y^2=x^3+A*x+B 53 for HESSIAN: U^3+V^3+W^3=3*A*U*V*W */ 54 mpz_t a1, a3, a2, a6; /* for complete WEIERSTRASS */ 55 mpz_t buf[EC_W_NBUFS]; /* used in the addition laws */ 56 int disc; /* in case E is known to have CM by Q(sqrt(disc)) */ 57 mpz_t sq[10]; /* for CM curves, we might have squareroots */ 58} __ell_curve_struct; 59typedef __ell_curve_struct ell_curve_t[1]; 60 61typedef struct 62{ 63 mpz_t x; 64 mpz_t y; 65 mpz_t z; 66} __ell_point_struct; 67typedef __ell_point_struct ell_point_t[1]; 68 69typedef struct 70{ 71 int method; /* factorization method, default is ecm */ 72 mpz_t x, y; /* starting point (if non zero) */ 73 int param; /* (ECM only) What parametrization do we used */ 74 mpz_t sigma; /* (ECM only) The parameter for the parametrization */ 75 /* May contains A */ 76 int sigma_is_A; /* if 1, 'parameter' contains A (Montgomery form), 77 if 0, 'parameter' contains sigma (Montgomery form), 78 if -1, 'parameter' contains A, and the input curve is in 79 Weierstrass form y^2 = x^3 + A*x + B, with y in 'go'. */ 80 __ell_curve_struct *E; /* the curve, particularly useful for CM ones */ 81 mpz_t go; /* initial group order to preload (if NULL: do nothing), 82 or y for Weierstrass form if sigma_is_A = -1. */ 83 double B1done; /* step 1 was already done up to B1done */ 84 mpz_t B2min; /* lower bound for stage 2 (default is B1) */ 85 mpz_t B2; /* step 2 bound (chosen automatically if < 0.0) */ 86 unsigned long k;/* number of blocks in stage 2 */ 87 int S; /* degree of the Brent-Suyama's extension for stage 2 */ 88 int repr; /* representation for modular arithmetic: ECM_MOD_MPZ=mpz, 89 ECM_MOD_MODMULN=modmuln (Montgomery's quadratic multiplication), 90 ECM_MOD_REDC=redc (Montgomery's subquadratic multiplication), 91 ECM_MOD_GWNUM=Woltman's gwnum routines (tbd), 92 > 16 : special base-2 representation 93 MOD_DEFAULT: automatic choice */ 94 int nobase2step2; /* disable special base-2 code in ecm stage 2 only */ 95 int verbose; /* verbosity level: 0 no output, 1 normal output, 96 2 diagnostic output */ 97 FILE *os; /* output stream (for verbose messages) */ 98 FILE *es; /* error stream (for error messages) */ 99 char *chkfilename; /* Filename to write stage 1 checkpoints to */ 100 char *TreeFilename; /* Base filename for storing product tree of F */ 101 double maxmem; /* Maximal amount of memory to use in stage 2, in bytes. 102 0. means no limit (optimise only for speed) */ 103 double stage1time; /* Time to add for estimating expected time to find fac.*/ 104 gmp_randstate_t rng; /* State of random number generator */ 105 int use_ntt; /* set to 1 to use ntt poly code in stage 2 */ 106 int (*stop_asap) (void); /* Pointer to function, if it returns 0, contine 107 normally, otherwise exit asap. May be NULL */ 108 /* The batch mode is used for stage 1 when param=1 or param=2)*/ 109 mpz_t batch_s; /* s is the product of primes up to B1 for batch mode */ 110 double batch_last_B1_used; /* Last B1 used in batch mode. Used to avoid */ 111 /* computing s when B1 = batch_last_B1_used */ 112 int gpu; /* do we use the GPU for stage 1. */ 113 /* If different from 0, the GPU is used */ 114 /* Else, the parameters beginning by gpu_* have no meaning */ 115 int gpu_device; /* Which device do we use */ 116 int gpu_device_init; /* Is the device initialized?*/ 117 unsigned int gpu_number_of_curves; 118 double gw_k; /* use for gwnum stage 1 if input has form k*b^n+c */ 119 unsigned long gw_b; /* use for gwnum stage 1 if input has form k*b^n+c */ 120 unsigned long gw_n; /* use for gwnum stage 1 if input has form k*b^n+c */ 121 signed long gw_c; /* use for gwnum stage 1 if input has form k*b^n+c */ 122} __ecm_param_struct; 123typedef __ecm_param_struct ecm_params[1]; 124typedef __ecm_param_struct *ecm_params_ptr; 125 126#define ECM_MOD_NOBASE2 -1 127#define ECM_MOD_DEFAULT 0 128#define ECM_MOD_MPZ 1 129#define ECM_MOD_BASE2 2 130#define ECM_MOD_MODMULN 3 131#define ECM_MOD_REDC 4 132/* values <= -16 or >= 16 have a special meaning */ 133 134const char *ecm_version(); 135int ecm_factor (mpz_t, mpz_t, double, ecm_params); 136void ecm_init (ecm_params); 137void ecm_clear (ecm_params); 138 139/* the following interface is not supported */ 140int ecm (mpz_t, mpz_t, mpz_t, int*, mpz_t, mpz_t, mpz_t, double *, double, mpz_t, mpz_t, 141 unsigned long, int, int, int, int, int, int, 142 ell_curve_t, FILE* os, FILE* es, 143 char*, char *, double, double, gmp_randstate_t, int (*)(void), mpz_t, 144 double *, double, unsigned long, unsigned long, signed long); 145int pp1 (mpz_t, mpz_t, mpz_t, mpz_t, double *, double, mpz_t, mpz_t, 146 unsigned long, int, int, int, FILE*, FILE*, char*, 147 char *, double, gmp_randstate_t, int (*)(void)); 148int pm1 (mpz_t, mpz_t, mpz_t, mpz_t, double *, double, mpz_t, 149 mpz_t, unsigned long, int, int, int, FILE*, 150 FILE*, char *, char*, double, gmp_randstate_t, int (*)(void)); 151 152/* different methods implemented */ 153#define ECM_ECM 0 154#define ECM_PM1 1 155#define ECM_PP1 2 156 157/* return value of ecm, pm1, pp1 */ 158#define ECM_FACTOR_FOUND_STEP1 1 /* should be positive */ 159#define ECM_FACTOR_FOUND_STEP2 2 /* should be positive */ 160#define ECM_NO_FACTOR_FOUND 0 /* should be zero */ 161#define ECM_ERROR -1 /* should be non-zero */ 162#define ECM_FACTOR_FOUND_P(x) ((x) > 0) 163#define ECM_ERROR_P(x) ((x) < 0) 164 165#define ECM_DEFAULT_B1_DONE 1.0 166#define ECM_IS_DEFAULT_B1_DONE(x) (x <= 1.0) 167 168/* Different parametrizations used in stage 1 of ECM */ 169#define ECM_PARAM_DEFAULT -1 170#define ECM_PARAM_SUYAMA 0 171#define ECM_PARAM_BATCH_SQUARE 1 172#define ECM_PARAM_BATCH_2 2 173#define ECM_PARAM_BATCH_32BITS_D 3 174/* we keep 4 as spare */ 175#define ECM_PARAM_WEIERSTRASS 5 176#define ECM_PARAM_HESSIAN 6 177#define ECM_PARAM_TORSION 7 178 179/* stage 2 bound */ 180#define ECM_DEFAULT_B2 -1 181#define ECM_IS_DEFAULT_B2(x) (mpz_cmp_si (x, ECM_DEFAULT_B2) == 0) 182 183#define ECM_DEFAULT_K 0 /* default number of blocks in stage 2. 0 = automatic 184 choice */ 185#define ECM_DEFAULT_S 0 /* polynomial is chosen automatically */ 186 187/* Apple uses '\r' for newlines */ 188#define IS_NEWLINE(c) (((c) == '\n') || ((c) == '\r')) 189 190#ifdef __cplusplus 191} 192#endif 193 194#endif /* _ECM_H */ 195 196