ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MP/MP/Transport.pm
Revision: 1.82
Committed: Fri Mar 23 03:24:41 2012 UTC (12 years, 2 months ago) by root
Branch: MAIN
Changes since 1.81: +2 -3 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 =head1 NAME
2    
3 root 1.13 AnyEvent::MP::Transport - actual transport protocol handler
4 root 1.1
5     =head1 SYNOPSIS
6    
7     use AnyEvent::MP::Transport;
8    
9     =head1 DESCRIPTION
10    
11 root 1.43 This module implements (and documents) the actual transport protocol for
12     AEMP.
13 root 1.1
14 root 1.7 See the "PROTOCOL" section below if you want to write another client for
15     this protocol.
16 root 1.1
17     =head1 FUNCTIONS/METHODS
18    
19     =over 4
20    
21     =cut
22    
23     package AnyEvent::MP::Transport;
24    
25     use common::sense;
26    
27 root 1.27 use Scalar::Util ();
28     use List::Util ();
29 root 1.1 use MIME::Base64 ();
30 root 1.82
31 root 1.2 use JSON::XS ();
32 root 1.19 use Digest::MD6 ();
33     use Digest::HMAC_MD6 ();
34    
35 root 1.82 use AnyEvent ();
36 root 1.1 use AnyEvent::Socket ();
37 root 1.27 use AnyEvent::Handle 4.92 ();
38 root 1.2
39 root 1.30 use AnyEvent::MP::Config ();
40    
41 root 1.55 our $PROTOCOL_VERSION = 1;
42 root 1.1
43 root 1.75 our @HOOK_GREET; # called at connect/accept time
44     our @HOOK_GREETED; # called at greeting1 time
45     our @HOOK_CONNECT; # called at data phase
46     our @HOOK_DESTROY; # called at destroy time
47 root 1.59 our %HOOK_PROTOCOL = (
48     "aemp-dataconn" => sub {
49     require AnyEvent::MP::DataConn;
50     &AnyEvent::MP::DataConn::_inject;
51     },
52     );
53 root 1.52
54 root 1.75 =item $listener = mp_server $host, $port, <constructor-args>
55 root 1.1
56     Creates a listener on the given host/port using
57     C<AnyEvent::Socket::tcp_server>.
58    
59     See C<new>, below, for constructor arguments.
60    
61 root 1.10 Defaults for peerhost, peerport and fh are provided.
62 root 1.1
63     =cut
64    
65 root 1.46 sub mp_server($$;%) {
66     my ($host, $port, %arg) = @_;
67 root 1.1
68     AnyEvent::Socket::tcp_server $host, $port, sub {
69     my ($fh, $host, $port) = @_;
70    
71 root 1.39 my $tp = new AnyEvent::MP::Transport
72 root 1.1 fh => $fh,
73     peerhost => $host,
74     peerport => $port,
75 root 1.46 %arg,
76 root 1.39 ;
77     $tp->{keepalive} = $tp;
78 root 1.46 }, delete $arg{prepare}
79 root 1.1 }
80    
81 root 1.2 =item $guard = mp_connect $host, $port, <constructor-args>, $cb->($transport)
82    
83     =cut
84    
85     sub mp_connect {
86 root 1.31 my $release = pop;
87 root 1.2 my ($host, $port, @args) = @_;
88    
89 root 1.51 new AnyEvent::MP::Transport
90     connect => [$host, $port],
91 root 1.52 peerhost => $host,
92     peerport => $port,
93 root 1.51 release => $release,
94     @args,
95     ;
96 root 1.2 }
97    
98 root 1.1 =item new AnyEvent::MP::Transport
99    
100 root 1.75 Create a new transport - usually used via C<mp_server> or C<mp_connect>
101     instead.
102    
103 root 1.1 # immediately starts negotiation
104     my $transport = new AnyEvent::MP::Transport
105 root 1.2 # mandatory
106 root 1.75 fh => $filehandle,
107     local_id => $identifier,
108     on_recv => sub { receive-callback },
109     on_error => sub { error-callback },
110 root 1.1
111     # optional
112 root 1.75 on_greet => sub { before sending greeting },
113     on_greeted => sub { after receiving greeting },
114 root 1.1 on_connect => sub { successful-connect-callback },
115 root 1.75 greeting => { key => value },
116 root 1.1
117     # tls support
118 root 1.75 tls_ctx => AnyEvent::TLS,
119     peername => $peername, # for verification
120 root 1.1 ;
121    
122     =cut
123    
124     sub new {
125     my ($class, %arg) = @_;
126    
127     my $self = bless \%arg, $class;
128    
129     {
130     Scalar::Util::weaken (my $self = $self);
131    
132 root 1.50 my $config = $AnyEvent::MP::Kernel::CONFIG;
133 root 1.30
134 root 1.50 my $timeout = $config->{monitor_timeout};
135 root 1.64 my $lframing = $config->{framing_format};
136 root 1.50 my $auth_snd = $config->{auth_offer};
137     my $auth_rcv = $config->{auth_accept};
138 root 1.31
139 root 1.42 $self->{secret} = $config->{secret}
140     unless exists $self->{secret};
141 root 1.2
142 root 1.42 my $secret = $self->{secret};
143 root 1.19
144 root 1.30 if (exists $config->{cert}) {
145 root 1.42 $self->{tls_ctx} = {
146 root 1.19 sslv2 => 0,
147     sslv3 => 0,
148     tlsv1 => 1,
149     verify => 1,
150 root 1.30 cert => $config->{cert},
151     ca_cert => $config->{cert},
152 root 1.19 verify_require_client_cert => 1,
153     };
154     }
155    
156 root 1.1 $self->{hdl} = new AnyEvent::Handle
157 root 1.52 +($self->{fh} ? (fh => $self->{fh}) : (connect => $self->{connect})),
158 root 1.63 autocork => $config->{autocork},
159     no_delay => exists $config->{nodelay} ? $config->{nodelay} : 1,
160 root 1.48 keepalive => 1,
161     on_error => sub {
162 root 1.1 $self->error ($_[2]);
163     },
164 root 1.49 rtimeout => $timeout,
165 root 1.1 ;
166    
167 root 1.52 my $greeting_kv = $self->{local_greeting} ||= {};
168 root 1.24
169 root 1.42 $greeting_kv->{tls} = "1.0" if $self->{tls_ctx};
170 root 1.75 $greeting_kv->{provider} = "AE-$AnyEvent::MP::Config::VERSION";
171 root 1.7 $greeting_kv->{peeraddr} = AnyEvent::Socket::format_hostport $self->{peerhost}, $self->{peerport};
172 root 1.23
173 root 1.58 my $protocol = $self->{protocol} || "aemp";
174    
175 root 1.52 # can modify greeting_kv
176 root 1.75 $_->($self) for $protocol eq "aemp" ? @HOOK_GREET : ();
177     (delete $self->{on_greet})->($self)
178     if exists $self->{on_greet};
179 root 1.52
180 root 1.1 # send greeting
181 root 1.58 my $lgreeting1 = "$protocol;$PROTOCOL_VERSION"
182 root 1.52 . ";$AnyEvent::MP::Kernel::NODE"
183 root 1.50 . ";" . (join ",", @$auth_rcv)
184     . ";" . (join ",", @$lframing)
185 root 1.7 . (join "", map ";$_=$greeting_kv->{$_}", keys %$greeting_kv);
186 root 1.12
187 root 1.31 my $lgreeting2 = MIME::Base64::encode_base64 AnyEvent::MP::Kernel::nonce (66), "";
188 root 1.1
189 root 1.7 $self->{hdl}->push_write ("$lgreeting1\012$lgreeting2\012");
190 root 1.72 return unless $self;
191 root 1.1
192     # expect greeting
193 root 1.12 $self->{hdl}->rbuf_max (4 * 1024);
194 root 1.1 $self->{hdl}->push_read (line => sub {
195 root 1.7 my $rgreeting1 = $_[1];
196 root 1.1
197 root 1.26 my ($aemp, $version, $rnode, $auths, $framings, @kv) = split /;/, $rgreeting1;
198 root 1.1
199 root 1.53 $self->{remote_node} = $rnode;
200    
201     $self->{remote_greeting} = {
202     map /^([^=]+)(?:=(.*))?/ ? ($1 => $2) : (),
203     @kv
204     };
205    
206 root 1.60 # maybe upgrade the protocol
207     if ($protocol eq "aemp" and $aemp =~ /^aemp-\w+$/) {
208     # maybe check for existence of the protocol handler?
209     $self->{protocol} = $protocol = $aemp;
210     }
211    
212 root 1.75 $_->($self) for $protocol eq "aemp" ? @HOOK_GREETED : ();
213     (delete $self->{on_greeted})->($self)
214     if exists $self->{on_greeted};
215 root 1.54
216 root 1.60 if ($aemp ne $protocol and $aemp ne "aemp") {
217 root 1.58 return $self->error ("unparsable greeting, expected '$protocol', got '$aemp'");
218 root 1.12 } elsif ($version != $PROTOCOL_VERSION) {
219     return $self->error ("version mismatch (we: $PROTOCOL_VERSION, they: $version)");
220 root 1.60 } elsif ($protocol eq "aemp") {
221     if ($rnode eq $AnyEvent::MP::Kernel::NODE) {
222     return $self->error ("I refuse to talk to myself");
223     } elsif ($AnyEvent::MP::Kernel::NODE{$rnode} && $AnyEvent::MP::Kernel::NODE{$rnode}{transport}) {
224     return $self->error ("$rnode already connected, not connecting again.");
225     }
226 root 1.1 }
227    
228 root 1.7 # read nonce
229     $self->{hdl}->push_read (line => sub {
230     my $rgreeting2 = $_[1];
231    
232 root 1.19 "$lgreeting1\012$lgreeting2" ne "$rgreeting1\012$rgreeting2" # echo attack?
233     or return $self->error ("authentication error, echo attack?");
234    
235 root 1.41 my $tls = $self->{tls_ctx} && 1 == int $self->{remote_greeting}{tls};
236    
237     my $s_auth;
238     for my $auth_ (split /,/, $auths) {
239 root 1.50 if (grep $auth_ eq $_, @$auth_snd and ($auth_ !~ /^tls_/ or $tls)) {
240 root 1.41 $s_auth = $auth_;
241     last;
242     }
243     }
244    
245     defined $s_auth
246     or return $self->error ("$auths: no common auth type supported");
247    
248     my $s_framing;
249     for my $framing_ (split /,/, $framings) {
250 root 1.50 if (grep $framing_ eq $_, @$lframing) {
251 root 1.41 $s_framing = $framing_;
252     last;
253     }
254     }
255    
256     defined $s_framing
257     or return $self->error ("$framings: no common framing method supported");
258    
259 root 1.30 my $key;
260 root 1.19 my $lauth;
261    
262 root 1.41 if ($tls) {
263 root 1.8 $self->{tls} = $lgreeting2 lt $rgreeting2 ? "connect" : "accept";
264     $self->{hdl}->starttls ($self->{tls}, $self->{tls_ctx});
265 root 1.66 return unless $self->{hdl}; # starttls might destruct us
266 root 1.41
267     $lauth =
268     $s_auth eq "tls_anon" ? ""
269     : $s_auth eq "tls_md6_64_256" ? Digest::MD6::md6_hex "$lgreeting1\012$lgreeting2\012$rgreeting1\012$rgreeting2\012"
270     : return $self->error ("$s_auth: fatal, selected unsupported snd auth method");
271    
272 root 1.30 } elsif (length $secret) {
273 root 1.41 return $self->error ("$s_auth: fatal, selected unsupported snd auth method")
274     unless $s_auth eq "hmac_md6_64_256"; # hardcoded atm.
275    
276 root 1.30 $key = Digest::MD6::md6 $secret;
277 root 1.19 # we currently only support hmac_md6_64_256
278     $lauth = Digest::HMAC_MD6::hmac_md6_hex $key, "$lgreeting1\012$lgreeting2\012$rgreeting1\012$rgreeting2\012", 64, 256;
279 root 1.41
280 root 1.30 } else {
281     return $self->error ("unable to handshake TLS and no shared secret configured");
282 root 1.8 }
283 root 1.2
284 root 1.7 $self->{hdl}->push_write ("$s_auth;$lauth;$s_framing\012");
285 root 1.72 return unless $self;
286 root 1.2
287 root 1.19 # read the authentication response
288 root 1.7 $self->{hdl}->push_read (line => sub {
289     my ($hdl, $rline) = @_;
290 root 1.2
291 root 1.7 my ($auth_method, $rauth2, $r_framing) = split /;/, $rline;
292 root 1.1
293 root 1.19 my $rauth =
294     $auth_method eq "hmac_md6_64_256" ? Digest::HMAC_MD6::hmac_md6_hex $key, "$rgreeting1\012$rgreeting2\012$lgreeting1\012$lgreeting2\012", 64, 256
295     : $auth_method eq "cleartext" ? unpack "H*", $secret
296 root 1.41 : $auth_method eq "tls_anon" ? ($tls ? "" : "\012\012") # \012\012 never matches
297     : $auth_method eq "tls_md6_64_256" ? ($tls ? Digest::MD6::md6_hex "$rgreeting1\012$rgreeting2\012$lgreeting1\012$lgreeting2\012" : "\012\012")
298     : return $self->error ("$auth_method: fatal, selected unsupported rcv auth method");
299 root 1.19
300 root 1.7 if ($rauth2 ne $rauth) {
301     return $self->error ("authentication failure/shared secret mismatch");
302     }
303 root 1.1
304 root 1.79 $self->{r_framing} = $r_framing;
305 root 1.7 $self->{s_framing} = $s_framing;
306 root 1.2
307 root 1.7 $hdl->rbuf_max (undef);
308 root 1.1
309 root 1.49 # we rely on TCP retransmit timeouts and keepalives
310     $self->{hdl}->rtimeout (undef);
311    
312     $self->{remote_greeting}{untrusted} = 1
313     if $auth_method eq "tls_anon";
314 root 1.24
315 root 1.64 if ($protocol eq "aemp" and $self->{hdl}) {
316 root 1.77 # listener-less nodes need to continuously probe
317 root 1.78 # unless (@$AnyEvent::MP::Kernel::BINDS) {
318     # $self->{hdl}->wtimeout ($timeout);
319     # $self->{hdl}->on_wtimeout (sub { $self->{send}->([]) });
320     # }
321 root 1.58
322     # receive handling
323 root 1.79 $self->set_snd_framing;
324     $self->set_rcv_framing;
325 root 1.58 }
326 root 1.67
327     $self->connected;
328 root 1.7 });
329 root 1.1 });
330     });
331     }
332    
333     $self
334     }
335    
336 root 1.79 sub set_snd_framing {
337     my ($self) = @_;
338    
339     my $framing = $self->{s_framing};
340     my $hdl = $self->{hdl};
341     my $push_write = $hdl->can ("push_write");
342    
343     if ($framing eq "json") {
344     $self->{send} = sub {
345     $push_write->($hdl, JSON::XS::encode_json $_[0]);
346     };
347     } else {
348     $self->{send} = sub {
349     $push_write->($hdl, $framing => $_[0]);
350     };
351     }
352     }
353    
354     sub set_rcv_framing {
355     my ($self) = @_;
356    
357     my $node = $self->{remote_node};
358     my $framing = $self->{r_framing};
359     my $hdl = $self->{hdl};
360     my $push_read = $hdl->can ("push_read");
361    
362     if ($framing eq "json") {
363     my $coder = JSON::XS->new->utf8;
364    
365     $hdl->on_read (sub {
366     $AnyEvent::MP::Kernel::SRCNODE = $node;
367    
368     AnyEvent::MP::Kernel::_inject (@$_)
369     for $coder->incr_parse (delete $_[0]{rbuf});
370    
371     ()
372     });
373     } else {
374     my $rmsg; $rmsg = $self->{rmsg} = sub {
375     $push_read->($_[0], $framing => $rmsg);
376    
377     $AnyEvent::MP::Kernel::SRCNODE = $node;
378     AnyEvent::MP::Kernel::_inject (@{ $_[1] });
379     };
380     eval {
381     $push_read->($hdl, $framing => $rmsg);
382     };
383     Scalar::Util::weaken $rmsg;
384     return $self->error ("$framing: unusable remote framing")
385     if $@;
386     }
387     }
388    
389 root 1.1 sub error {
390     my ($self, $msg) = @_;
391    
392 root 1.39 delete $self->{keepalive};
393    
394 root 1.58 if ($self->{protocol}) {
395 root 1.59 $HOOK_PROTOCOL{$self->{protocol}}->($self, $msg);
396 root 1.58 } else {
397 root 1.81 AE::log 8 => "$self->{peerhost}:$self->{peerport} $msg.";
398 root 1.39
399 root 1.58 $self->{node}->transport_error (transport_error => $self->{node}{id}, $msg)
400     if $self->{node} && $self->{node}{transport} == $self;
401     }
402 root 1.31
403     (delete $self->{release})->()
404     if exists $self->{release};
405    
406 root 1.4 $self->destroy;
407 root 1.1 }
408    
409 root 1.2 sub connected {
410     my ($self) = @_;
411    
412 root 1.39 delete $self->{keepalive};
413    
414 root 1.58 if ($self->{protocol}) {
415 root 1.59 $self->{hdl}->on_error (undef);
416     $HOOK_PROTOCOL{$self->{protocol}}->($self, undef);
417 root 1.58 } else {
418 root 1.81 AE::log 9 => "$self->{peerhost}:$self->{peerport} connected as $self->{remote_node}.";
419 root 1.58
420     my $node = AnyEvent::MP::Kernel::add_node ($self->{remote_node});
421     Scalar::Util::weaken ($self->{node} = $node);
422     $node->transport_connect ($self);
423 root 1.39
424 root 1.75 $_->($self) for @HOOK_CONNECT;
425 root 1.58 }
426 root 1.61
427     (delete $self->{release})->()
428     if exists $self->{release};
429 root 1.75
430     (delete $self->{on_connect})->($self)
431     if exists $self->{on_connect};
432 root 1.2 }
433    
434 root 1.1 sub destroy {
435     my ($self) = @_;
436    
437 root 1.42 (delete $self->{release})->()
438     if exists $self->{release};
439    
440 root 1.2 $self->{hdl}->destroy
441     if $self->{hdl};
442 root 1.52
443 root 1.75 (delete $self->{on_destroy})->($self)
444     if exists $self->{on_destroy};
445 root 1.59 $_->($self) for $self->{protocol} ? () : @HOOK_DESTROY;
446 root 1.74
447     $self->{protocol} = "destroyed"; # to keep hooks from invoked twice.
448 root 1.1 }
449    
450     sub DESTROY {
451     my ($self) = @_;
452    
453     $self->destroy;
454     }
455    
456     =back
457    
458 root 1.7 =head1 PROTOCOL
459    
460 root 1.59 The AEMP protocol is comparatively simple, and consists of three phases
461     which are symmetrical for both sides: greeting (followed by optionally
462     switching to TLS mode), authentication and packet exchange.
463 root 1.7
464 root 1.43 The protocol is designed to allow both full-text and binary streams.
465 root 1.7
466     The greeting consists of two text lines that are ended by either an ASCII
467     CR LF pair, or a single ASCII LF (recommended).
468    
469     =head2 GREETING
470    
471 root 1.15 All the lines until after authentication must not exceed 4kb in length,
472 root 1.43 including line delimiter. Afterwards there is no limit on the packet size
473     that can be received.
474 root 1.15
475     =head3 First Greeting Line
476 root 1.12
477 root 1.16 Example:
478    
479 root 1.43 aemp;0;rain;tls_md6_64_256,hmac_md6_64_256,tls_anon,cleartext;json,storable;timeout=12;peeraddr=10.0.0.1:48082
480 root 1.16
481     The first line contains strings separated (not ended) by C<;>
482 root 1.43 characters. The first five strings are fixed by the protocol, the
483 root 1.16 remaining strings are C<KEY=VALUE> pairs. None of them may contain C<;>
484 root 1.43 characters themselves (when escaping is needed, use C<%3b> to represent
485     C<;> and C<%25> to represent C<%>)-
486 root 1.16
487 root 1.12 The fixed strings are:
488 root 1.7
489     =over 4
490    
491 root 1.18 =item protocol identification
492 root 1.7
493 root 1.43 The constant C<aemp> to identify this protocol.
494 root 1.7
495     =item protocol version
496    
497 root 1.55 The protocol version supported by this end, currently C<1>. If the
498 root 1.12 versions don't match then no communication is possible. Minor extensions
499 root 1.18 are supposed to be handled through additional key-value pairs.
500 root 1.7
501 root 1.43 =item the node ID
502 root 1.7
503 root 1.57 This is the node ID of the connecting node.
504 root 1.7
505     =item the acceptable authentication methods
506    
507     A comma-separated list of authentication methods supported by the
508     node. Note that AnyEvent::MP supports a C<hex_secret> authentication
509 root 1.43 method that accepts a clear-text password (hex-encoded), but will not use
510     this authentication method itself.
511 root 1.7
512 root 1.43 The receiving side should choose the first authentication method it
513     supports.
514 root 1.7
515     =item the acceptable framing formats
516    
517 root 1.43 A comma-separated list of packet encoding/framing formats understood. The
518 root 1.7 receiving side should choose the first framing format it supports for
519     sending packets (which might be different from the format it has to accept).
520    
521 root 1.10 =back
522 root 1.8
523     The remaining arguments are C<KEY=VALUE> pairs. The following key-value
524     pairs are known at this time:
525    
526     =over 4
527    
528     =item provider=<module-version>
529    
530     The software provider for this implementation. For AnyEvent::MP, this is
531     C<AE-0.0> or whatever version it currently is at.
532    
533     =item peeraddr=<host>:<port>
534    
535 root 1.39 The peer address (socket address of the other side) as seen locally.
536 root 1.8
537     =item tls=<major>.<minor>
538    
539     Indicates that the other side supports TLS (version should be 1.0) and
540     wishes to do a TLS handshake.
541    
542 root 1.76 =item nproto=<major>.<fractional>
543    
544     Informs the other side of the node protocol implemented by this
545     node. Major version mismatches are fatal. If this key is missing, then it
546     is assumed that the node doesn't support the node protocol.
547    
548     The node protocol is currently undocumented, but includes port
549     monitoring, spawning and informational requests.
550    
551     =item gproto=<major>.<fractional>
552    
553     Informs the other side of the global protocol implemented by this
554     node. Major version mismatches are fatal. If this key is missing, then it
555     is assumed that the node doesn't support the global protocol.
556    
557     The global protocol is currently undocumented, but includes node address
558     lookup and shared database operations.
559    
560 root 1.8 =back
561    
562 root 1.15 =head3 Second Greeting Line
563    
564 root 1.8 After this greeting line there will be a second line containing a
565     cryptographic nonce, i.e. random data of high quality. To keep the
566     protocol text-only, these are usually 32 base64-encoded octets, but
567     it could be anything that doesn't contain any ASCII CR or ASCII LF
568     characters.
569    
570 root 1.14 I<< The two nonces B<must> be different, and an aemp implementation
571     B<must> check and fail when they are identical >>.
572    
573 root 1.43 Example of a nonce line (yes, it's random-looking because it is random
574     data):
575 root 1.8
576 root 1.43 2XYhdG7/O6epFa4wuP0ujAEx1rXYWRcOypjUYK7eF6yWAQr7gwIN9m/2+mVvBrTPXz5GJDgfGm9d8QRABAbmAP/s
577 root 1.8
578     =head2 TLS handshake
579    
580 root 1.14 I<< If, after the handshake, both sides indicate interest in TLS, then the
581 root 1.43 connection B<must> use TLS, or fail to continue. >>
582 root 1.8
583     Both sides compare their nonces, and the side who sent the lower nonce
584     value ("string" comparison on the raw octet values) becomes the client,
585     and the one with the higher nonce the server.
586    
587     =head2 AUTHENTICATION PHASE
588    
589     After the greeting is received (and the optional TLS handshake),
590     the authentication phase begins, which consists of sending a single
591     C<;>-separated line with three fixed strings and any number of
592     C<KEY=VALUE> pairs.
593    
594     The three fixed strings are:
595    
596     =over 4
597    
598     =item the authentication method chosen
599    
600     This must be one of the methods offered by the other side in the greeting.
601    
602 root 1.41 Note that all methods starting with C<tls_> are only valid I<iff> TLS was
603     successfully handshaked (and to be secure the implementation must enforce
604     this).
605    
606 root 1.13 The currently supported authentication methods are:
607    
608     =over 4
609    
610     =item cleartext
611    
612     This is simply the shared secret, lowercase-hex-encoded. This method is of
613 root 1.43 course very insecure if TLS is not used (and not completely secure even
614     if TLS is used), which is why this module will accept, but not generate,
615     cleartext auth replies.
616 root 1.13
617     =item hmac_md6_64_256
618    
619 root 1.43 This method uses an MD6 HMAC with 64 bit blocksize and 256 bit hash, and
620     requires a shared secret. It is the preferred auth method when a shared
621     secret is available.
622    
623     First, the shared secret is hashed with MD6:
624 root 1.13
625     key = MD6 (secret)
626    
627     This secret is then used to generate the "local auth reply", by taking
628     the two local greeting lines and the two remote greeting lines (without
629     line endings), appending \012 to all of them, concatenating them and
630 root 1.43 calculating the MD6 HMAC with the key:
631 root 1.13
632     lauth = HMAC_MD6 key, "lgreeting1\012lgreeting2\012rgreeting1\012rgreeting2\012"
633    
634     This authentication token is then lowercase-hex-encoded and sent to the
635     other side.
636    
637     Then the remote auth reply is generated using the same method, but local
638     and remote greeting lines swapped:
639    
640     rauth = HMAC_MD6 key, "rgreeting1\012rgreeting2\012lgreeting1\012lgreeting2\012"
641    
642     This is the token that is expected from the other side.
643    
644 root 1.41 =item tls_anon
645 root 1.19
646 root 1.43 This type is only valid I<iff> TLS was enabled and the TLS handshake
647 root 1.19 was successful. It has no authentication data, as the server/client
648     certificate was successfully verified.
649    
650 root 1.43 This authentication type is somewhat insecure, as it allows a
651     man-in-the-middle attacker to change some of the connection parameters
652     (such as the framing format), although there is no known attack that
653     exploits this in a way that is worse than just denying the service.
654 root 1.41
655 root 1.43 By default, this implementation accepts but never generates this auth
656     reply.
657 root 1.41
658     =item tls_md6_64_256
659    
660 root 1.43 This type is only valid I<iff> TLS was enabled and the TLS handshake was
661     successful.
662 root 1.41
663     This authentication type simply calculates:
664    
665     lauth = MD6 "rgreeting1\012rgreeting2\012lgreeting1\012lgreeting2\012"
666    
667     and lowercase-hex encodes the result and sends it as authentication
668     data. No shared secret is required (authentication is done by TLS). The
669 root 1.43 checksum exists only to make tinkering with the greeting hard.
670 root 1.19
671 root 1.13 =back
672    
673 root 1.8 =item the authentication data
674    
675 root 1.13 The authentication data itself, usually base64 or hex-encoded data, see
676     above.
677 root 1.8
678     =item the framing protocol chosen
679    
680     This must be one of the framing protocols offered by the other side in the
681 root 1.43 greeting. Each side must accept the choice of the other side, and generate
682     packets in the format it chose itself.
683 root 1.8
684     =back
685    
686 root 1.16 Example of an authentication reply:
687 root 1.9
688 root 1.13 hmac_md6_64_256;363d5175df38bd9eaddd3f6ca18aa1c0c4aa22f0da245ac638d048398c26b8d3;json
689 root 1.9
690 root 1.8 =head2 DATA PHASE
691    
692     After this, packets get exchanged using the chosen framing protocol. It is
693     quite possible that both sides use a different framing protocol.
694    
695 root 1.16 =head2 FULL EXAMPLE
696    
697 root 1.17 This is an actual protocol dump of a handshake, followed by a single data
698 root 1.16 packet. The greater than/less than lines indicate the direction of the
699     transfer only.
700    
701 root 1.43 > aemp;0;anon/57Cs1CggVJjzYaQp13XXg4;tls_md6_64_256,hmac_md6_64_256,tls_anon,cleartext;json,storable;provider=AE-0.8;timeout=12;peeraddr=10.0.0.17:4040
702     > yLgdG1ov/02shVkVQer3wzeuywZK+oraTdEQBmIqWHaegxSGDG4g+HqogLQbvdypFOsoDWJ1Sh4ImV4DMhvUBwTK
703    
704     < aemp;0;ruth;tls_md6_64_256,hmac_md6_64_256,tls_anon,cleartext;json,storable;provider=AE-0.8;timeout=12;peeraddr=10.0.0.1:37108
705     < +xMQXP8ElfNmuvEhsmcp+s2wCJOuQAsPxSg3d2Ewhs6gBnJz+ypVdWJ/wAVrXqlIJfLeVS/CBy4gEGkyWHSuVb1L
706    
707     > hmac_md6_64_256;5ad913855742ae5a03a5aeb7eafa4c78629de136bed6acd73eea36c9e98df44a;json
708    
709     < hmac_md6_64_256;84cd590976f794914c2ca26dac3a207a57a6798b9171289c114de07cf0c20401;json
710     < ["","AnyEvent::MP::_spawn","57Cs1CggVJjzYaQp13XXg4.c","AnyEvent::MP::Global::connect",0,"anon/57Cs1CggVJjzYaQp13XXg4"]
711     ...
712    
713     The shared secret in use was C<8ugxrtw6H5tKnfPWfaSr4HGhE8MoJXmzTT1BWq7sLutNcD0IbXprQlZjIbl7MBKoeklG3IEfY9GlJthC0pENzk>.
714 root 1.16
715 root 1.65 =head2 SIMPLE HANDSHAKE FOR NON-PERL NODES
716    
717     Implementing the full set of options for handshaking can be a daunting
718     task.
719    
720     If security is not so important (because you only connect locally and
721     control the host, a common case), and you want to interface with an AEMP
722     node from another programming language, then you can also implement a
723     simplified handshake.
724    
725     For example, in a simple implementation you could decide to simply not
726     check the authenticity of the other side and use cleartext authentication
727     yourself. The the handshake is as simple as sending three lines of text,
728     reading three lines of text, and then you can exchange JSON-formatted
729     messages:
730    
731     aemp;1;<nodename>;hmac_md6_64_256;json
732     <nonce>
733     cleartext;<hexencoded secret>;json
734    
735     The nodename should be unique within the network, preferably unique with
736     every connection, the <nonce> could be empty or some random data, and the
737     hexencoded secret would be the shared secret, in lowercase hex (e.g. if
738     the secret is "geheim", the hex-encoded version would be "67656865696d").
739    
740     Note that apart from the low-level handshake and framing protocol, there
741     is a high-level protocol, e.g. for monitoring, building the mesh or
742     spawning. All these messages are sent to the node port (the empty string)
743     and can safely be ignored if you do not need the relevant functionality.
744    
745     =head3 USEFUL HINTS
746    
747     Since taking part in the global protocol to find port groups is
748     nontrivial, hardcoding port names should be considered as well, i.e. the
749     non-Perl node could simply listen to messages for a few well-known ports.
750    
751     Alternatively, the non-Perl node could call a (already loaded) function
752     in the Perl node by sending it a special message:
753    
754     ["", "Some::Function::name", "myownport", 1, 2, 3]
755    
756     This would call the function C<Some::Function::name> with the string
757     C<myownport> and some additional arguments.
758    
759 root 1.49 =head2 MONITORING
760    
761     Monitoring the connection itself is transport-specific. For TCP, all
762     connection monitoring is currently left to TCP retransmit time-outs
763     on a busy link, and TCP keepalive (which should be enabled) for idle
764     connections.
765    
766     This is not sufficient for listener-less nodes, however: they need
767     to regularly send data (30 seconds, or the monitoring interval, is
768     recommended), so TCP actively probes.
769    
770 elmex 1.73 Future implementations of AnyEvent::MP::Transport might query the kernel TCP
771 root 1.49 buffer after a write timeout occurs, and if it is non-empty, shut down the
772     connections, but this is an area of future research :)
773    
774     =head2 NODE PROTOCOL
775    
776     The transport simply transfers messages, but to implement a full node, a
777     special node port must exist that understands a number of requests.
778    
779     If you are interested in implementing this, drop us a note so we finish
780     the documentation.
781    
782 root 1.1 =head1 SEE ALSO
783    
784 root 1.29 L<AnyEvent::MP>.
785 root 1.1
786     =head1 AUTHOR
787    
788     Marc Lehmann <schmorp@schmorp.de>
789     http://home.schmorp.de/
790    
791     =cut
792    
793     1
794