From 5e86db71550371bdb48855f0eb4b4e18d1846665 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juhani=20Krekel=C3=A4?= <juhani@krekelä.fi>
Date: Wed, 17 Jul 2019 00:06:43 +0300
Subject: [PATCH] Start working on ethermess.7

---
 ethermess.7 | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 ethermess.7

diff --git a/ethermess.7 b/ethermess.7
new file mode 100644
index 0000000..b3ee0e4
--- /dev/null
+++ b/ethermess.7
@@ -0,0 +1,102 @@
+.Dd July 16, 2019
+.Dt ETHERMESS 7
+.Os
+.Sh NAME
+.Nm EtherMess
+.Nd messaging protocol for bare Ethernet
+.Sh DESCRIPTION
+.Nm
+is a protocol for direct messaging over raw Ethernet frames.
+.Pp
+The structure of an Ethernet frame containing an EtherMess packet is as
+follows:
+.TS
+allbox;
+lb	lb	lb	lb
+l	l	l	l
+^	l	l	l
+^	l	l	l
+l	l	l	l
+^	l	l	l
+l	l	l	l
+l	l	l	l.
+Part	Field	Length (B)	Contents
+Ethernet header	Destination	6	Recipient's MAC
+	Source	6	Sender's MAC
+	EtherType	2	0xDA7A
+EtherMess header	Version	1	0x00
+	Packet type	1	(defined below)
+Payload		0 - 1494	(depends on packet type)
+Padding		0 - 1494	0x00
+.TE
+.Pp
+Padding may always be present, and it can be any length that fits into the
+Ethernet frame after the headers and the payload.
+Only requirement for padding is that it has to be all zero bytes.
+.Pp
+NOTE: Frame check sequence is not present in the table above, as at least
+on Linux if you read and write raw Ethernet frames using
+.Xr packet 7
+it gets stripped off and added by the lower level drivers.
+.Ss Packet type
+.Bl -tag -width Ds
+.It Speak version (0x00)
+.TS
+allbox;
+lb	lb	lb
+l	l	l.
+Field	Length (B)	Contents
+Version	1	EtherMess protocol version
+.TE
+.Pp
+Tells the recipient to speak the given version of the protocol.
+Should be generated whenever you receive an EtherMess packet with a version
+you don't speak.
+.It Status request (0x01)
+Requests the recipient to tell its status and nick.
+Upon receiving this packet, a status packet should be sent to the sender.
+.It Status (0x02)
+.TS
+allbox;
+lb	lb	lb
+l	l	l.
+Field	Length (B)	Contents
+Status	1	(defined below)
+Nick length	1	Length of the nick field in bytes
+Nick	0 - 255	Nick encoded as utf-8
+.TE
+.Pp
+Informs the recipient about the current status and the nick of the sender.
+.Pp
+Allowed values for the status field are:
+.Bl -tag -width Ds
+.It 0x00
+Available
+.It 0x01
+Unavailable
+.It 0x02
+Offline
+.El
+.Pp
+The nick field must contain valid utf-8.
+That is, it may not contain overlong encodings, codepoints over U+10FFFF,
+or surrogate pairs.
+.Pp
+Additionally, the nick may not contain any non-characters (U+xxFFFE,
+U+xxFFFF, U+FDD0 - U+FDED), C0 control characters (U+00 - U+1F), C1 control
+characters (U+80 - U+9F), or the codepoints U+2028 LINE SEPARATOR and
+U+2029 PARAGRAPH SEPARATOR.
+.Pp
+If the message has a status that is not recognized or the nick is not valid
+utf-8 or contains disallowed codepopoints, the message must be ignored.
+.It Msgid request (0x03)
+<>
+.It Msgid (0x04)
+<>
+.It Message (0x05)
+<>
+.It ACK (0x06)
+<>
+.El
+.Sh SEE ALSO
+.Xr ethermess 1