lib/silccrypt/silcdh.h

   1 /****h* silccrypt/SilcDH/silcdh.h
   2  *
   3  * NAME
   4  *
   5  * silcdh.h
   6  *
   7  * COPYRIGHT
   8  *
   9  * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
  10  *
  11  * Copyright (C) 2001 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  * PKCS #3 compliant Diffie Hellman key agreement protocol implementation.
  26  * This is used as part of SKE (SILC Key Exchange) protocol.
  27  ***/
  28
  29 #ifndef SILCDH_H
  30 #define SILCDH_H
  31
  32 #include "silcmp.h"
  33 #include "silcrng.h"
  34
  35 /****s* silccrypt/SilcDH/SilcDH
  36  *
  37  * NAME
  38  *
  39  *    typedef struct SilcDHStruct *SilcDH;
  40  *
  41  * DESCRIPTION
  42  *
  43  *    This context is allocated by silc_dh_alloc and is given as argument
  44  *    to all silc_dh_* functions.  It is freed by silc_dh_free function.
  45  *
  46  ***/
  47 typedef struct SilcDHStruct *SilcDH;
  48
  49 /* XXX Move to source file */
  50 /* Diffie Hellman context. This includes the DH parameters including the
  51    negotiated key material. */
  52 struct SilcDHStruct {
  53   SilcInt *g;             /* Global base (generator) */
  54   SilcInt *p;             /* Global prime (modulus, prime) */
  55   SilcInt *lpf;           /* Largest prime factor (prime) */
  56   SilcInt *my_x;          /* x, My private value (random) */
  57   SilcInt *my_y;          /* y, My public value (y = g ^ x mod p) */
  58   SilcInt *your_y;        /* y', Your public value (y' = g ^ x' mod p) */
  59   SilcInt *z;             /* The computed secret key (z = y' ^ x mod p) */
  60
  61   SilcRng rng;            /* RNG */
  62 };
  63
  64 /****f* silccrypt/SilcDH/silc_dh_alloc
  65  *
  66  * SYNOPSIS
  67  *
  68  *    SilcDH silc_dh_alloc(SilcRng rng, SilcInt *g, SilcInt *p, SilcInt *lpf);
  69  *
  70  * DESCRIPTION
  71  *
  72  *    Allocate SilcDH context. The `rng' must be initialized random number
  73  *    generator context, the `g' is the public base generator used in the
  74  *    negotiation, the `p' is the public prime used in the negotiation and
  75  *    the `lpf' is largest prime factor of p defined publicly as well. The
  76  *    `lpf' is optional and if it is not supplied then the private values
  77  *    generated satifies 0 < x < p - 1 instead of 0 < x < lpf. Returns NULL
  78  *    on error or allocated SilcDH context on success.
  79  *
  80  ***/
  81 SilcDH silc_dh_alloc(SilcRng rng, SilcInt *g, SilcInt *p, SilcInt *lpf);
  82
  83 /****f* silccrypt/SilcDH/silc_dh_free
  84  *
  85  * SYNOPSIS
  86  *
  87  *    void silc_dh_free(SilcDH dh);
  88  *
  89  * DESCRIPTION
  90  *
  91  *    Frees the SilcDH context. Does not free the RNG context given in the
  92  *    allocation. Frees all the allocated data inside the SilcDH context.
  93  *
  94  ***/
  95 void silc_dh_free(SilcDH dh);
  96
  97 /****f* silccrypt/SilcDH/silc_dh_generate_private
  98  *
  99  * SYNOPSIS
 100  *
 101  *    int silc_dh_generate_private(SilcDH dh, SilcInt **x);
 102  *
 103  * DESCRIPTION
 104  *
 105  *    Generates random private value `x' such that 0 < x < lpf at most of
 106  *    length of lpf. Returns FALSE if the random number could not be generated.
 107  *    Returns the generated value into `x' pointer sent as argument, unless
 108  *    the `x' is NULL. The returned `x' must no be freed by the caller.
 109  *
 110  ***/
 111 int silc_dh_generate_private(SilcDH dh, SilcInt **x);
 112
 113 /****f* silccrypt/SilcDH/silc_dh_compute_public
 114  *
 115  * SYNOPSIS
 116  *
 117  *    int silc_dh_compute_public(SilcDH dh, SilcInt **y);
 118  *
 119  * DESCRIPTION
 120  *
 121  *    Computes the public key y = g ^ x mod p, and returns it to the `y'
 122  *    pointer sent as argument, unless the `y' is NULL. Returns FALSE if
 123  *    the computation could not be performed. The returned `y' must not be
 124  *    freed by the caller.
 125  *
 126  ***/
 127 int silc_dh_compute_public(SilcDH dh, SilcInt **y);
 128
 129 /****f* silccrypt/SilcDH/silc_dh_remote_public
 130  *
 131  * SYNOPSIS
 132  *
 133  *    int silc_dh_compute_public(SilcDH dh, SilcInt **y);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Sets the remote end's public value y' into the SilcDH context.
 138  *    This must be done before computing the secret key. Returns FALSE
 139  *    on error.
 140  *
 141  ***/
 142 int silc_dh_set_remote_public(SilcDH dh, SilcInt *y);
 143
 144 /****f* silccrypt/SilcDH/silc_dh_compute_key
 145  *
 146  * SYNOPSIS
 147  *
 148  *    int silc_dh_compute_key(SilcDH dh, SilcInt **z);
 149  *
 150  * DESCRIPTION
 151  *
 152  *    Computes the secret key z = y' ^ x mod p, and returns the key to the
 153  *    `z' pointer sent as argument, unless the `z' is NULL. Returns FALSE if
 154  *    the computation could not be performed. The returned `z' must not be
 155  *    freed by the caller.
 156  *
 157  ***/
 158 int silc_dh_compute_key(SilcDH dh, SilcInt **z);
 159
 160 /****f* silccrypt/SilcDH/silc_dh_remote_public
 161  *
 162  * SYNOPSIS
 163  *
 164  *    int silc_dh_compute_key_data(SilcDH dh, unsigned char **z,
 165  *                                 uint32 *z_len);
 166  *
 167  * DESCRIPTION
 168  *
 169  *    Same as above but returns the computed secret key as octet binary
 170  *    string.
 171  *
 172  ***/
 173 int silc_dh_compute_key_data(SilcDH dh, unsigned char **z,
 174                              uint32 *z_len);
 175
 176 #endif