Reject calls to X509_verify_cert that have not been reinitialised
[openssl.git] / doc / crypto / dh.pod
1 =pod
2
3 =head1 NAME
4
5 dh - Diffie-Hellman key agreement
6
7 =head1 SYNOPSIS
8
9  #include <openssl/dh.h>
10  #include <openssl/engine.h>
11
12  DH *   DH_new(void);
13  void   DH_free(DH *dh);
14
15  DH *   DH_generate_parameters(int prime_len, int generator,
16                 void (*callback)(int, int, void *), void *cb_arg);
17  int    DH_check(const DH *dh, int *codes);
18
19  int    DH_generate_key(DH *dh);
20  int    DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
21
22  void DH_set_default_method(const DH_METHOD *meth);
23  const DH_METHOD *DH_get_default_method(void);
24  int DH_set_method(DH *dh, const DH_METHOD *meth);
25  DH *DH_new_method(ENGINE *engine);
26  const DH_METHOD *DH_OpenSSL(void);
27
28  int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(),
29              int (*dup_func)(), void (*free_func)());
30  int DH_set_ex_data(DH *d, int idx, char *arg);
31  char *DH_get_ex_data(DH *d, int idx);
32
33  DH *   d2i_DHparams(DH **a, unsigned char **pp, long length);
34  int    i2d_DHparams(const DH *a, unsigned char **pp);
35
36  int    DHparams_print_fp(FILE *fp, const DH *x);
37  int    DHparams_print(BIO *bp, const DH *x);
38
39 =head1 DESCRIPTION
40
41 These functions implement the Diffie-Hellman key agreement protocol.
42 The generation of shared DH parameters is described in
43 L<DH_generate_parameters(3)|DH_generate_parameters(3)>; L<DH_generate_key(3)|DH_generate_key(3)> describes how
44 to perform a key agreement.
45
46 The B<DH> structure consists of several BIGNUM components.
47
48  struct
49         {
50         BIGNUM *p;              // prime number (shared)
51         BIGNUM *g;              // generator of Z_p (shared)
52         BIGNUM *priv_key;       // private DH value x
53         BIGNUM *pub_key;        // public DH value g^x
54         // ...
55         };
56  DH
57
58 Note that DH keys may use non-standard B<DH_METHOD> implementations,
59 either directly or by the use of B<ENGINE> modules. In some cases (eg. an
60 ENGINE providing support for hardware-embedded keys), these BIGNUM values
61 will not be used by the implementation or may be used for alternative data
62 storage. For this reason, applications should generally avoid using DH
63 structure elements directly and instead use API functions to query or
64 modify keys.
65
66 =head1 SEE ALSO
67
68 L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>,
69 L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>,
70 L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>,
71 L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>,
72 L<DH_generate_parameters(3)|DH_generate_parameters(3)>,
73 L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>,
74 L<RSA_print(3)|RSA_print(3)> 
75
76 =cut