Add protocol description

1 files changed, 46 insertions, 0 deletions

@@ -0,0 +1,46 @@
+THE POSTCARD PROTOCOL
+
+The postcard protocol is a small client-server protocol built on udp for short
+one-off messages.  Messages must be contained in one packet (512 bytes); with
+metadata taking up around 100 bytes that means messages can be up to around 400
+bytes in length, which is roughly postcard-sized.
+
+A postcard message looks like this (sans leading indentation):
+
+    <recipient><newline>
+    <ed25519 public key of sender><newline>
+    <message>
+
+A postcard server ("Post office") is a persistent process somewhere online that exists to
+receive postcards and deliver them to the proper user.  It could be fun to have
+a block of ports, each of which serves as one user's "P.O. box" on that server.
+If an entire block isn't available, one port could be used and delivery made
+using the first line of the postcard.
+
+Spam mitigation has two layers:
+
+1. The sender must know the recipient's server (and possibly port number) and
+   user name.  Post offices must keep a list of user names and their associated
+   port numbers, and if the recipient's name and port fail to align, or if the
+   office doesn't have a user, the message is rejected.
+
+2. Sender identity is verified using ED25519 public key cryptography (chosen
+   because of its short length---a mere 32 bytes).  Post offices should keep
+   lists of friends and fuckers, letting the first deliver to their users and
+   telling the second to shove it.  When receiving a message from an unknown
+   recipient, the post office should hold the message for a given amount of time
+   and allow a moderator ("postmaster") to decide whether the sender is a
+   friend or fucker.
+
+UDP was chosen as a protocol precisely for its lossy and unpredictable nature:
+postcards themselves can get lost in the mail or damaged by rain or machinery,
+after all.  However, if a postmaster wants to provide a greater level of
+service for senders to their office, they may respond with one of the following
+codes upon receipt of message:
+
+(1) HM --- message received but waiting for moderation
+(2) OK --- message received and delivered
+(3) FU --- fuck off, fucker!
+
+Of course, a postmaster can decide to not send HM or simply not to reply to
+fuckers.  They can just pretend the message was lost in the mail.