lib/silcmath/silcmath.h

   1 /****h* silcmath/silcmath.h
   2  *
   3  * NAME
   4  *
   5  * silcmath.h
   6  *
   7  * COPYRIGHT
   8  *
   9  * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
  10  *
  11  * Copyright (C) 1997 - 2000 Pekka Riikonen
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * DESCRIPTION
  24  *
  25  * SILC Math interface includes various utility functions such as
  26  * prime generation, and conversion routines. See the silcmp.h for the
  27  * SILC MP interface.
  28  *
  29  */
  30
  31 #ifndef SILCMATH_H
  32 #define SILCMATH_H
  33
  34 /****f* silcmath/SilcMathAPI/silc_mp_modinv
  35  *
  36  * SYNOPSIS
  37  *
  38  *    void silc_mp_modinv(SilcInt *inv, SilcInt *a, SilcInt *n);
  39  *
  40  * DESCRIPTION
  41  *
  42  *    Find multiplicative inverse using Euclid's extended algorithm.
  43  *    Computes inverse such that a * inv mod n = 1, where 0 < a < n.
  44  *    Algorithm goes like this:
  45  *
  46  *    g(0) = n    v(0) = 0
  47  *    g(1) = a    v(1) = 1
  48  *
  49  *    y = g(i-1) / g(i)
  50  *    g(i+1) = g(i-1) - y * g(i) = g(i)-1 mod g(i)
  51  *    v(i+1) = v(i-1) - y * v(i)
  52  *
  53  *    do until g(i) = 0, then inverse = v(i-1). If inverse is negative then n,
  54  *    is added to inverse making it positive again. (Sometimes the algorithm
  55  *    has a variable u defined too and it behaves just like v, except that
  56  *    initalize values are swapped (i.e. u(0) = 1, u(1) = 0). However, u is
  57  *    not needed by the algorithm so it does not have to be included.)
  58  *
  59  ***/
  60 void silc_mp_modinv(SilcInt *inv, SilcInt *a, SilcInt *n);
  61
  62 /****f* silcmath/SilcMathAPI/silc_mp_mp2bin
  63  *
  64  * SYNOPSIS
  65  *
  66  *    unsigned char *silc_mp_mp2bin(SilcInt *val, uint32 len,
  67  *                                  uint32 *ret_len);
  68  *
  69  * DESCRIPTION
  70  *
  71  *    Encodes MP integer into binary data. Returns allocated data that
  72  *    must be free'd by the caller. If `len' is provided the destination
  73  *    buffer is allocated that large. If zero then the size is approximated.
  74  *
  75  ***/
  76 unsigned char *silc_mp_mp2bin(SilcInt *val, uint32 len,
  77                               uint32 *ret_len);
  78
  79 /****f* silcmath/SilcMathAPI/silc_mp_mp2bin_noalloc
  80  *
  81  * SYNOPSIS
  82  *
  83  *    void silc_mp_mp2bin_noalloc(SilcInt *val, unsigned char *dst,
  84  *                                uint32 dst_len);
  85  *
  86  * DESCRIPTION
  87  *
  88  *    Same as silc_mp_mp2bin but does not allocate any memory.  The
  89  *    encoded data is returned into `dst' and it's length to the `ret_len'.
  90  *
  91  ***/
  92 void silc_mp_mp2bin_noalloc(SilcInt *val, unsigned char *dst,
  93                             uint32 dst_len);
  94
  95 /****f* silcmath/SilcMathAPI/silc_mp_bin2mp
  96  *
  97  * SYNOPSIS
  98  *
  99  *    void silc_mp_bin2mp(unsigned char *data, uint32 len, SilcInt *ret);
 100  *
 101  * DESCRIPTION
 102  *
 103  *    Decodes binary data into MP integer. The integer sent as argument
 104  *    must be initialized.
 105  *
 106  ***/
 107 void silc_mp_bin2mp(unsigned char *data, uint32 len, SilcInt *ret);
 108
 109 /****f* silcmath/SilcMathAPI/silc_math_gen_prime
 110  *
 111  * SYNOPSIS
 112  *
 113  *    int silc_math_gen_prime(SilcInt *prime, uint32 bits, int verbose);
 114  *
 115  * DESCRIPTION
 116  *
 117  *    Find appropriate prime. It generates a number by taking random bytes.
 118  *    It then tests the number that it's not divisible by any of the small
 119  *    primes and then it performs Fermat's prime test. I thank Rieks Joosten
 120  *    (r.joosten@pijnenburg.nl) for such a good help with prime tests.
 121  *
 122  *    If argument verbose is TRUE this will display some status information
 123  *    about the progress of generation.
 124  *
 125  ***/
 126 int silc_math_gen_prime(SilcInt *prime, uint32 bits, int verbose);
 127
 128 /****f* silcmath/SilcMathAPI/silc_math_prime_test
 129  *
 130  * SYNOPSIS
 131  *
 132  *    int silc_math_prime_test(SilcInt *p);
 133  *
 134  * DESCRIPTION
 135  *
 136  *    Performs primality testings for given number. Returns TRUE if the
 137  *    number is probably a prime.
 138  *
 139  ***/
 140 int silc_math_prime_test(SilcInt *p);
 141
 142 #endif