aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README67
1 files changed, 59 insertions, 8 deletions
diff --git a/README b/README
index d5f624c..826973a 100644
--- a/README
+++ b/README
@@ -8,6 +8,7 @@ Features:
No send-time timestamps
Increasing message size limit may cause problems
Support for routing keys with wildcards.
+ Support for secret communication.
Non-features:
No IP or cluster support, should be implemented as a separate service.
@@ -18,25 +19,29 @@ Non-features:
No support for shared queues, should be implemented as a separate service.
No file descriptor passing support, not network-compatible, should be
implemented as a separate service or at application level.
- No support for server-verified credentials, not network-compatible
+ No support for server-verified credentials, can be implemented at
+ application level by using '!.cred.' routing keys.
Routing keys:
Routing keys are used to filter received messages. A routing key
- may contain any byte, whoever there are two bytes with special
- meaning: '*' and '.'. '*' should not be used in routin keys, but
- only in routing key patterns, it matches until the next '.' or
+ may contain any byte, whoever there are three bytes with special
+ meaning: '*', '.', and '!'. '*' should not be used in routing keys,
+ but only in routing key patterns, it matches until the next '.' or
end if there are not more '.'s. Additionally if a routing key
pattern ends with '.' that '.' will match to a '.' and any
subsequent byte. For example 'a.*.c.' will match 'a.b.c.' and
- 'a.b.c.d.e' but not 'a.b.c' or 'a.c.d'. And empty routiung key
- pattern shall match everything. Routing keys starting with '!'
- are reserved.
+ 'a.b.c.d.e' but not 'a.b.c' or 'a.c.d'. And empty routing key
+ pattern shall match everything. The token '!' is reserved, a client
+ should never use '!' for any other purpose than specified in the
+ protocol, unless it has an other byte than a '.' next to it. The
+ server may choose to disconnect a client using '!' in an invalid
+ way or simply ignore such messages.
Protocol:
Communication is done over unix domain, sequenced-packet sockets.
Each packet is interpreted as a complete message. A packet cannot
contain multiple message, and a message cannot be split over
- multiple packets. There are 3 types of messages:
+ multiple packets. There are 4 types of messages:
Subscribe:
Send a routing key pattern to the server for the client.
@@ -77,3 +82,49 @@ Protocol:
where \1 is the routing key for the message and \2
is the message payload.
+
+ Control message:
+ Send a control message to the server. The server may
+ also send control message to clients. The server will
+ never forward control message it receives, and no
+ subscriptions are required to receive the messages.
+
+ Messages of this type shall match the regular expression
+
+ ^CMSG \([^\x00]*\)\(\x00\(.*\)\)$
+
+ where \1 is the routing key for the message and \3
+ is the message payload. \2 may be om be omitted if
+ sent by the client.
+
+Secret messages:
+ Routing keys starting with '!.cred.' can only be subscribed to
+ by clients with matching credentials. These routing keys look
+ match this regular expression
+
+ ^!\.cred\.\([0-9]*\)\.\([0-9]*\)\.\([0-9]*\)\.\(.*\)$
+
+ where \1 is the group ID, \2 is the user ID, \3 is the process
+ ID, and \4 the rest of routing key which may also use this
+ pattern a process it communicates. Client can only subscribe
+ to the routing key \1, \2, and \3 match it's credentials.
+ If \1, \2, or \3 are empty, they will match the clients it's
+ credentials when subscribing. However, the server will not
+ accept '*' for \1, \2, or \3, or truncated routing key.s
+
+ However, due to network support, these routing keys may need
+ to be prefixed with the credentials for the servers the message
+ goes through. This prefix can be retrieved by simply sending an
+ empty control message (CMSG) with the routing key '!.cred.prefix'
+ and the server will reply with a control message containing prefix
+ using this routing key. Note, prefix is probably the empty string,
+ as the master server do not need to add its credentials to be
+ prefixed. Note, the server will never send control messages, so
+ received control message are guaranteed to come from the server.
+
+ Example of how two client can prove their identities to each oter:
+
+ A: Send A's credentials to B.
+ B: Send B's credentials with routing key private to A.
+ A: Send a random message with routing key private to B.
+ B: Send back the message with routing key private to A.