Snarl Network Protocol
SNP 3.1 adds a number of improvements to SNP 3.0 while maintaining several of the features the earlier version of the protocol introduced. Among the changes introduced in SNP 3.1 are:
Standardised processing: every SNP 3.1 request must be accompanied by a resulting SNP 3.1 response. Furthermore, spurious responses (e.g. forwarded notifications and callbacks) should be sent to a different port that has been created specifically to receive these out-of-cycle messages;
Structured messages: SNP 3.1 defines a number of standard request messages which may be sent by a client;
Clearer message format: SNP 3.1 requests and responses now follow the same template approach;
Granular security controls: servers listening for incoming SNP 3.1 messages should provide the user with the ability to block forwarded notifications, and to require authorisation for such notifications;
Flexibility: callbacks can now be directed to a separate TCP port created specifically for receiving out-of-cycle messages, or POSTed to a URL;
More descriptive errors: in addition to returning the code and name of the error that occurred, SNP 3.1 also defines a further parameter that allows the server to return more context around why the error occurred.
A SNP 3.1 conversation is held between a client and a server, with the client initiating the request and the server responding to the request appropriately. The process is as follows:
The client and server may be on the same physical machine, or they may be on different machines. If a client wishes to send a request and then close, it must wait until it has received the response from the server, even if it does not plan to do anything with it.
Callbacks may be received on the port used by the client to issue the requests, however this is not recommended as it requires more complex logic within the client to distinguish between an expected response and an out-of-cycle callback message. The recommendation is for the client application to create a separate listening socket and pass the port number of that socket when creating notifications. This then allows the client to run a tight send/receive message loop.
SNP 3.1 does not define a standard port. The end user (or system administrator) is free create SNP 3.1 servers on any valid TCP port.
Content values should be encoded as UTF-8.
A SNP 3.1 request comprises of a header, zero or more lines of content, and a terminator. Like SNP 3.0, a SNP 3.1 message spans multiple lines and can be a variable number of lines. The terminator is always END
. Each line, including the terminator, must end with a CRLF
.
SNP 3.1 defines two types of message: Request and Response. Both are very similar in format, however requests must include at least one line of content; responses may not include content. Also, requests must be responded to; responses are not responded to.
The header describes the nature of the request:
{id/version} {action} [{authentication} [{encryption}]]
Item | Description |
---|---|
id/version |
Indicates the version of the protocol to be used. Always SNP/3.1 . |
action |
Indicates the request type. There are currently five types of request: FORWARD , NOTIFY , REGISTER , SUBSCRIBE , UNSUBSCRIBE . |
authentication |
The algorithm, key hash and salt used if authentication is required. |
encryption |
The encryption algorithm and initialisation value used to secure the message content if it’s encrypted. |
Each line of content is formatted in a similar way to MIME and HTTP headers, as a key/value pair separated with a colon and a space character:
title: Hello, world!
text: This is some text...
SNP/3.1 NOTIFY
title: Testing...
text: Hello, world!
icon: stock:system-info
END
The response header is as follows:
{id/version} {response_type} [{authentication} [{encryption}]]
Item | Description |
---|---|
id/version |
Returns the highest version of the protocol supported. Always SNP/3.1 . |
response_type |
Indicates the response type. There are currently four types of response: CALLBACK , FAILED , GOODBYE and SUCCESS . |
authentication |
The algorithm, key hash and salt used if authentication is required. |
encryption |
The encryption algorithm and initialisation value used to secure the message content if it’s encrypted. |
Typically no content is returned. However, if a request returns an error, the following will be included in the content:
Item | Description |
---|---|
error-number |
The Snarl status code indicating the error. |
error-name |
The name of the error code. |
reason |
If available, a more human-readable explaination of what went wrong. |
Success:
SNP/3.1 SUCCESS
END
Less success:
SNP/3.1 FAILED
error-number: 216
error-name: UserIsAway
reason: The user is currently away. The notification may have been displayed, ignored, or logged as missed
END
… Section to be completed …
… Section to be completed …
… Section to be completed …
… Section to be completed …
To authenticate a message, the password must be translated into a key hash using a supported hash algorithm and and salt. This is included in the header, as follows:
SNP/3.1 {action} {hash_algorithm}:{key_hash}.{salt}
See the Developer Guide for details on supported hash_algorithm
types and how to generate the key_hash
and salt
.
SNP/3.1 FORWARD MD5:123456789ABCDEF.CA53559F21004566
source: SecureBot
text:Hello, world!
END
Encrypting a message requires both authentication and a valid encryption algorithm and initialisation value. The header therefore looks thus:
SNP/3.1 {action} {hash_algorithm}:{key_hash}.{salt} {encryption_algorithm}:{iv}
The encrypted message still has a header and terminating line, however the content is encrypted into a byte array which is then encoded as a hexadecimal string.
Hexadecimal-encoding the message content will double the size of the message packet compared to the same packet unencrypted. As notifications are by nature intended to be brief, this should not be a significant issue, however if a client typically transfers a large amount of metadata along with the notification, consideration should be given to using a different mechanism to transfer the data - especially if network bandwidth is a concern.