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, 2 months ago) by root
Branch: MAIN
Changes since 1.76: +2 -2 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 =head1 NAME
2
3 AnyEvent::MP::Transport - actual transport protocol handler
4
5 =head1 SYNOPSIS
6
7 use AnyEvent::MP::Transport;
8
9 =head1 DESCRIPTION
10
11 This module implements (and documents) the actual transport protocol for
12 AEMP.
13
14 See the "PROTOCOL" section below if you want to write another client for
15 this protocol.
16
17 =head1 FUNCTIONS/METHODS
18
19 =over 4
20
21 =cut
22
23 package AnyEvent::MP::Transport;
24
25 use common::sense;
26
27 use Scalar::Util ();
28 use List::Util ();
29 use MIME::Base64 ();
30 use Storable ();
31 use JSON::XS ();
32
33 use Digest::MD6 ();
34 use Digest::HMAC_MD6 ();
35
36 use AE ();
37 use AnyEvent::Socket ();
38 use AnyEvent::Handle 4.92 ();
39
40 use AnyEvent::MP::Config ();
41
42 our $PROTOCOL_VERSION = 1;
43
44 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 our %HOOK_PROTOCOL = (
49 "aemp-dataconn" => sub {
50 require AnyEvent::MP::DataConn;
51 &AnyEvent::MP::DataConn::_inject;
52 },
53 );
54
55 =item $listener = mp_server $host, $port, <constructor-args>
56
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 Defaults for peerhost, peerport and fh are provided.
63
64 =cut
65
66 sub mp_server($$;%) {
67 my ($host, $port, %arg) = @_;
68
69 AnyEvent::Socket::tcp_server $host, $port, sub {
70 my ($fh, $host, $port) = @_;
71
72 my $tp = new AnyEvent::MP::Transport
73 fh => $fh,
74 peerhost => $host,
75 peerport => $port,
76 %arg,
77 ;
78 $tp->{keepalive} = $tp;
79 }, delete $arg{prepare}
80 }
81
82 =item $guard = mp_connect $host, $port, <constructor-args>, $cb->($transport)
83
84 =cut
85
86 sub mp_connect {
87 my $release = pop;
88 my ($host, $port, @args) = @_;
89
90 new AnyEvent::MP::Transport
91 connect => [$host, $port],
92 peerhost => $host,
93 peerport => $port,
94 release => $release,
95 @args,
96 ;
97 }
98
99 =item new AnyEvent::MP::Transport
100
101 Create a new transport - usually used via C<mp_server> or C<mp_connect>
102 instead.
103
104 # immediately starts negotiation
105 my $transport = new AnyEvent::MP::Transport
106 # mandatory
107 fh => $filehandle,
108 local_id => $identifier,
109 on_recv => sub { receive-callback },
110 on_error => sub { error-callback },
111
112 # optional
113 on_greet => sub { before sending greeting },
114 on_greeted => sub { after receiving greeting },
115 on_connect => sub { successful-connect-callback },
116 greeting => { key => value },
117
118 # tls support
119 tls_ctx => AnyEvent::TLS,
120 peername => $peername, # for verification
121 ;
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 my $config = $AnyEvent::MP::Kernel::CONFIG;
134
135 my $timeout = $config->{monitor_timeout};
136 my $lframing = $config->{framing_format};
137 my $auth_snd = $config->{auth_offer};
138 my $auth_rcv = $config->{auth_accept};
139
140 $self->{secret} = $config->{secret}
141 unless exists $self->{secret};
142
143 my $secret = $self->{secret};
144
145 if (exists $config->{cert}) {
146 $self->{tls_ctx} = {
147 sslv2 => 0,
148 sslv3 => 0,
149 tlsv1 => 1,
150 verify => 1,
151 cert => $config->{cert},
152 ca_cert => $config->{cert},
153 verify_require_client_cert => 1,
154 };
155 }
156
157 $self->{hdl} = new AnyEvent::Handle
158 +($self->{fh} ? (fh => $self->{fh}) : (connect => $self->{connect})),
159 autocork => $config->{autocork},
160 no_delay => exists $config->{nodelay} ? $config->{nodelay} : 1,
161 keepalive => 1,
162 on_error => sub {
163 $self->error ($_[2]);
164 },
165 rtimeout => $timeout,
166 ;
167
168 my $greeting_kv = $self->{local_greeting} ||= {};
169
170 $greeting_kv->{tls} = "1.0" if $self->{tls_ctx};
171 $greeting_kv->{provider} = "AE-$AnyEvent::MP::Config::VERSION";
172 $greeting_kv->{peeraddr} = AnyEvent::Socket::format_hostport $self->{peerhost}, $self->{peerport};
173
174 my $protocol = $self->{protocol} || "aemp";
175
176 # can modify greeting_kv
177 $_->($self) for $protocol eq "aemp" ? @HOOK_GREET : ();
178 (delete $self->{on_greet})->($self)
179 if exists $self->{on_greet};
180
181 # send greeting
182 my $lgreeting1 = "$protocol;$PROTOCOL_VERSION"
183 . ";$AnyEvent::MP::Kernel::NODE"
184 . ";" . (join ",", @$auth_rcv)
185 . ";" . (join ",", @$lframing)
186 . (join "", map ";$_=$greeting_kv->{$_}", keys %$greeting_kv);
187
188 my $lgreeting2 = MIME::Base64::encode_base64 AnyEvent::MP::Kernel::nonce (66), "";
189
190 $self->{hdl}->push_write ("$lgreeting1\012$lgreeting2\012");
191 return unless $self;
192
193 # expect greeting
194 $self->{hdl}->rbuf_max (4 * 1024);
195 $self->{hdl}->push_read (line => sub {
196 my $rgreeting1 = $_[1];
197
198 my ($aemp, $version, $rnode, $auths, $framings, @kv) = split /;/, $rgreeting1;
199
200 $self->{remote_node} = $rnode;
201
202 $self->{remote_greeting} = {
203 map /^([^=]+)(?:=(.*))?/ ? ($1 => $2) : (),
204 @kv
205 };
206
207 # 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 $_->($self) for $protocol eq "aemp" ? @HOOK_GREETED : ();
214 (delete $self->{on_greeted})->($self)
215 if exists $self->{on_greeted};
216
217 if ($aemp ne $protocol and $aemp ne "aemp") {
218 return $self->error ("unparsable greeting, expected '$protocol', got '$aemp'");
219 } elsif ($version != $PROTOCOL_VERSION) {
220 return $self->error ("version mismatch (we: $PROTOCOL_VERSION, they: $version)");
221 } 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 }
228
229 # read nonce
230 $self->{hdl}->push_read (line => sub {
231 my $rgreeting2 = $_[1];
232
233 "$lgreeting1\012$lgreeting2" ne "$rgreeting1\012$rgreeting2" # echo attack?
234 or return $self->error ("authentication error, echo attack?");
235
236 my $tls = $self->{tls_ctx} && 1 == int $self->{remote_greeting}{tls};
237
238 my $s_auth;
239 for my $auth_ (split /,/, $auths) {
240 if (grep $auth_ eq $_, @$auth_snd and ($auth_ !~ /^tls_/ or $tls)) {
241 $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 if (grep $framing_ eq $_, @$lframing) {
252 $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 my $key;
261 my $lauth;
262
263 if ($tls) {
264 $self->{tls} = $lgreeting2 lt $rgreeting2 ? "connect" : "accept";
265 $self->{hdl}->starttls ($self->{tls}, $self->{tls_ctx});
266 return unless $self->{hdl}; # starttls might destruct us
267
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 } elsif (length $secret) {
274 return $self->error ("$s_auth: fatal, selected unsupported snd auth method")
275 unless $s_auth eq "hmac_md6_64_256"; # hardcoded atm.
276
277 $key = Digest::MD6::md6 $secret;
278 # 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
281 } else {
282 return $self->error ("unable to handshake TLS and no shared secret configured");
283 }
284
285 $self->{hdl}->push_write ("$s_auth;$lauth;$s_framing\012");
286 return unless $self;
287
288 # read the authentication response
289 $self->{hdl}->push_read (line => sub {
290 my ($hdl, $rline) = @_;
291
292 my ($auth_method, $rauth2, $r_framing) = split /;/, $rline;
293
294 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 : $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
301 if ($rauth2 ne $rauth) {
302 return $self->error ("authentication failure/shared secret mismatch");
303 }
304
305 $self->{s_framing} = $s_framing;
306
307 $hdl->rbuf_max (undef);
308
309 # 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
315 if ($protocol eq "aemp" and $self->{hdl}) {
316 # listener-less nodes need to continuously probe
317 unless (@$AnyEvent::MP::Kernel::BINDS) {
318 $self->{hdl}->wtimeout ($timeout);
319 $self->{hdl}->on_wtimeout (sub { $self->{send}->([]) });
320 }
321
322 # receive handling
323
324 my $push_write = $hdl->can ("push_write");
325 my $push_read = $hdl->can ("push_read");
326
327 if ($s_framing eq "json") {
328 $self->{send} = sub {
329 $push_write->($hdl, JSON::XS::encode_json $_[0]);
330 };
331 } 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
340 $hdl->on_read (sub {
341 local $AnyEvent::MP::Kernel::SRCNODE = $self->{node};
342
343 AnyEvent::MP::Kernel::_inject (@$_)
344 for $coder->incr_parse (delete $_[0]{rbuf});
345
346 ()
347 });
348 } else {
349 my $rmsg; $rmsg = $self->{rmsg} = sub {
350 $push_read->($_[0], $r_framing => $rmsg);
351
352 local $AnyEvent::MP::Kernel::SRCNODE = $self->{node};
353 AnyEvent::MP::Kernel::_inject (@{ $_[1] });
354 };
355 eval {
356 $push_read->($_[0], $r_framing => $rmsg);
357 };
358 Scalar::Util::weaken $rmsg;
359 return $self->error ("$r_framing: unusable remote framing")
360 if $@;
361 }
362 }
363
364 $self->connected;
365 });
366 });
367 });
368 }
369
370 $self
371 }
372
373 sub error {
374 my ($self, $msg) = @_;
375
376 delete $self->{keepalive};
377
378 if ($self->{protocol}) {
379 $HOOK_PROTOCOL{$self->{protocol}}->($self, $msg);
380 } else {
381 $AnyEvent::MP::Kernel::WARN->(9, "$self->{peerhost}:$self->{peerport} $msg");#d#
382
383 $self->{node}->transport_error (transport_error => $self->{node}{id}, $msg)
384 if $self->{node} && $self->{node}{transport} == $self;
385 }
386
387 (delete $self->{release})->()
388 if exists $self->{release};
389
390 # $AnyEvent::MP::Kernel::WARN->(7, "$self->{peerhost}:$self->{peerport}: $msg");
391 $self->destroy;
392 }
393
394 sub connected {
395 my ($self) = @_;
396
397 delete $self->{keepalive};
398
399 if ($self->{protocol}) {
400 $self->{hdl}->on_error (undef);
401 $HOOK_PROTOCOL{$self->{protocol}}->($self, undef);
402 } 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
409 $_->($self) for @HOOK_CONNECT;
410 }
411
412 (delete $self->{release})->()
413 if exists $self->{release};
414
415 (delete $self->{on_connect})->($self)
416 if exists $self->{on_connect};
417 }
418
419 sub destroy {
420 my ($self) = @_;
421
422 (delete $self->{release})->()
423 if exists $self->{release};
424
425 $self->{hdl}->destroy
426 if $self->{hdl};
427
428 (delete $self->{on_destroy})->($self)
429 if exists $self->{on_destroy};
430 $_->($self) for $self->{protocol} ? () : @HOOK_DESTROY;
431
432 $self->{protocol} = "destroyed"; # to keep hooks from invoked twice.
433 }
434
435 sub DESTROY {
436 my ($self) = @_;
437
438 $self->destroy;
439 }
440
441 =back
442
443 =head1 PROTOCOL
444
445 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
449 The protocol is designed to allow both full-text and binary streams.
450
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 All the lines until after authentication must not exceed 4kb in length,
457 including line delimiter. Afterwards there is no limit on the packet size
458 that can be received.
459
460 =head3 First Greeting Line
461
462 Example:
463
464 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
466 The first line contains strings separated (not ended) by C<;>
467 characters. The first five strings are fixed by the protocol, the
468 remaining strings are C<KEY=VALUE> pairs. None of them may contain C<;>
469 characters themselves (when escaping is needed, use C<%3b> to represent
470 C<;> and C<%25> to represent C<%>)-
471
472 The fixed strings are:
473
474 =over 4
475
476 =item protocol identification
477
478 The constant C<aemp> to identify this protocol.
479
480 =item protocol version
481
482 The protocol version supported by this end, currently C<1>. If the
483 versions don't match then no communication is possible. Minor extensions
484 are supposed to be handled through additional key-value pairs.
485
486 =item the node ID
487
488 This is the node ID of the connecting node.
489
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 method that accepts a clear-text password (hex-encoded), but will not use
495 this authentication method itself.
496
497 The receiving side should choose the first authentication method it
498 supports.
499
500 =item the acceptable framing formats
501
502 A comma-separated list of packet encoding/framing formats understood. The
503 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 =back
507
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 The peer address (socket address of the other side) as seen locally.
521
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 =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 =back
546
547 =head3 Second Greeting Line
548
549 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 I<< The two nonces B<must> be different, and an aemp implementation
556 B<must> check and fail when they are identical >>.
557
558 Example of a nonce line (yes, it's random-looking because it is random
559 data):
560
561 2XYhdG7/O6epFa4wuP0ujAEx1rXYWRcOypjUYK7eF6yWAQr7gwIN9m/2+mVvBrTPXz5GJDgfGm9d8QRABAbmAP/s
562
563 =head2 TLS handshake
564
565 I<< If, after the handshake, both sides indicate interest in TLS, then the
566 connection B<must> use TLS, or fail to continue. >>
567
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 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 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 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
602 =item hmac_md6_64_256
603
604 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
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 calculating the MD6 HMAC with the key:
616
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 =item tls_anon
630
631 This type is only valid I<iff> TLS was enabled and the TLS handshake
632 was successful. It has no authentication data, as the server/client
633 certificate was successfully verified.
634
635 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
640 By default, this implementation accepts but never generates this auth
641 reply.
642
643 =item tls_md6_64_256
644
645 This type is only valid I<iff> TLS was enabled and the TLS handshake was
646 successful.
647
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 checksum exists only to make tinkering with the greeting hard.
655
656 =back
657
658 =item the authentication data
659
660 The authentication data itself, usually base64 or hex-encoded data, see
661 above.
662
663 =item the framing protocol chosen
664
665 This must be one of the framing protocols offered by the other side in the
666 greeting. Each side must accept the choice of the other side, and generate
667 packets in the format it chose itself.
668
669 =back
670
671 Example of an authentication reply:
672
673 hmac_md6_64_256;363d5175df38bd9eaddd3f6ca18aa1c0c4aa22f0da245ac638d048398c26b8d3;json
674
675 =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 =head2 FULL EXAMPLE
681
682 This is an actual protocol dump of a handshake, followed by a single data
683 packet. The greater than/less than lines indicate the direction of the
684 transfer only.
685
686 > 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
700 =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 =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 Future implementations of AnyEvent::MP::Transport might query the kernel TCP
756 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 =head1 SEE ALSO
768
769 L<AnyEvent::MP>.
770
771 =head1 AUTHOR
772
773 Marc Lehmann <schmorp@schmorp.de>
774 http://home.schmorp.de/
775
776 =cut
777
778 1
779