1 /* 2 3 silcdh.h 4 5 Author: Pekka Riikonen <priikone@silcnet.org> 6 7 Copyright (C) 2001 Pekka Riikonen 8 9 The contents of this file are subject to one of the Licenses specified 10 in the COPYING file; You may not use this file except in compliance 11 with the License. 12 13 The software distributed under the License is distributed on an "AS IS" 14 basis, in the hope that it will be useful, but WITHOUT WARRANTY OF ANY 15 KIND, either expressed or implied. See the COPYING file for more 16 information. 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 174