lib/silccrypt/silcdh.h

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