2 * Copyright (c) 2006 - 2007 Kungliga Tekniska Högskolan
3 * (Royal Institute of Technology, Stockholm, Sweden).
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in the
15 * documentation and/or other materials provided with the distribution.
17 * 3. Neither the name of the Institute nor the names of its contributors
18 * may be used to endorse or promote products derived from this software
19 * without specific prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
22 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
25 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
38 RCSID("$Id: dh.c 22397 2008-01-01 20:20:31Z lha $");
47 * @page page_dh DH - Diffie-Hellman key exchange
49 * Diffie-Hellman key exchange is a protocol that allows two parties
50 * to establish a shared secret key.
52 * Include and example how to use DH_new() and friends here.
54 * See the library functions here: @ref hcrypto_dh
58 * Create a new DH object using DH_new_method(NULL), see DH_new_method().
60 * @return a newly allocated DH object.
68 return DH_new_method(NULL);
72 * Create a new DH object from the given engine, if the NULL is used,
73 * the default engine is used. Free the DH object with DH_free().
75 * @param engine The engine to use to allocate the DH object.
77 * @return a newly allocated DH object.
83 DH_new_method(ENGINE *engine)
87 dh = calloc(1, sizeof(*dh));
94 ENGINE_up_ref(engine);
97 dh->engine = ENGINE_get_default_DH();
101 dh->meth = ENGINE_get_DH(dh->engine);
102 if (dh->meth == NULL) {
103 ENGINE_finish(engine);
109 if (dh->meth == NULL)
110 dh->meth = DH_get_default_method();
112 (*dh->meth->init)(dh);
118 * Free a DH object and release related resources, like ENGINE, that
119 * the object was using.
121 * @param dh object to be freed.
123 * @ingroup hcrypto_dh
129 if (dh->references <= 0)
132 if (--dh->references > 0)
135 (*dh->meth->finish)(dh);
138 ENGINE_finish(dh->engine);
140 #define free_if(f) if (f) { BN_free(f); }
143 free_if(dh->pub_key);
144 free_if(dh->priv_key);
147 free_if(dh->counter);
150 memset(dh, 0, sizeof(*dh));
155 * Add a reference to the DH object. The object should be free with
156 * DH_free() to drop the reference.
158 * @param dh the object to increase the reference count too.
160 * @return the updated reference count, can't safely be used except
161 * for debug printing.
163 * @ingroup hcrypto_dh
169 return ++dh->references;
173 * The maximum output size of the DH_compute_key() function.
175 * @param dh The DH object to get the size from.
177 * @return the maximum size in bytes of the out data.
179 * @ingroup hcrypto_dh
183 DH_size(const DH *dh)
185 return BN_num_bytes(dh->p);
189 * Set the data index idx in the DH object to data.
191 * @param dh DH object.
192 * @param idx index to set the data for.
193 * @param data data to store for the index idx.
195 * @return 1 on success.
197 * @ingroup hcrypto_dh
201 DH_set_ex_data(DH *dh, int idx, void *data)
203 dh->ex_data.sk = data;
208 * Get the data for index idx in the DH object.
210 * @param dh DH object.
211 * @param idx index to get the data for.
213 * @return the object store in index idx
215 * @ingroup hcrypto_dh
219 DH_get_ex_data(DH *dh, int idx)
221 return dh->ex_data.sk;
225 * Generate DH parameters for the DH object give parameters.
227 * @param dh The DH object to generate parameters for.
228 * @param prime_len length of the prime
229 * @param generator generator, g
230 * @param cb Callback parameters to show progress, can be NULL.
232 * @return the maximum size in bytes of the out data.
234 * @ingroup hcrypto_dh
238 DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb)
240 if (dh->meth->generate_params)
241 return dh->meth->generate_params(dh, prime_len, generator, cb);
246 * Check that the public key is sane.
248 * @param dh the local peer DH parameters.
249 * @param pub_key the remote peer public key parameters.
250 * @param codes return that the failures of the pub_key are.
252 * @return 1 on success, 0 on failure and *codes is set the the
253 * combined fail check for the public key
255 * @ingroup hcrypto_dh
259 DH_check_pubkey(const DH *dh, const BIGNUM *pub_key, int *codes)
261 BIGNUM *bn = NULL, *sum = NULL;
267 * Checks that the function performs are:
268 * - pub_key is not negative
271 if (BN_is_negative(pub_key))
275 * - pub_key > 1 and pub_key < p - 1,
276 * to avoid small subgroups attack.
283 if (!BN_set_word(bn, 1))
286 if (BN_cmp(bn, pub_key) >= 0)
287 *codes |= DH_CHECK_PUBKEY_TOO_SMALL;
293 BN_uadd(sum, pub_key, bn);
295 if (BN_cmp(sum, dh->p) >= 0)
296 *codes |= DH_CHECK_PUBKEY_TOO_LARGE;
299 * - if g == 2, pub_key have more then one bit set,
300 * if bits set is 1, log_2(pub_key) is trival
303 if (!BN_set_word(bn, 2))
306 if (BN_cmp(bn, pub_key) == 0) {
307 unsigned i, n = BN_num_bits(pub_key);
310 for (i = 0; i <= n; i++)
311 if (BN_is_bit_set(pub_key, i))
315 *codes |= DH_CHECK_PUBKEY_TOO_SMALL;
331 * Generate a new DH private-public key pair. The dh parameter must be
332 * allocted first with DH_new(). dh->p and dp->g must be set.
334 * @param dh dh parameter.
336 * @return 1 on success.
338 * @ingroup hcrypto_dh
342 DH_generate_key(DH *dh)
344 return dh->meth->generate_key(dh);
348 * Complute the shared secret key.
350 * @param shared_key the resulting shared key, need to be at least
352 * @param peer_pub_key the peer's public key.
353 * @param dh the dh key pair.
355 * @return 1 on success.
357 * @ingroup hcrypto_dh
361 DH_compute_key(unsigned char *shared_key,
362 const BIGNUM *peer_pub_key, DH *dh)
367 * Checks that the pubkey passed in is valid using
371 if (!DH_check_pubkey(dh, peer_pub_key, &codes) || codes != 0)
374 return dh->meth->compute_key(shared_key, peer_pub_key, dh);
378 * Set a new method for the DH keypair.
380 * @param dh dh parameter.
381 * @param method the new method for the DH parameter.
383 * @return 1 on success.
385 * @ingroup hcrypto_dh
389 DH_set_method(DH *dh, const DH_METHOD *method)
391 (*dh->meth->finish)(dh);
393 ENGINE_finish(dh->engine);
397 (*dh->meth->init)(dh);
406 dh_null_generate_key(DH *dh)
412 dh_null_compute_key(unsigned char *shared,const BIGNUM *pub, DH *dh)
424 dh_null_finish(DH *dh)
430 dh_null_generate_params(DH *dh, int prime_num, int len, BN_GENCB *cb)
435 static const DH_METHOD dh_null_method = {
437 dh_null_generate_key,
444 dh_null_generate_params
447 extern const DH_METHOD _hc_dh_imath_method;
448 static const DH_METHOD *dh_default_method = &_hc_dh_imath_method;
451 * Return the dummy DH implementation.
453 * @return pointer to a DH_METHOD.
455 * @ingroup hcrypto_dh
461 return &dh_null_method;
465 * Set the default DH implementation.
467 * @param meth pointer to a DH_METHOD.
469 * @ingroup hcrypto_dh
473 DH_set_default_method(const DH_METHOD *meth)
475 dh_default_method = meth;
479 * Return the default DH implementation.
481 * @return pointer to a DH_METHOD.
483 * @ingroup hcrypto_dh
487 DH_get_default_method(void)
489 return dh_default_method;