Snarl Network Protocol (SNP)

Version Information

Revision 3, 11-Jan-2015

Changes

Revision 3

  • Added features introduced in Snarl R4.0;
  • Clarified position around forwarding.

Revision 2

  • Revised Subscribing section;
  • Sending of "subscriber-name" as part of [subscribe] command is now considered required (although not mandatory in SNP 3.0).

Introduction

The Snarl Network Protocol (SNP) provides simple access to both local and remote instances of Snarl.  It is TCP-based and thus the sending computer need not be running Snarl (or Windows) - so long as it can connect via TCP/IP to a remote computer running Snarl, it will be able to send notifications.

Note: this document refers to the current version of SNP, for previous versions of SNP, see the legacy SNP page.

SNP 3.0 introduces the following benefits over earlier versions of the protocol:
  • Simplified multi-action requests;
  • Authorisation and encryption;
  • Subscribing and forwarding.

Communication Overview

Communication takes place using TCP via either port 9887 or port 5233.  Starting with Snarl R4.0, communication can take place over any valid TCP port, although applications may still expect communication to work across a specific port.

Typically it is down to the client to manage the connection and terminate it when no further communication is required, however in some cases Snarl may terminate the connection (due to malformed messages, security concerns, etc.).

Note: To use TCP port 5233, the destination computer must be running Snarl R2.5 or later.

The communication process is as follows:
  1. Client creates a socket
  2. Client connects to Snarl running on the remote computer
  3. Client sends a request to Snarl
  4. Client receives reply from Snarl
  5. Steps 3 and 4 repeat continually until...
  6. Client ends connection
Callback events and notifications forwarded as the result of a subscription will also be received by the client.

The client may choose to create a new socket for each request, or re-use an existing socket.  If the client is expecting to handle callbacks then it should ensure the socket remains open at least until the callback is received.  If a client has subscribed for notifications from a remote computer, it must leave the socket open in order to receive notifications sent by the remote computer.

Message Structure

An SNP 3.0 message consists of:
  • A header;
  • One or more lines of content;
  • A terminator.
Additionally, the following:
  • Each line must each end with a CR/LF pair;
  • The header and content lines vary depending on whether the message type;
  • The terminator is always "END" on a single line (followed by a CR/LF pair).

Message Types

Two types of message are currently defined: requests and responses.

Requests

An SNP 3.0 request is sent from a client (which may be Snarl but more likely will part of an application) to computer running Snarl.  An SNP 3.0 request consists of:
  • A header;
  • One or more actions;
  • A terminator.
The header, all request lines, and the terminator must all end with a CR/LF pair.

Request Header

The SNP 3.0 header is as follows:

{id/version} [request_type] [hash_type:key_hash.salt [cypher_type:key]] CRLF

id/version is always required and must be "SNP/3.0"; request_type, hash_type and cypher_type are optional, however if cypher_type is specified then hash_type must also be specified.

See Security for details of supported hashing and encryption algorithms.

Request Types

The following request types are defined:

Standard request

request_type is blank.  A standard request typically consists of a registration action, one or more event additions and one or more notification actions.

Forward

