5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 Pekka Riikonen
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.
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.
20 /****h* silccrypt/SilcDH/silcdh.h
24 * PKCS #3 compliant Diffie Hellman key agreement protocol implementation.
25 * This is used as part of SKE (SILC Key Exchange) protocol.
34 /****s* silccrypt/SilcDH/SilcDH
38 * typedef struct SilcDHStruct *SilcDH;
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.
46 typedef struct SilcDHStruct *SilcDH;
48 /* XXX Move to source file */
49 /* Diffie Hellman context. This includes the DH parameters including the
50 negotiated key material. */
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) */
61 /****f* silccrypt/SilcDH/silc_dh_alloc
65 * SilcDH silc_dh_alloc(SilcMPInt *g, SilcMPInt *p, SilcMPInt *lpf);
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
78 SilcDH silc_dh_alloc(SilcMPInt *g, SilcMPInt *p, SilcMPInt *lpf);
80 /****f* silccrypt/SilcDH/silc_dh_free
84 * void silc_dh_free(SilcDH dh);
88 * Free the SilcDH context. Frees all the allocated data inside the
92 void silc_dh_free(SilcDH dh);
94 /****f* silccrypt/SilcDH/silc_dh_generate_private
98 * bool silc_dh_generate_private(SilcDH dh, const SilcMPInt **x);
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.
108 bool silc_dh_generate_private(SilcDH dh, const SilcMPInt **x);
110 /****f* silccrypt/SilcDH/silc_dh_compute_public
114 * bool silc_dh_compute_public(SilcDH dh, const SilcMPInt **y);
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.
124 bool silc_dh_compute_public(SilcDH dh, const SilcMPInt **y);
126 /****f* silccrypt/SilcDH/silc_dh_remote_public
130 * bool silc_dh_compute_public(SilcDH dh, SilcMPInt *y);
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
139 bool silc_dh_set_remote_public(SilcDH dh, SilcMPInt *y);
141 /****f* silccrypt/SilcDH/silc_dh_compute_key
145 * bool silc_dh_compute_key(SilcDH dh, const SilcMPInt **z);
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.
155 bool silc_dh_compute_key(SilcDH dh, const SilcMPInt **z);
157 /****f* silccrypt/SilcDH/silc_dh_remote_public
161 * bool silc_dh_compute_key_data(SilcDH dh, unsigned char **z,
166 * Same as above but returns the computed secret key as octet binary
167 * string. The caller must free the returned binary string.
170 bool silc_dh_compute_key_data(SilcDH dh, unsigned char **z,