1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
.Dd $Mdocdate: November 5 2016 $
.Dt DH 3
.Os
.Sh NAME
.Nm dh
.Nd Diffie-Hellman key agreement
.Sh SYNOPSIS
.In openssl/dh.h
.In openssl/engine.h
.Ft DH *
.Fn DH_new void
.Ft void
.Fo DH_free
.Fa "DH *dh"
.Fc
.Ft int
.Fo DH_size
.Fa "const DH *dh"
.Fc
.Ft DH *
.Fo DH_generate_parameters
.Fa "int prime_len"
.Fa "int generator"
.Fa "void (*callback)(int, int, void *)"
.Fa "void *cb_arg"
.Fc
.Ft int
.Fo DH_check
.Fa "const DH *dh"
.Fa "int *codes"
.Fc
.Ft int
.Fo DH_generate_key
.Fa "DH *dh"
.Fc
.Ft int
.Fo DH_compute_key
.Fa "unsigned char *key"
.Fa "BIGNUM *pub_key"
.Fa "DH *dh"
.Fc
.Ft void
.Fo DH_set_default_method
.Fa "const DH_METHOD *meth"
.Fc
.Ft const DH_METHOD *
.Fn DH_get_default_method void
.Ft int
.Fo DH_set_method
.Fa "DH *dh"
.Fa "const DH_METHOD *meth"
.Fc
.Ft DH *
.Fo DH_new_method
.Fa "ENGINE *engine"
.Fc
.Ft const DH_METHOD *
.Fn DH_OpenSSL void
.Ft int
.Fo DH_get_ex_new_index
.Fa "long argl"
.Fa "char *argp"
.Fa "int (*new_func)()"
.Fa "int (*dup_func)()"
.Fa "void (*free_func)()"
.Fc
.Ft int
.Fo DH_set_ex_data
.Fa "DH *d"
.Fa "int idx"
.Fa "char *arg"
.Fc
.Ft char *
.Fo DH_get_ex_data
.Fa "DH *d"
.Fa "int idx"
.Fc
.Ft DH *
.Fo d2i_DHparams
.Fa "DH **a"
.Fa "unsigned char **pp"
.Fa "long length"
.Fc
.Ft int
.Fo i2d_DHparams
.Fa "const DH *a"
.Fa "unsigned char **pp"
.Fc
.Ft int
.Fo DHparams_print_fp
.Fa "FILE *fp"
.Fa "const DH *x"
.Fc
.Ft int
.Fo DHparams_print
.Fa "BIO *bp"
.Fa "const DH *x"
.Fc
.Sh DESCRIPTION
These functions implement the Diffie-Hellman key agreement protocol.
The generation of shared DH parameters is described in
.Xr DH_generate_parameters 3 ;
.Xr DH_generate_key 3
describes how to perform a key agreement.
.Pp
The
.Vt DH
structure consists of several
.Vt BIGNUM
components.
.Bd -literal
typedef struct {
BIGNUM *p; // prime number (shared)
BIGNUM *g; // generator of Z_p (shared)
BIGNUM *priv_key; // private DH value x
BIGNUM *pub_key; // public DH value g^x
// ...
} DH;
.Ed
.Pp
Note that DH keys may use non-standard
.Vt DH_METHOD
implementations, either directly or by the use of
.Vt ENGINE
modules.
In some cases (eg. an
.Vt ENGINE
providing support for hardware-embedded keys), these
.Vt BIGNUM
values will not be used by the implementation or may be used for
alternative data storage.
For this reason, applications should generally avoid using
.Vt DH
structure elements directly and instead use API functions to query
or modify keys.
.Sh SEE ALSO
.Xr bn 3 ,
.Xr d2i_DHparams 3 ,
.Xr DH_compute_key 3 ,
.Xr DH_generate_parameters 3 ,
.Xr DH_get_ex_new_index 3 ,
.Xr DH_new 3 ,
.Xr DH_set_method 3 ,
.Xr dsa 3 ,
.Xr engine 3 ,
.Xr ERR 3 ,
.Xr rsa 3 ,
.Xr RSA_print 3
|