[ViewVC] Diff of: cvs/AnyEvent-MP/MP/Transport.pm

Comparing AnyEvent-MP/MP/Transport.pm (file contents):
Revision 1.42 by root, Fri Aug 28 20:57:42 2009 UTC vs.
Revision 1.43 by root, Fri Aug 28 23:06:33 2009 UTC

…		…
6		6
7	use AnyEvent::MP::Transport;	7	use AnyEvent::MP::Transport;
8		8
9	=head1 DESCRIPTION	9	=head1 DESCRIPTION
10		10
11	This implements the actual transport protocol for MP (it represents a	11	This module implements (and documents) the actual transport protocol for
12	single link), most of which is considered an implementation detail.	12	AEMP.
13		13
14	See the "PROTOCOL" section below if you want to write another client for	14	See the "PROTOCOL" section below if you want to write another client for
15	this protocol.	15	this protocol.
16		16
17	=head1 FUNCTIONS/METHODS	17	=head1 FUNCTIONS/METHODS
…		…
385		385
386	=back	386	=back
387		387
388	=head1 PROTOCOL	388	=head1 PROTOCOL
389		389
390	The protocol is relatively simple, and consists of three phases which are	390	The AEMP protocol is relatively simple, and consists of three phases which
391	symmetrical for both sides: greeting (followed by optionally switching to	391	are symmetrical for both sides: greeting (followed by optionally switching
392	TLS mode), authentication and packet exchange.	392	to TLS mode), authentication and packet exchange.
393		393
394	the protocol is designed to allow both full-text and binary streams.	394	The protocol is designed to allow both full-text and binary streams.
395		395
396	The greeting consists of two text lines that are ended by either an ASCII	396	The greeting consists of two text lines that are ended by either an ASCII
397	CR LF pair, or a single ASCII LF (recommended).	397	CR LF pair, or a single ASCII LF (recommended).
398		398
399	=head2 GREETING	399	=head2 GREETING
400		400
401	All the lines until after authentication must not exceed 4kb in length,	401	All the lines until after authentication must not exceed 4kb in length,
402	including delimiter. Afterwards there is no limit on the packet size that	402	including line delimiter. Afterwards there is no limit on the packet size
403	can be received.	403	that can be received.
404		404
405	=head3 First Greeting Line	405	=head3 First Greeting Line
406		406
407	Example:	407	Example:
408		408
409	aemp;0;fec.4a7720fc;127.0.0.1:1235,[::1]:1235;hmac_md6_64_256;json,storable;provider=AE-0.0	409	aemp;0;rain;tls_md6_64_256,hmac_md6_64_256,tls_anon,cleartext;json,storable;timeout=12;peeraddr=10.0.0.1:48082
410		410
411	The first line contains strings separated (not ended) by C<;>	411	The first line contains strings separated (not ended) by C<;>
412	characters. The first even ixtrings are fixed by the protocol, the	412	characters. The first five strings are fixed by the protocol, the
413	remaining strings are C<KEY=VALUE> pairs. None of them may contain C<;>	413	remaining strings are C<KEY=VALUE> pairs. None of them may contain C<;>
414	characters themselves.	414	characters themselves (when escaping is needed, use C<%3b> to represent
		415	C<;> and C<%25> to represent C<%>)-
415		416
416	The fixed strings are:	417	The fixed strings are:
417		418
418	=over 4	419	=over 4
419		420
420	=item protocol identification	421	=item protocol identification
421		422
422	The constant C<aemp> to identify the protocol.	423	The constant C<aemp> to identify this protocol.
423		424
424	=item protocol version	425	=item protocol version
425		426
426	The protocol version supported by this end, currently C<0>. If the	427	The protocol version supported by this end, currently C<0>. If the
427	versions don't match then no communication is possible. Minor extensions	428	versions don't match then no communication is possible. Minor extensions
428	are supposed to be handled through additional key-value pairs.	429	are supposed to be handled through additional key-value pairs.
429		430
430	=item the node id	431	=item the node ID
431		432
432	This is the node ID of the connecting node.	433	This is the node ID of the connecting node.
433		434
434	=item the acceptable authentication methods	435	=item the acceptable authentication methods
435		436
436	A comma-separated list of authentication methods supported by the	437	A comma-separated list of authentication methods supported by the
437	node. Note that AnyEvent::MP supports a C<hex_secret> authentication	438	node. Note that AnyEvent::MP supports a C<hex_secret> authentication
438	method that accepts a cleartext password (hex-encoded), but will not use	439	method that accepts a clear-text password (hex-encoded), but will not use
439	this auth method itself.	440	this authentication method itself.
440		441
441	The receiving side should choose the first auth method it supports.	442	The receiving side should choose the first authentication method it
		443	supports.
