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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::DiffieHellman)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
(Diffie Hellman key computations)
manpagename(FBB::DiffieHellman)(Diffie-Hellman PKI, computing shared keys)
manpagesynopsis()
bf(#include <bobcat/diffiehellman>)nl()
Linking option: tt(-lbobcat -lcrypto)
manpagedescription()
The class bf(FBB::DiffieHellman) computes shared keys (shared secrets) using
the Diffie-Hellman (1976) algorithm. The Diffie-Hellman algorithm uses public
and private information, providing a public key infrastructure (PKI). The
public information consists of a em(prime) (e.g., a prime number consisting of
1024 bits), a em(generator) (for which the value 5 is commonly used), and
(using tt(**) to represent the power operator on integral values) the value
tt(generator ** private mod prime), where tt(private) is a randomly selected
large number, which is the private information.
The Diffie-Hellman algorithm is commonly used to compute a shared key which
can be used to encrypt information sent between two parties. One party, which
in this man-page is called the em(initiator), computes the prime and defines
the generator. The prime is computed by bf(FBB::DiffieHellman)'s first
constructor, while the generator is passed to this constructor as one of its
arguments. For the generator the value 5 is often used.
Next the initiator passes its public information, consisting of the prime, the
generator, and the value tt(pow(generator, private) mod prime) to the other
party, which in this man-page is called the tt(peer). The public information
is written in binairy, big-endian form to file using the member tt(save). The
initiator may optionally save the private information to a separate file as
well.
The peer thereupon receives the initiator's public information. The
initialor's public information is read by a bf(FBB::DiffieHellman) constructor
either expecting the name of a file or a tt(std::istream) containining the
initiator's public information.
Having obtained the prime and generator, the peer's public (and, optionally,
private information) is saved by also calling tt(save). This results, among
other things, in the value tt(pow(generator, private) mod prime), but now
using the peer's private information.
At this point the peer is already able to compute the shared key. The key is
returned by calling the tt(key) member, which returns the shared key as a
series of bytes stored in a tt(std::string).
Before the initiator can compute the shared key the peer's
tt(generator ** private mod prime) value must be available. The peer sends
the saved public data to the initiator. The initiator then passes the peer's
public data either by file name or by tt(std::istream) to the tt(key) member,
returning the shared key.
bf(Perfect Forward Secrecy and Ephemeral Diffie Hellman)
If the initiator and peer decide not to save their private information
em(Perfect Forward Secrecy) and em(Ephemeral Diffie Hellman) may be
obtained. Here, the procedure is applied as follows:
itemization(
it() Initiator and peer have agreed upon and securely exchanged a
long-lasting common secret, which may be used in combination with, e.g.,
symmetric encryption methods.
it() Applying the abovementioned procedure, the private information is
never saved on file. Consequently, the shared key, once computed, cannot be
reconstructed anymore.
it() The value tt(generator ** private mod prime) is not sent to either
peer or initiator `in the clear', but encrypted using the long-lasting common
secret. As the current implementation saves all public information on file,
it's probably easiest to encrypt the file containing the public information.
it() The recipients, having received the other party's encrypted public
information, decrypt it using the long-lasting shared secret and compute the
the shared key.
it() As the secret information is not kept, the shared key cannot be
reconstructed, while a Man-In-The-Middle attack is prevented by only
exchanging encrypted public information.
it() The shared key can now be used to encrypt a communication session
)
bf(Document encryption using Diffie Hellman)
As with PKI in general, the Diffie Hellman key exchange method itself is not
normally used for encrypting documents. Instead, it is usually used to
exchange the key that is used for symmetric encryption methods like 3DES and
CBC. These symmetric encryption methods are available through, e.g., Bobcats'
tt(EncryptBuf, DecryptBuf,) and tt(ISymCryptStream) classes.
includefile(include/namespace)
manpagesection(INHERITS FROM)
-
manpagesection(CONSTRUCTORS)
itemization(
itb(DiffieHellman(size_t primeLength = 1024, size_t generator = 5,
bool progress = false))
This constructor computes a prime of the specified length, and
initializes the public information with the indicated generator. The
prime length must at least be 1024 or an tt(FBB::Exception) is thrown.
If tt(progress) is tt(true), the progress of the prime construction
process is shown to tt(std::cout) by a series of dots, minuses and
plusses. Generating a suitable prime may fail, resulting in an
tt(FBB::Exception) being thrown. Unless the generator is specified as
2 or 5 the warning tt(cannot check the validity of generator ...) is
inserted into the bf(mstream)(3bobcat)'s tt(wmsg) object. A warning is
also inserted if the provided generator is not a generator for the
computed prime.
This constructor should be called by the initiator to start the
Diffie-Hellman shared key computation procedure.
itb(DiffieHellman(FBB::BigInt const &prime, size_t generator = 5,
bool progress = false))
Alternatively, this constructor can be used by the initiator after
separately having constructed the prime to use. The prime must at
least be 1024 bits long.
itb(DiffieHellman(std::string const &initiatorPublicFileName))
This constructor should be called by the peer, after having received the
initiator's public info. It makes the initiator's public information available
to the peer, after which the peer's public and private information can be
computed.
itb(DiffieHellman(std::stream &initiatorPublicStream))
This constructor acts like the previous constructor, expecting a
tt(std::istream) rather than a file name. It should be called by the peer,
after having received the initiator's public info. It makes the initiator's
public information available to the peer, after which the peer's public and
private information can be computed.
itb(DiffieHellman(std::string const &initiatorPublicFileName, std::string
const &initiatorPrivateFileName))
Unless the initiator's tt(DiffieHellman) object is still available,
this constructor should again be called by the initiator, to load the
initiator's public and private data.
itb(DiffieHellman(std::stream &initiatorPublicStream, std::stream
&initiatorPrivateStream))
This constructor acts like the previous constructor, expecting
tt(std::istreams) rather than file names. It should be called by the
initiator, to load the initiator's public and private info.
)
Copy and move constructors (and assignment operators) are available.
manpagesection(MEMBER FUNCTIONS)
itemization(
itb(std::string key() const)
This member should be called by the peer. It returns the shared key. If
the key cannot be computed, or if the key is not resistant to the small group
attack (i.e., if the key equals 1, or is at least equal to the public prime
value, or if tt(key ** ((prime - 1) / 2) mod prime != 1)), then an
tt(FBB::Exception) is thrown.
itb(std::string key(std::string const &peerPublicFileName) const)
This member should be called by the initiator. It skips the data referring
to the prime and generator found in tt(peerPublicFileName) and then reads the
peer's tt(generator ** private mod prime) value. If this value cannot be
read or if the key is not resistant to the small group attack (cf. the
description of the previous tt(key) member) then an tt(FBB::Exception) is
thrown. It returns the shared key.
itb(std::string key(std::istream const &peerPublicStream) const)
This member should be called by the initiator. It acts like the previous
tt(key) member, reading the peer's tt(generator ** private mod prime) value
from tt(peerPublicStream). It returns the shared key.
itb(void save(std::string const &basename))
This member should be called by the initiator. It saves the public
information on the file tt('basename'.pub). The information is written in
binary, big-endian format, using the following organization:
- the size of the prime in bytes;nl()
- the prime's bytes;nl()
- the size of the generator in bytes;nl()
- the generator's bytes;nl()
- the size of the public info (tt(generator ** private mod prime)) in
bytes;nl()
- the public info's bytes.nl()
In addition the private information is written to the file
tt('basename'.sec) in binary, big-endian format, using the following
organization:
- the size of the private information in bytes;nl()
- the private information bytes.
)
manpagesection(EXAMPLE)
When called without arguments, the example program generates
Diffie-Hellman parameters writing the initiator's public and private
information to, respectively, tt(init.pub) and tt(init.sec).
When called with one argument, tt(init.pub) is read, and the peer's public
and private information is written to, respectively, tt(peer.pub) and
tt(peer.sec). Next, the (peer's) shared key is written to tt(peerkey).
When called with two arguments, tt(init.pub) and tt(init.sec) are read,
as well as the peer's public information (on the file tt(peer.pub)). Next, the
(initiator's) shared key is written to tt(initkey).
The files tt(peerkey) and tt(initkey) should be identical.
verbinclude(../../diffiehellman/driver/driver.cc)
manpagefiles()
em(bobcat/diffiehellman) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(bigint)(3bobcat), bf(ecdh)(3bobcat),
bf(isymcryptstream)(3bobcat), bf(osymcryptstream)(3bobcat)
manpagebugs()
None Reported.
includefile(include/trailer)
|
