WebSNP v1 Reference

1. Introduction
2. Overview
3. Messages
   i. Requests
   ii. Responses
   iii. Signals
4. Forwarding
5. Subscriptions
6. Security
   i. Authorisation
   ii. Encryption

Introduction

SNP/HTTP v1 is a revised implementation of v0 which returns a JSON-formatted response, but uses the same request format as v0.  This should make migration from v0 to v1 very straightforward for most applications: only those applications which process the response will need some modification.

Overview

Communication Cycle

A SNP/HTTP 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 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, on different machines, or even split across the Internet. 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.

Other Metrics

Default Port

Awaiting allocation - port 8084 requested.

Text Encoding

Content values should be encoded as UTF-8.

Messages

A SNP/HTTP v1 message is the same as a standard HTTP GET request.

Three message types are defined:

• Request: issued from a client to a server asking the server to do something;
• Response: issued from a server to a client in reply to a request. The response will indicate whether the previous request succeeded or not;

Request Format

The request format of SNP/HTTP v1 is identical to that of v0. To modify your application to use SNP/HTTP V1, rather than using an endpoint of /, use the endpoint /v1/.  For example:

v0 request:

/notify?title=Hello%20World%21&text=This%20is%20a%20test

Equivalent V1 request:

/v1/notify?title=Hello%20World%21&text=This%20is%20a%20test

Response Format

SNP/HTTP v1 returns a response formatted as JSON.  An example response looks like this:

{
  "Meta": {
    "Success": false,
    "Code": 102,
    "Text": "UnknownCommand",
    "Message": "",
    "Host": "cs30",
    "Server": "Snarl 5.1.0"
  },
  "Content": null
}

Every response contains two objects: Meta and Content. Meta will always be provided and indicates whether the request succeeded or not; Content will only be provided if the request succeeded, otherwise it will be null.

Meta Object

The Meta object contains information about the response, specifically whether it was successful or not.

Property	Type	Value
Success	bool	true if the request was successful; false otherwise
Code	int	The status code in number form
Text	string	The status code in text form
Message	string	Further information relevant to the response
Host	string	The hostname the server is running on
Server	string	The name and version of the server

Content Object

if the request was successful, the Content object will contain a single Value integer field which will contain a value relevant to the request. If the request was not successful, Content will be null:

{
  "Meta": {
    "Success": true,
    "Code": 252,
    "Text": "Created",
    "Message": "Notification created",
    "Host": "cs30",
    "Server": "Snarl 5.1.0"
  },
  "Content": {
    "Value": 456
  }
}

Security

Security covers two parts: authorisation and encryption. Authorisation ensures the receiving server trusts incoming messages from a particular client by validating that they both share a common secret (in this case, a password); encryption protects the contents of the message from inspection during it's journey from the client to the server.

Messages can include authorisation without including encryption, however the reverse is not true, as encrypted messages rely on the key created during the authorisation process. So, if you want encryption, you’ll need to also use authorisation.

Authorisation

To authorise a message, the password must be translated into a key hash using a supported hash algorithm and salt (see the Developer Guide for details on how to generate these values). This is all then included in the HTTP request Authorisation: header, as follows:

Authorization: SnarlLock {hashAlgorithm}:{keyHash}.{salt}

Item	Description
hashAlgorithm	The hashing algorithm to use. Can be one of MD5, SHA1, SHA256, SHA512. It is recommended that only SHA256 and SHA512 are used in practice.
keyHash	The hash of the generated key in hex-encoded format.
salt	The cryptographically secure salt created as part of the key hash generation, in hex-encoded format.

Example

GET /v1/notify?title=Hello%20World%21&text=This%20is%20a%20test HTTP/1.1
Authorization: SnarlLock SHA256:EB1452C0F7AEF122588A053386658BB8023C484EE136DA79D8E779D9EC90862B.ACAA8464D48BB97D89380F58243F97B1
Host: 192.168.1.16:4444
Connection: Keep-Alive

Note that authorisation is not the same as authentication. Authentication applies to individual application registrations and ensures that one application cannot spoof notifications from another application.

Encryption

Encrypting a message requires both authorisation and a valid encryption algorithm and initialisation value. The HTTP request Authorization: header is modified to include the encryption metadata as follows:

Authorization: SnarlLock {hashAlgorithm}:{keyHash}.{salt}-{encryptionAlgorithm}:{iv}

Item	Description
encryptionAlgorithm	The encryption algorithm to use. Only AESis currently supported.
iv	The encryption initialisation value, in hex-encoded format.

Example

The following is an encrypted SNP/HTTP request:

GET /06F0313F1B2FB7C03A0ECB8F14C71F7CAE4511846302BFABA48170CE15DB16EB8C9AE513B26F1CCACC2FD25D620C0A2DCA7D67EDC5A04FFC4F62DA1F77B7215CD489AA46B09B5217D30CBA297205BEBE HTTP/1.1
Authorization: SnarlLock SHA256:EB1452C0F7AEF122588A053386658BB8023C484EE136DA79D8E779D9EC90862B.ACAA8464D48BB97D89380F58243F97B1-AES:D3531772621C382AA483D43455ABF352
Host: 192.168.1.16:4444
Connection: Keep-Alive

Hex-encoding the message content typically doubles the overall size of a 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 meta data along with the notification, consideration should be given to using a different mechanism to transfer the data - especially if network bandwidth is a concern.