442		444
443	=item the acceptable framing formats	445	=item the acceptable framing formats
444		446
445	A comma-separated list of packet encoding/framign formats understood. The	447	A comma-separated list of packet encoding/framing formats understood. The
446	receiving side should choose the first framing format it supports for	448	receiving side should choose the first framing format it supports for
447	sending packets (which might be different from the format it has to accept).	449	sending packets (which might be different from the format it has to accept).
448		450
449	=back	451	=back
450		452
451	The remaining arguments are C<KEY=VALUE> pairs. The following key-value	453	The remaining arguments are C<KEY=VALUE> pairs. The following key-value
452	pairs are known at this time:	454	pairs are known at this time:
453		455
454	=over 4	456	=over 4
455
456	=item provider=<module-version>
457
458	The software provider for this implementation. For AnyEvent::MP, this is
459	C<AE-0.0> or whatever version it currently is at.
460
461	=item peeraddr=<host>:<port>
462
463	The peer address (socket address of the other side) as seen locally.
464
465	=item tls=<major>.<minor>
466
467	Indicates that the other side supports TLS (version should be 1.0) and
468	wishes to do a TLS handshake.
469		457
470	=item timeout=<seconds>	458	=item timeout=<seconds>
471		459
472	The amount of time after which this node should be detected as dead unless	460	The amount of time after which this node should be detected as dead unless
473	some data has been received. The node is responsible to send traffic	461	some data has been received. The node is responsible to send traffic
474	reasonably more often than this interval (such as every timeout minus five	462	reasonably more often than this interval (such as every timeout minus five
475	seconds).	463	seconds).
		464
		465	=item provider=<module-version>
		466
		467	The software provider for this implementation. For AnyEvent::MP, this is
		468	C<AE-0.0> or whatever version it currently is at.
		469
		470	=item peeraddr=<host>:<port>
		471
		472	The peer address (socket address of the other side) as seen locally.
		473
		474	=item tls=<major>.<minor>
		475
		476	Indicates that the other side supports TLS (version should be 1.0) and
		477	wishes to do a TLS handshake.
476		478
477	=back	479	=back
478		480
479	=head3 Second Greeting Line	481	=head3 Second Greeting Line
480		482
…		…
485	characters.	487	characters.
486		488
487	I<< The two nonces B<must> be different, and an aemp implementation	489	I<< The two nonces B<must> be different, and an aemp implementation
488	B<must> check and fail when they are identical >>.	490	B<must> check and fail when they are identical >>.
489		491
490	Example of a nonce line:	492	Example of a nonce line (yes, it's random-looking because it is random
		493	data):
