ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MP/MP/Transport.pm
Revision: 1.77
Committed: Sun Mar 4 15:12:26 2012 UTC (12 years, 3 months ago) by root
Branch: MAIN
Changes since 1.76: +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.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     unless (@$AnyEvent::MP::Kernel::BINDS) {
318 root 1.59 $self->{hdl}->wtimeout ($timeout);
319 root 1.71 $self->{hdl}->on_wtimeout (sub { $self->{send}->([]) });
320 root 1.59 }
321 root 1.58
322     # receive handling
323 root 1.45
324 root 1.68 my $push_write = $hdl->can ("push_write");
325     my $push_read = $hdl->can ("push_read");
326    
327 root 1.69 if ($s_framing eq "json") {
328 root 1.68 $self->{send} = sub {
329     $push_write->($hdl, JSON::XS::encode_json $_[0]);
330     };
331 root 1.69 } else {
332     $self->{send} = sub {
333     $push_write->($hdl, $s_framing => $_[0]);
334     };
335     }
336    
337     if ($r_framing eq "json") {
338     my $coder = JSON::XS->new->utf8;
339 root 1.68
340     $hdl->on_read (sub {
341 root 1.70 local $AnyEvent::MP::Kernel::SRCNODE = $self->{node};
342 root 1.68
343     AnyEvent::MP::Kernel::_inject (@$_)
344     for $coder->incr_parse (delete $_[0]{rbuf});
345    
346     ()
347     });
348 root 1.65 } else {
349     my $rmsg; $rmsg = $self->{rmsg} = sub {
350 root 1.67 $push_read->($_[0], $r_framing => $rmsg);
351 root 1.65
352 root 1.70 local $AnyEvent::MP::Kernel::SRCNODE = $self->{node};
353 root 1.65 AnyEvent::MP::Kernel::_inject (@{ $_[1] });
354     };
355     eval {
356 root 1.67 $push_read->($_[0], $r_framing => $rmsg);
357 root 1.65 };
358     Scalar::Util::weaken $rmsg;
359     return $self->error ("$r_framing: unusable remote framing")
360     if $@;
361     }
362 root 1.58 }
363 root 1.67
364     $self->connected;
365 root 1.7 });
366 root 1.1 });
367     });
368     }
369    
370     $self
371     }
372    
373     sub error {
374     my ($self, $msg) = @_;
375    
376 root 1.39 delete $self->{keepalive};
377    
378 root 1.58 if ($self->{protocol}) {
379 root 1.59 $HOOK_PROTOCOL{$self->{protocol}}->($self, $msg);
380 root 1.58 } else {
381     $AnyEvent::MP::Kernel::WARN->(9, "$self->{peerhost}:$self->{peerport} $msg");#d#
382 root 1.39
383 root 1.58 $self->{node}->transport_error (transport_error => $self->{node}{id}, $msg)
384     if $self->{node} && $self->{node}{transport} == $self;
385     }
386 root 1.31
387     (delete $self->{release})->()
388     if exists $self->{release};
389    
390 root 1.37 # $AnyEvent::MP::Kernel::WARN->(7, "$self->{peerhost}:$self->{peerport}: $msg");
391 root 1.4 $self->destroy;
392 root 1.1 }
393    
394 root 1.2 sub connected {
395     my ($self) = @_;
396    
397 root 1.39 delete $self->{keepalive};
398    
399 root 1.58 if ($self->{protocol}) {
400 root 1.59 $self->{hdl}->on_error (undef);
401     $HOOK_PROTOCOL{$self->{protocol}}->($self, undef);
402 root 1.58 } else {
403     $AnyEvent::MP::Kernel::WARN->(9, "$self->{peerhost}:$self->{peerport} connected as $self->{remote_node}");
404    
405     my $node = AnyEvent::MP::Kernel::add_node ($self->{remote_node});
406     Scalar::Util::weaken ($self->{node} = $node);
407     $node->transport_connect ($self);
408 root 1.39
409 root 1.75 $_->($self) for @HOOK_CONNECT;
410 root 1.58 }
411 root 1.61
412     (delete $self->{release})->()
413     if exists $self->{release};
414 root 1.75
415     (delete $self->{on_connect})->($self)
416     if exists $self->{on_connect};
417 root 1.2 }
418    
419 root 1.1 sub destroy {
420     my ($self) = @_;
421    
422 root 1.42 (delete $self->{release})->()
423     if exists $self->{release};
424    
425 root 1.2 $self->{hdl}->destroy
426     if $self->{hdl};
427 root 1.52
428 root 1.75 (delete $self->{on_destroy})->($self)
429     if exists $self->{on_destroy};
430 root 1.59 $_->($self) for $self->{protocol} ? () : @HOOK_DESTROY;
431 root 1.74
432     $self->{protocol} = "destroyed"; # to keep hooks from invoked twice.
433 root 1.1 }
434    
435     sub DESTROY {
436     my ($self) = @_;
437    
438     $self->destroy;
439     }
440    
441     =back
442    
443 root 1.7 =head1 PROTOCOL
444    
445 root 1.59 The AEMP protocol is comparatively simple, and consists of three phases
446     which are symmetrical for both sides: greeting (followed by optionally
447     switching to TLS mode), authentication and packet exchange.
448 root 1.7
449 root 1.43 The protocol is designed to allow both full-text and binary streams.
450 root 1.7
451     The greeting consists of two text lines that are ended by either an ASCII
452     CR LF pair, or a single ASCII LF (recommended).
453    
454     =head2 GREETING
455    
456 root 1.15 All the lines until after authentication must not exceed 4kb in length,
457 root 1.43 including line delimiter. Afterwards there is no limit on the packet size
458     that can be received.
459 root 1.15
460     =head3 First Greeting Line
461 root 1.12
462 root 1.16 Example:
463    
464 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
465 root 1.16
466     The first line contains strings separated (not ended) by C<;>
467 root 1.43 characters. The first five strings are fixed by the protocol, the
468 root 1.16 remaining strings are C<KEY=VALUE> pairs. None of them may contain C<;>
469 root 1.43 characters themselves (when escaping is needed, use C<%3b> to represent
470     C<;> and C<%25> to represent C<%>)-
471 root 1.16
472 root 1.12 The fixed strings are:
473 root 1.7
474     =over 4
475    
476 root 1.18 =item protocol identification
477 root 1.7
478 root 1.43 The constant C<aemp> to identify this protocol.
479 root 1.7
480     =item protocol version
481    
482 root 1.55 The protocol version supported by this end, currently C<1>. If the
483 root 1.12 versions don't match then no communication is possible. Minor extensions
484 root 1.18 are supposed to be handled through additional key-value pairs.
485 root 1.7
486 root 1.43 =item the node ID
487 root 1.7
488 root 1.57 This is the node ID of the connecting node.
489 root 1.7
490     =item the acceptable authentication methods
491    
492     A comma-separated list of authentication methods supported by the
493     node. Note that AnyEvent::MP supports a C<hex_secret> authentication
494 root 1.43 method that accepts a clear-text password (hex-encoded), but will not use
495     this authentication method itself.
496 root 1.7
497 root 1.43 The receiving side should choose the first authentication method it
498     supports.
499 root 1.7
500     =item the acceptable framing formats
501    
502 root 1.43 A comma-separated list of packet encoding/framing formats understood. The
503 root 1.7 receiving side should choose the first framing format it supports for
504     sending packets (which might be different from the format it has to accept).
505    
506 root 1.10 =back
507 root 1.8
508     The remaining arguments are C<KEY=VALUE> pairs. The following key-value
509     pairs are known at this time:
510    
511     =over 4
512    
513     =item provider=<module-version>
514    
515     The software provider for this implementation. For AnyEvent::MP, this is
516     C<AE-0.0> or whatever version it currently is at.
517    
518     =item peeraddr=<host>:<port>
519    
520 root 1.39 The peer address (socket address of the other side) as seen locally.
521 root 1.8
522     =item tls=<major>.<minor>
523    
524     Indicates that the other side supports TLS (version should be 1.0) and
525     wishes to do a TLS handshake.
526    
527 root 1.76 =item nproto=<major>.<fractional>
528    
529     Informs the other side of the node protocol implemented by this
530     node. Major version mismatches are fatal. If this key is missing, then it
531     is assumed that the node doesn't support the node protocol.
532    
533     The node protocol is currently undocumented, but includes port
534     monitoring, spawning and informational requests.
535    
536     =item gproto=<major>.<fractional>
537    
538     Informs the other side of the global protocol implemented by this
539     node. Major version mismatches are fatal. If this key is missing, then it
540     is assumed that the node doesn't support the global protocol.
541    
542     The global protocol is currently undocumented, but includes node address
543     lookup and shared database operations.
544    
545 root 1.8 =back
546    
547 root 1.15 =head3 Second Greeting Line
548    
549 root 1.8 After this greeting line there will be a second line containing a
550     cryptographic nonce, i.e. random data of high quality. To keep the
551     protocol text-only, these are usually 32 base64-encoded octets, but
552     it could be anything that doesn't contain any ASCII CR or ASCII LF
553     characters.
554    
555 root 1.14 I<< The two nonces B<must> be different, and an aemp implementation
556     B<must> check and fail when they are identical >>.
557    
558 root 1.43 Example of a nonce line (yes, it's random-looking because it is random
559     data):
560 root 1.8
561 root 1.43 2XYhdG7/O6epFa4wuP0ujAEx1rXYWRcOypjUYK7eF6yWAQr7gwIN9m/2+mVvBrTPXz5GJDgfGm9d8QRABAbmAP/s
562 root 1.8
563     =head2 TLS handshake
564    
565 root 1.14 I<< If, after the handshake, both sides indicate interest in TLS, then the
566 root 1.43 connection B<must> use TLS, or fail to continue. >>
567 root 1.8
568     Both sides compare their nonces, and the side who sent the lower nonce
569     value ("string" comparison on the raw octet values) becomes the client,
570     and the one with the higher nonce the server.
571    
572     =head2 AUTHENTICATION PHASE
573    
574     After the greeting is received (and the optional TLS handshake),
575     the authentication phase begins, which consists of sending a single
576     C<;>-separated line with three fixed strings and any number of
577     C<KEY=VALUE> pairs.
578    
579     The three fixed strings are:
580    
581     =over 4
582    
583     =item the authentication method chosen
584    
585     This must be one of the methods offered by the other side in the greeting.
586    
587 root 1.41 Note that all methods starting with C<tls_> are only valid I<iff> TLS was
588     successfully handshaked (and to be secure the implementation must enforce
589     this).
590    
591 root 1.13 The currently supported authentication methods are:
592    
593     =over 4
594    
595     =item cleartext
596    
597     This is simply the shared secret, lowercase-hex-encoded. This method is of
598 root 1.43 course very insecure if TLS is not used (and not completely secure even
599     if TLS is used), which is why this module will accept, but not generate,
600     cleartext auth replies.
601 root 1.13
602     =item hmac_md6_64_256
603    
604 root 1.43 This method uses an MD6 HMAC with 64 bit blocksize and 256 bit hash, and
605     requires a shared secret. It is the preferred auth method when a shared
606     secret is available.
607    
608     First, the shared secret is hashed with MD6:
609 root 1.13
610     key = MD6 (secret)
611    
612     This secret is then used to generate the "local auth reply", by taking
613     the two local greeting lines and the two remote greeting lines (without
614     line endings), appending \012 to all of them, concatenating them and
615 root 1.43 calculating the MD6 HMAC with the key:
616 root 1.13
617     lauth = HMAC_MD6 key, "lgreeting1\012lgreeting2\012rgreeting1\012rgreeting2\012"
618    
619     This authentication token is then lowercase-hex-encoded and sent to the
620     other side.
621    
622     Then the remote auth reply is generated using the same method, but local
623     and remote greeting lines swapped:
624    
625     rauth = HMAC_MD6 key, "rgreeting1\012rgreeting2\012lgreeting1\012lgreeting2\012"
626    
627     This is the token that is expected from the other side.
628    
629 root 1.41 =item tls_anon
630 root 1.19
631 root 1.43 This type is only valid I<iff> TLS was enabled and the TLS handshake
632 root 1.19 was successful. It has no authentication data, as the server/client
633     certificate was successfully verified.
634    
635 root 1.43 This authentication type is somewhat insecure, as it allows a
636     man-in-the-middle attacker to change some of the connection parameters
637     (such as the framing format), although there is no known attack that
638     exploits this in a way that is worse than just denying the service.
639 root 1.41
640 root 1.43 By default, this implementation accepts but never generates this auth
641     reply.
642 root 1.41
643     =item tls_md6_64_256
644    
645 root 1.43 This type is only valid I<iff> TLS was enabled and the TLS handshake was
646     successful.
647 root 1.41
648     This authentication type simply calculates:
649    
650     lauth = MD6 "rgreeting1\012rgreeting2\012lgreeting1\012lgreeting2\012"
651    
652     and lowercase-hex encodes the result and sends it as authentication
653     data. No shared secret is required (authentication is done by TLS). The
654 root 1.43 checksum exists only to make tinkering with the greeting hard.
655 root 1.19
656 root 1.13 =back
657    
658 root 1.8 =item the authentication data
659    
660 root 1.13 The authentication data itself, usually base64 or hex-encoded data, see
661     above.
662 root 1.8
663     =item the framing protocol chosen
664    
665     This must be one of the framing protocols offered by the other side in the
666 root 1.43 greeting. Each side must accept the choice of the other side, and generate
667     packets in the format it chose itself.
668 root 1.8
669     =back
670    
671 root 1.16 Example of an authentication reply:
672 root 1.9
673 root 1.13 hmac_md6_64_256;363d5175df38bd9eaddd3f6ca18aa1c0c4aa22f0da245ac638d048398c26b8d3;json
674 root 1.9
675 root 1.8 =head2 DATA PHASE
676    
677     After this, packets get exchanged using the chosen framing protocol. It is
678     quite possible that both sides use a different framing protocol.
679    
680 root 1.16 =head2 FULL EXAMPLE
681    
682 root 1.17 This is an actual protocol dump of a handshake, followed by a single data
683 root 1.16 packet. The greater than/less than lines indicate the direction of the
684     transfer only.
685    
686 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
687     > yLgdG1ov/02shVkVQer3wzeuywZK+oraTdEQBmIqWHaegxSGDG4g+HqogLQbvdypFOsoDWJ1Sh4ImV4DMhvUBwTK
688    
689     < 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
690     < +xMQXP8ElfNmuvEhsmcp+s2wCJOuQAsPxSg3d2Ewhs6gBnJz+ypVdWJ/wAVrXqlIJfLeVS/CBy4gEGkyWHSuVb1L
691    
692     > hmac_md6_64_256;5ad913855742ae5a03a5aeb7eafa4c78629de136bed6acd73eea36c9e98df44a;json
693    
694     < hmac_md6_64_256;84cd590976f794914c2ca26dac3a207a57a6798b9171289c114de07cf0c20401;json
695     < ["","AnyEvent::MP::_spawn","57Cs1CggVJjzYaQp13XXg4.c","AnyEvent::MP::Global::connect",0,"anon/57Cs1CggVJjzYaQp13XXg4"]
696     ...
697    
698     The shared secret in use was C<8ugxrtw6H5tKnfPWfaSr4HGhE8MoJXmzTT1BWq7sLutNcD0IbXprQlZjIbl7MBKoeklG3IEfY9GlJthC0pENzk>.
699 root 1.16
700 root 1.65 =head2 SIMPLE HANDSHAKE FOR NON-PERL NODES
701    
702     Implementing the full set of options for handshaking can be a daunting
703     task.
704    
705     If security is not so important (because you only connect locally and
706     control the host, a common case), and you want to interface with an AEMP
707     node from another programming language, then you can also implement a
708     simplified handshake.
709    
710     For example, in a simple implementation you could decide to simply not
711     check the authenticity of the other side and use cleartext authentication
712     yourself. The the handshake is as simple as sending three lines of text,
713     reading three lines of text, and then you can exchange JSON-formatted
714     messages:
715    
716     aemp;1;<nodename>;hmac_md6_64_256;json
717     <nonce>
718     cleartext;<hexencoded secret>;json
719    
720     The nodename should be unique within the network, preferably unique with
721     every connection, the <nonce> could be empty or some random data, and the
722     hexencoded secret would be the shared secret, in lowercase hex (e.g. if
723     the secret is "geheim", the hex-encoded version would be "67656865696d").
724    
725     Note that apart from the low-level handshake and framing protocol, there
726     is a high-level protocol, e.g. for monitoring, building the mesh or
727     spawning. All these messages are sent to the node port (the empty string)
728     and can safely be ignored if you do not need the relevant functionality.
729    
730     =head3 USEFUL HINTS
731    
732     Since taking part in the global protocol to find port groups is
733     nontrivial, hardcoding port names should be considered as well, i.e. the
734     non-Perl node could simply listen to messages for a few well-known ports.
735    
736     Alternatively, the non-Perl node could call a (already loaded) function
737     in the Perl node by sending it a special message:
738    
739     ["", "Some::Function::name", "myownport", 1, 2, 3]
740    
741     This would call the function C<Some::Function::name> with the string
742     C<myownport> and some additional arguments.
743    
744 root 1.49 =head2 MONITORING
745    
746     Monitoring the connection itself is transport-specific. For TCP, all
747     connection monitoring is currently left to TCP retransmit time-outs
748     on a busy link, and TCP keepalive (which should be enabled) for idle
749     connections.
750    
751     This is not sufficient for listener-less nodes, however: they need
752     to regularly send data (30 seconds, or the monitoring interval, is
753     recommended), so TCP actively probes.
754    
755 elmex 1.73 Future implementations of AnyEvent::MP::Transport might query the kernel TCP
756 root 1.49 buffer after a write timeout occurs, and if it is non-empty, shut down the
757     connections, but this is an area of future research :)
758    
759     =head2 NODE PROTOCOL
760    
761     The transport simply transfers messages, but to implement a full node, a
762     special node port must exist that understands a number of requests.
763    
764     If you are interested in implementing this, drop us a note so we finish
765     the documentation.
766    
767 root 1.1 =head1 SEE ALSO
768    
769 root 1.29 L<AnyEvent::MP>.
770 root 1.1
771     =head1 AUTHOR
772    
773     Marc Lehmann <schmorp@schmorp.de>
774     http://home.schmorp.de/
775    
776     =cut
777    
778     1
779