request_type is "FORWARD".  A forwarded notification is one sent from a computer to another computer on the network.  Forwarding does not typically involve application registration, instead the forwarding computer effectively acts as a proxy for the notification it has sent.

    Request Content

    Each action must be on a separate line and there must be at least one action contained within the message (otherwise you'll receive a SNARL_ERROR_BAD_PACKET response).

    Actions follow the standard format, however there are some specific points to note:
    • Actions cannot contain CR or LF characters - use '\n' to include line feeds within actions (for example, within notification text);
    • '&' and '=' characters are reserved; use '&&' and '==' respectively or URL-encode any content which may include these characters;
    • Similarly, Base64 encoded icon data must not contain CR, LF, or '=' characters (which typically appear in most Base64 encoding algorithms).  To avoid this, replace CRLF pairs and equals signs with other suitable symbols before including in the request.  You should use Phat64 encoding (helper functions are included) to achieve this easily.

    Example Request

    With no hashing:

    SNP/3.0 CRLF
    register?app-sig=foo/bar&title=Foo CRLF
    notify?app-sig=foo/bar&title=Hello&text=World CRLF
    END CRLF

    With SHA-256 hashing:

    SNP/3.0 SHA256:4509405940583953094503945 CRLF
    register?app-sig=foo/bar&title=Foo CRLF
    notify?app-sig=foo/bar&title=Hello&text=World CRLF
    END CRLF

    Forward:

    SNP/3.0 FORWARD CRLF
    notify?app-sig=foo/bar&title=Hello&text=World CRLF
    END CRLF

    Responses

    An SNP 3.0 response is received by a client from Snarl.  An SNP 3.0 response consists of:
    • A header;
    • Zero or more lines of content;
    • A terminator.
    The header, all content lines, and the terminator all end with a CR/LF pair.  Unlike an SNP 3.0 request, an SNP 3.0 response follows a MIME style format which each line of content a key/value pair separated with a colon and a space character.  There are three types of SNP 3.0 response: the first two (success and failure) are typically received immediately after a request is sent; the third type (notification response) can be received at any time.

    Response Header

    The SNP 3.0 response header is as follows:

    {id/version} {OK|FAILED|CALLBACK} [hash_type [cypher_type]] CRLF

    At present hash_type and cypher_type are not provided.

    Success Response

    SNP/3.0 OK CRLF
    x-timestamp: 29/06/2011 12:04:59 CRLF
    x-daemon: Snarl 2.4 CRLF
    x-host: cornerstone CRLF
    END CRLF

    Failure Response

    A failure response provides the same content as a success response.  In some cases, a "hint" line will indicate more specific information about the error that occurred.

    SNP/3.0 FAILED CRLF
    error-code: 211 CRLF
    error-name: AuthenticationFailure CRLF
    error-hint: Digest Mismatch CRLF
    x-timestamp: 29/06/2011 12:24:59 CRLF
    x-daemon: Snarl 2.4 CRLF
    x-host: conerstone CRLF
    END CRLF

    Status codes are defined here.

    Notification Response

    A notification response provides the feedback to the application concerning a notification it has generated.

    SNP/3.0 CALLBACK CRLF
    event-code: 303 CRLF
    event-name: TimedOut CRLF
    x-timestamp: 29/06/2011 12:24:59 CRLF
    x-daemon: Snarl 2.4 CRLF
    x-host: conerstone CRLF
    END CRLF

    Points to Note

    • An SNP 3.0 may only consist of the header line and terminator line.  This would be a very unusual occurrence but it is still a valid SNP 3.0 response and should be handled as such.
    A.

    Security

    Authorisation

    Authorisation ensures only applications that share a common secret (in this case, a password) can communicate with Snarl.  The password is entered on the remote computer running Snarl and is used in the construction of the key and key hash on the client, consequently it is never transmitted in clear text between the client and remote computer.

    Currently, three forms of hashing are supported:
    • MD5
    • SHA-1
    • SHA-256
    Due to deficiencies identified in both MD5 and SHA-1, it is recommended that SHA-256 should always be used when communication may occur over a WAN or across the Internet in an unsecured channel.

    The authorisation type used is determined by the sender and is included in the SNP 3.0 header, along with the key hash and salt value used.  A new salt value should be used for each request.

    The key hash is computed as follows:
    • A salt value is created and converted to ASCII hex (e.g. "0036CA21C91F")
    • The salt value is appended to the password
    • The hash of the combined password+salt string is calculated and included in the SNP 3.0 header

    Example

    Using a password of "abcdef" and random salt of "1A2B3C4D5E6F" and MD5 and the hashing algorithm:
    • Combined password and salt: "abcdef1A2B3C4D5E6F"
    • MD5 hash: "b7c903901cab976ee5db15792eb15a03"
    Resulting SNP 3.0 header:

    SNP/3.0 MD5:b7c903901cab976ee5db15792eb15a03.1A2B3C4D5E6F

    Encryption

    TBC

    Digital Signatures

    TBC

    Subscribing and Forwarding

    Subscribing and forwarding achieve a similar end result but are subtly different.

    As the name implies, a subscription is an open-ended connection initiated by a client to a known remote computer, both running Snarl.  Some examples of subscriptions:
    • a central office server which propagates company-wide notifications;
    • part of a help-desk system which notifies referral groups of ticket changes;
    • a centralised source control server which notifies interested parties when a commit had occured.
    To summarise: a subscription takes place between two instances of Snarl, is initiated by the client computer and remains in place until the client unsubscribes.

    Conversely, forwarding is effectively a wrapper for an SNP 3.0 register/notify action pair.  Forwarding is still initiated by a client, however it's the client that is wishing to '''send''' notifications to an instance of Snarl, not receive them.  The instance of Snarl may be running on the same computer, but more often than not it will be running on a remote computer.  The client may use Snarl to send the register/notify message, although it's more likely it will be an application which creates the message itself.  Some examples of forwarding:
    • a printer driver installed on a computer that sends events (e.g. paper jam, toner low) to a central management server;
    • a user who wants to send simple ad-hoc IM-style messages to one or more other users;
    • an application that monitors and reports on activity on a computer to a central server.

    Subscribing

    To subscribe to notifications from a remote source, issue a [subscribe] command as follows:

    SNP/3.0
    subscribe?subscriber-name=<friendly name>
    END

    The subscriber-name parameter is optional but its use is highly recommended as it gives the remote computer (that is, the one you're subscribing to) a better indication of who you are. Future revisions of the SNP protocol may require this parameter to be specified.If the subscription request completes successfully, you'll receive a standard SNP 3.0 success response.

    Depending on the remote source you're subscribing to, you may immediately start receiving notifications (e.g. from a store of buffered messages, a welcome message, etc.) - the implementation depending wholly on the intention of the remote source.

    All notifications will be received to the TCP socket you issued the [subscribe] command from; closing the socket ceases the connection with the remote source.

    Forwarding

    TBC

    Examples

    TBC
    Comments