491		494
492	p/I122ql7kJR8lumW3lXlXCeBnyDAvz8NQo3x5IFowE4	495	2XYhdG7/O6epFa4wuP0ujAEx1rXYWRcOypjUYK7eF6yWAQr7gwIN9m/2+mVvBrTPXz5GJDgfGm9d8QRABAbmAP/s
493		496
494	=head2 TLS handshake	497	=head2 TLS handshake
495		498
496	I<< If, after the handshake, both sides indicate interest in TLS, then the	499	I<< If, after the handshake, both sides indicate interest in TLS, then the
497	connection B<must> use TLS, or fail. >>	500	connection B<must> use TLS, or fail to continue. >>
498		501
499	Both sides compare their nonces, and the side who sent the lower nonce	502	Both sides compare their nonces, and the side who sent the lower nonce
500	value ("string" comparison on the raw octet values) becomes the client,	503	value ("string" comparison on the raw octet values) becomes the client,
501	and the one with the higher nonce the server.	504	and the one with the higher nonce the server.
502		505
…		…
524	=over 4	527	=over 4
525		528
526	=item cleartext	529	=item cleartext
527		530
528	This is simply the shared secret, lowercase-hex-encoded. This method is of	531	This is simply the shared secret, lowercase-hex-encoded. This method is of
529	course very insecure, unless TLS is used, which is why this module will	532	course very insecure if TLS is not used (and not completely secure even
530	accept, but not generate, cleartext auth replies.	533	if TLS is used), which is why this module will accept, but not generate,
		534	cleartext auth replies.
531		535
532	=item hmac_md6_64_256	536	=item hmac_md6_64_256
533		537
534	This method uses an MD6 HMAC with 64 bit blocksize and 256 bit hash. First, the shared secret	538	This method uses an MD6 HMAC with 64 bit blocksize and 256 bit hash, and
535	is hashed with MD6:	539	requires a shared secret. It is the preferred auth method when a shared
		540	secret is available.
		541
		542	First, the shared secret is hashed with MD6:
536		543
537	key = MD6 (secret)	544	key = MD6 (secret)
538		545
539	This secret is then used to generate the "local auth reply", by taking	546	This secret is then used to generate the "local auth reply", by taking
540	the two local greeting lines and the two remote greeting lines (without	547	the two local greeting lines and the two remote greeting lines (without
541	line endings), appending \012 to all of them, concatenating them and	548	line endings), appending \012 to all of them, concatenating them and
542	calculating the MD6 HMAC with the key.	549	calculating the MD6 HMAC with the key:
543		550
544	lauth = HMAC_MD6 key, "lgreeting1\012lgreeting2\012rgreeting1\012rgreeting2\012"	551	lauth = HMAC_MD6 key, "lgreeting1\012lgreeting2\012rgreeting1\012rgreeting2\012"
545		552
546	This authentication token is then lowercase-hex-encoded and sent to the	553	This authentication token is then lowercase-hex-encoded and sent to the
547	other side.	554	other side.
…		…
553		560
554	This is the token that is expected from the other side.	561	This is the token that is expected from the other side.
555		562
556	=item tls_anon	563	=item tls_anon
557		564
558	This type is only valid iff TLS was enabled and the TLS handshake	565	This type is only valid I<iff> TLS was enabled and the TLS handshake
559	was successful. It has no authentication data, as the server/client	566	was successful. It has no authentication data, as the server/client
560	certificate was successfully verified.	567	certificate was successfully verified.
561		568
562	This authentication type is slightly less secure than the others, as it	569	This authentication type is somewhat insecure, as it allows a
563	allows a man-in-the-middle attacker to change some of the connection	570	man-in-the-middle attacker to change some of the connection parameters
564	parameters (such as the framing format), although there is no known attack	571	(such as the framing format), although there is no known attack that
565	that exploits this in a way that is worse than just denying the service.	572	exploits this in a way that is worse than just denying the service.
566		573
567	By default, this implementation accepts but uses this authentication	574	By default, this implementation accepts but never generates this auth
568	method.	575	reply.
569		576
570	=item tls_md6_64_256	577	=item tls_md6_64_256
571		578
572	This type is only valid iff TLS was enabled and the TLS handshake	579	This type is only valid I<iff> TLS was enabled and the TLS handshake was
573	was successful.	580	successful.
574		581
575	This authentication type simply calculates:	582	This authentication type simply calculates:
576		583
577	lauth = MD6 "rgreeting1\012rgreeting2\012lgreeting1\012lgreeting2\012"	584	lauth = MD6 "rgreeting1\012rgreeting2\012lgreeting1\012lgreeting2\012"
578		585
579	and lowercase-hex encodes the result and sends it as authentication	586	and lowercase-hex encodes the result and sends it as authentication
580	data. No shared secret is required (authentication is done by TLS). The	587	data. No shared secret is required (authentication is done by TLS). The
581	checksum solely exists to make tinkering with the greeting hard.	588	checksum exists only to make tinkering with the greeting hard.
582		589
583	=back	590	=back
584		591
585	=item the authentication data	592	=item the authentication data
586		593
…		…
588	above.	595	above.
589		596
590	=item the framing protocol chosen	597	=item the framing protocol chosen
591		598
592	This must be one of the framing protocols offered by the other side in the	599	This must be one of the framing protocols offered by the other side in the
593	greeting. Each side must accept the choice of the other side.	600	greeting. Each side must accept the choice of the other side, and generate
		601	packets in the format it chose itself.
