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