/[svn]/ircd-hybrid/doc/technical/cryptlink.txt
ViewVC logotype

Annotation of /ircd-hybrid/doc/technical/cryptlink.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 30 - (hide annotations)
Sun Oct 2 20:03:27 2005 UTC (14 years, 8 months ago) by adx
File MIME type: text/plain
File size: 13070 byte(s)
- imported sources
- can be moved later according to the directory/branching scheme,
  but we need the svn up

1 adx 30 CRYPTLINK Encrypted Server Link Protocol
2     ========================================
3     (Loosely based on draft by A1kmm)
4     (Rewritten by David-T, einride, vulture, and jdc)
5    
6     0.1 - Conventions of this document
7     ----------------------------------
8    
9     * "MUST" means that a server is not compliant unless it does this.
10     * "MUST NOT" means a server is not compliant if it does this.
11     * "SHOULD" means that a server is at most conditionally compliant
12     if it does not do this.
13     * "SHOULD NOT" means that a server is at most conditionally
14     compliant if it does this.
15     * "MAY" means that a server may choose whether or not to do this.
16    
17    
18     1.1 - Goal of this protocol
19     ---------------------------
20    
21     To reduce the risk of attacks relating to password sniffing,
22     replay attacks, or connection hijacking, in turn permitting
23     unauthorized access to server privileges.
24    
25     1.2 - Background of this protocol
26     ---------------------------------
27    
28     This protocol is based on the IRC protocol as described in RFC1459,
29     and extensions implemented on EFnet as described in other documents
30     available in this directory (doc/), and on the WWW.
31    
32     Any encrypted strings which are transmitted in IRC commands in
33     accordance with this document shall be base64 encoded, with the
34     most significant bits of the most significant byte transmitted
35     first, followed by bits/bytes of decreasing significance. However,
36     the encrypted link itself will be 8-bit, without no encoding.
37    
38     2.1 - Configuration changes
39     ---------------------------
40    
41     Every server which supports encrypted links has a 2048-bit RSA
42     private key stored in a configuration file. Care must be taken
43     to ensure this file is accessible only to the ircd user. For
44     every link to another server that supports encrypted links, the
45     public component of that server's RSA key is stored instead of the
46     traditional password or password hash.
47    
48     A server which is configured to make an encrypted link to another
49     MUST NOT fall back on any other authentication scheme, regardless
50     of what the remote server sends or does.
51    
52    
53     3.1 - Changes to the CAPAB command
54     ----------------------------------
55    
56     The first command sent by a server over an encrypted link MUST
57     be a CAPAB command. The CAPAB command MUST include the
58     ENC capability. The syntax would be as follows:
59    
60     CAPAB :<other supported capabilities> ENC
61    
62     An example CAPAB could be the following:
63    
64     CAPAB :QS EX CHW IE EOB KLN HUB ENC ZIP
65    
66     Note that ENC is not required to be the last capab.
67    
68     The maximum allowable key length permitted for the encryption
69     cipher is 512 bits, as only 64 bytes of random data for the
70     key is available.
71    
72     Servers which support regeneration of session keys MAY also
73     include the DK ('Dynamic Key') capability.
74    
75     3.2 - New 'CRYPTLINK CIPHERS' command
76     -------------------------------------
77    
78     To prevent admins having to identically configure each end of
79     the link, the ircd SHOULD allow the admin to specify a list
80     of ciphers to be supported on a per link basis and/or a global
81     default.
82    
83     The second command sent over a CRYPTLINK enabled link MUST be the
84     CRYPTLINK CIPHERS command, to inform the remote server what ciphers
85     are supported by this end of the link:
86    
87     CRYPTLINK CIPHERS :cipher1/keylen cipher2/keylen, ...
88    
89     For example:
90    
91     CRYPTLINK CIPHERS :BF/168 BF/128 3DES/156
92    
93     The ciphers which are available as of the date this document was
94     written are listed in doc/README.openssl.
95    
96     All servers MUST, as minimum, support BF/128 encryption; admins
97     MAY choose to use another cipher which is available.
98    
99     If no ciphers are supported on BOTH servers, the receiving
100     server (the server which was connected to) should send back an
101     error response, instead of returning a CRYPTLINK CIPHERS command
102     of its own. See Section 3.5 ("Error Responses") for more
103     information on the process for doing this.
104    
105     3.3 - Key Generation
106     --------------------
107    
108     To initiate an encrypted link to another server, each server
109     is required to generate a 512-bit random key, of which a portion
110     will be used to decrypt all data received by the server. This key
111     MUST be generated by a cryptographically strong PRNG.
112    
113     This key should be stored, then encrypted to the server's private
114     key, encrypted to the remote server's public key, then base64 encoded
115     for transmission to the remote server.
116    
117     3.3 - Link Establishment
118     ------------------------
119    
120     Once the initiating server (server A) has connected to the
121     remote server (server B), it MUST send the CAPAB command,
122     listing its capabilities (including the new ENC capability).
123    
124     It MUST then send a CRYPTLINK CIPHER command, as described above.
125    
126     It MUST then send a CRYPTLINK SERV command using the following
127     syntax:
128    
129     CRYPTLINK SERV <irc.server.name> <key> :server info
130    
131     "<irc.server.name>" should be self-explanatory. "<key>" is the
132     base64-encoded key. "server info" is the server's M-line.
133    
134     Servers MUST NOT send a PASS or initial SERVER command over an
135     encrypted link. However, SERVER commands are still used to
136     introduce remote servers during the net burst, and as they link
137     to the network. All encrypted links MUST support the
138     TS protocol (as normally indicated by PASS ... :TS).
139    
140     On receiving the CAPAB command, server B MUST send its own
141     CAPAB/CRYPTLINK CIPHER/CRYPTLINK SERV commands and decrypt and
142     verify the signature on the key, unless there is an error
143     processing one of the received commands, in which case, an error
144     should be sent instead -- see Section 3.5 ("Error Responses").
145    
146     Server B should then select a cipher to be used bi-directionally
147     for data encryption. The server MAY determine the 'preferred'
148     cipher by using the order in which the ciphers were listed in
149     each CRYPTLINK CIPHER command, or simply select the first cipher
150     found to be compatible with both ends.
151    
152     Then Server B must interleave the received 64 byte key with its
153     generated 64 byte key as follows:
154    
155     R[0]G[0]R[1]G[2] ... R[62]G[62]R[63]G[64]
156    
157     It must then (using RSA) encrypt this key to its own private key
158     (to sign the data), then encrypt it to Server A's public key.
159    
160     It should then send a CRYPTLINK AUTH command as follows:
161    
162     CRYPTLINK AUTH <cipher>/<keylen> <base64-encoded new key>
163    
164     Once this command has been sent, the link MUST switch to being
165     encrypted. All future data sent over the link will be encrypted
166     using the selected symmetric encryption cipher, with the key
167     used to encrypt data being generated by using the first N bits,
168     where N is the key length of the negotiated cipher, from:
169    
170     R[0]G[1]R[2]G[3] ... R[60]G[61]R[62]G[63]
171    
172     At this point, Server B SHOULD send an SVINFO command, followed by
173     a normal net-burst.
174    
175     If the CAPAB lines exchanged indicated that both servers support
176     ZIPLINKS for this link, the data will be "zipped" immediately
177     before encrypting it. The data will start to be "zipped" after
178     the CRYPTLINK AUTH command is sent (i.e., at the same time as
179     encryption).
180    
181     After receiving a CRYPTLINK AUTH command Server A MUST decrypt the
182     key returned by Server B and ensure it is correct - taking care
183     to use the correct key to compare (i.e. G[0]R[0] ... G[63]R[63]).
184     If it is not, the server SHOULD notify online admins/IRCops, and
185     MUST drop the link.
186    
187     Server A will then send its own CRYPTLINK AUTH command, and switch
188     to an encrypted link as above. It SHOULD then send an SVINFO
189     command, and a normal net-burst.
190    
191     Server B MUST also validate the CRYPTLINK AUTH response as above.
192    
193     3.4 - Key Regeneration
194     ----------------------
195    
196     Although a capability (DK) to indicate support for dynamic key
197     regeneration has been defined, the protocol extensions required
198     to support this ability have not yet been defined.
199    
200     3.5 - Error Responses
201     ---------------------
202    
203     There are many possibilities of failure/error during the
204     negotiation process. Due to the vast diversity of these
205     errors, a generic error response mechanism should be implemented.
206    
207     The stock ERROR command is used to spit out errors regarding
208     all sorts of errors. Example:
209    
210     Example:
211    
212     ERROR :No compatible ciphers enabled. Aborting Link.
213    
214     This response MUST be sent immediately after any error is
215     encountered. For example, if the cipher negotiation phase
216     fails, the receiving server MUST send an ERROR response once this
217     is detected, and the socket MUST be closed.
218    
219     The output to the ERROR command can be anything. Do not assume
220     all ERROR messages for CRYPTLINK failures will be the same; they
221     MAY be changed by administrators.
222    
223     See Section 4.0 ("Communication Phase Examples") for some more
224     examples.
225    
226     3.6 - The Validation Mechanism
227     ------------------------------
228    
229     It is important to understand how the validation process
230     works. Section 3.2 ("Key Generation") briefly touches on
231     this subject.
232    
233     Both servers have a pair of keys on their file system: a PUBLIC
234     key, and a PRIVATE key.
235    
236     Each server should have a copy of the others' PUBLIC key.
237    
238     Herein we will refer to each server individually as "Server A" and
239     "Server B." In this example, Server A is connecting to Server B.
240    
241     Server A connects to Server B, and sends CAPAB, followed by
242     CRYPTLINK CIPHER.
243    
244     Server A then generates a unique 512-bit key phrase. This key phrase
245     is generated from a 64 bytes of random data taken from what is
246     referred to as a PRNG ("Pseudo-Random Number Generator"). A PRNG
247     could be something like /dev/urandom or something like the EGD
248     ("Entropy Gathering Daemon").
249    
250     The key phrase is encrypted to Server A's own PRIVATE key, to sign
251     the data. They key is then encrypted using Server 2's PUBLIC
252     key to prevent anyone sniffing the connecting from determining
253     the session key.
254    
255     This keyphrase is sent to Server B during the CRYPTLINK SERV
256     phase.
257    
258     After selecting a cipher, Server B takes the keyphrase, and
259     decrypts it using it's own PRIVATE key. If the decryption fails,
260     an ERROR is sent, and the connection is dropped. The signature
261     is then verified by decrypting the data with Server A's PUBLIC key.
262    
263     Server B then sends its own CRYPTLINK SERV command as above.
264    
265     Server B then combines the data with the locally generated
266     key with the received key as defined above[1], and signs
267     and encrypts this new key in the same way as the original, and
268     sends it to Server A.
269    
270     Server A then decrypts the key, and verifies it matches the
271     expected values, based on the key it generated, and the key
272     received from Server B. If it mismatches, Server A assumes
273     Server B could not decrypt Server A's data, and thus is not
274     in possession of Server B's private key.
275    
276     If the data matches, the authentication is legitimate, and
277     the servers officially link up.
278    
279     If the data does NOT match, then someone is being naughty.
280     In this case, an ERROR is sent, and the connection is dropped.
281    
282     4.0 - Communication Phase Examples
283     ----------------------------------
284    
285     Server #1 connects to Server #2
286     ===============================
287     1. Server #1 initiates connection to Server #2 on port 6667.
288     2. Server #2 answers on port 6667.
289     3. Server #1 sends:
290    
291     CAPAB :QS EX CHW IE EOB KLN GLN UID ZIP ENC.
292     CRYPTLINK CIPHERS :BF/168
293     CRYPTLINK SERV irc.server1 <keyphase> :We like IRC! Woo hoo!
294    
295     4. Server #2 checks to see if it supports BF/168. It does.
296     5. Server #2 sends:
297    
298     CAPAB :QS EX CHW IE EOB KLN GLN HUB UID ZIP ENC
299     CRYPTLINK CIPHERS :BF/168 BF/128
300     CRYPTLINK SERV irc.server2 <key> :My server is better than yours!
301     CRYPTLINK AUTH BF/168 <base64-encoded verification key>
302    
303     6. Server #1 checks to see if it supports one of BF/168 or BF/128,
304     and selects an outgoing cipher (BF/128).
305     7. Server #1 decrypts the key, and validates it. It's correct.
306     8. Server #1 sends:
307    
308     CRYPTLINK AUTH BF/128 <base64-encoded verification key>
309    
310     12. Server #1 now enters zip/encryption mode, and sends a net burst.
311     13. Server #2 decrypts the key, and validates it. It's correct.
312     14. Server #2 now enters zip/encryption mode, and sends a net burst.
313    
314     Server #1 connects to server #2, cipher fails
315     =============================================
316     1. Same as Steps 1-3 of the above example.
317     4. Server #2 checks to see if it supports BF/168. It does NOT.
318     5. Server #2 sends:
319    
320     ERROR :CRYPTLINK - No compatible ciphers enabled. Aborting Link.
321    
322     6. Server #1 is aware of the error, logs it, and/or informs
323     administrators/IRCops on the server of the cipher failure.
324     7. Server #2 closes the socket.
325    
326    
327     Server #1 connects to server #2, CRYPTAUTH fails
328     ================================================
329     1. Same as Steps 1-6 of the above example.
330     11. Server #1 decrypts the key, and validates it. It's INCORRECT.
331     12. Server #1 sends:
332    
333     ERROR :CRYPTLINK - Verification failed. Home, James.
334    
335     13. Server #1 is aware of the error, logs it, and/or informs
336     administrators/IRCops on the server of the key mismatch.
337     14. Server #1 closes the socket.
338    
339     $Id: cryptlink.txt,v 7.10 2003/05/31 07:01:39 lusky Exp $

Properties

Name Value
svn:eol-style native
svn:keywords "Id Revision"

svnadmin@ircd-hybrid.org
ViewVC Help
Powered by ViewVC 1.1.28