594		602
595	=back	603	=back
596		604
597	Example of an authentication reply:	605	Example of an authentication reply:
598		606
…		…
607		615
608	This is an actual protocol dump of a handshake, followed by a single data	616	This is an actual protocol dump of a handshake, followed by a single data
609	packet. The greater than/less than lines indicate the direction of the	617	packet. The greater than/less than lines indicate the direction of the
610	transfer only.	618	transfer only.
611		619
612	> aemp;0;nndKd+gn;10.0.0.1:4040;hmac_md6_64_256,cleartext;json,storable;provider=AE-0.0;peeraddr=127.0.0.1:1235	620	> 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
613	> sRG8bbc4TDbkpvH8FTP4HBs87OhepH6VuApoZqXXskuG	621	> yLgdG1ov/02shVkVQer3wzeuywZK+oraTdEQBmIqWHaegxSGDG4g+HqogLQbvdypFOsoDWJ1Sh4ImV4DMhvUBwTK
614	< aemp;0;nmpKd+gh;127.0.0.1:1235,[::1]:1235;hmac_md6_64_256,cleartext;json,storable;provider=AE-0.0;peeraddr=127.0.0.1:58760	622
615	< dCEUcL/LJVSTJcx8byEsOzrwhzJYOq+L3YcopA5T6EAo	623	< 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
616	> hmac_md6_64_256;9513d4b258975accfcb2ab7532b83690e9c119a502c612203332a591c7237788;json	624	< +xMQXP8ElfNmuvEhsmcp+s2wCJOuQAsPxSg3d2Ewhs6gBnJz+ypVdWJ/wAVrXqlIJfLeVS/CBy4gEGkyWHSuVb1L
617	< hmac_md6_64_256;0298d6ba2240faabb2b2e881cf86b97d70a113ca74a87dc006f9f1e9d3010f90;json	625
618	> ["","lookup","pinger","10.0.0.1:4040#nndKd+gn.a","resolved"]	626	> hmac_md6_64_256;5ad913855742ae5a03a5aeb7eafa4c78629de136bed6acd73eea36c9e98df44a;json
		627
		628	< hmac_md6_64_256;84cd590976f794914c2ca26dac3a207a57a6798b9171289c114de07cf0c20401;json
		629	< ["","AnyEvent::MP::_spawn","57Cs1CggVJjzYaQp13XXg4.c","AnyEvent::MP::Global::connect",0,"anon/57Cs1CggVJjzYaQp13XXg4"]
		630	...
		631
		632	The shared secret in use was C<8ugxrtw6H5tKnfPWfaSr4HGhE8MoJXmzTT1BWq7sLutNcD0IbXprQlZjIbl7MBKoeklG3IEfY9GlJthC0pENzk>.
619		633
620	=head1 SEE ALSO	634	=head1 SEE ALSO
621		635
622	L<AnyEvent::MP>.	636	L<AnyEvent::MP>.
623		637

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent-MP/MP/Transport.pm (file contents): Revision 1.42 by root, Fri Aug 28 20:57:42 2009 UTC vs. Revision 1.43 by root, Fri Aug 28 23:06:33 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP/Transport.pm (file contents):
Revision 1.42 by root, Fri Aug 28 20:57:42 2009 UTC vs.
Revision 1.43 by root, Fri Aug 28 23:06:33 2009 UTC