Snarl Network Protocol

View the Project on GitHub

SNP 3.1

  1. Introduction
  2. Overview
  3. Message Structure
    i. Requests
    ii. Responses
  4. Commands
    i. Registering
    ii. Notifications
    iii. Forwarding
    iv. Subscriptions
  5. Security
    i. Authentication
    ii. Encryption


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:


Communication Cycle

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:

  1. Client opens a connection to the server
  2. Client then issues a request
  3. Server takes action and issues an appropriate response
  4. Client either closes the connection or repeats step 2

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.

Info 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.

Other Metrics

Default Port

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.

Text Encoding

Content values should be encoded as UTF-8.

Message Structure

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.

Request Structure

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...

Example Request

title: Testing...
text: Hello, world!
icon: stock:system-info

Response Structure


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.

Example Response



Less success:

error-number: 216
error-name: UserIsAway
reason: The user is currently away.  The notification may have been displayed, ignored, or logged as missed



… 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!


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.

Info 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.