Communication protocols

This page lists the protocols used between the different major components of the system.

Signpost client <--> Personal signpost

The Signpost Client (SC) and the Personal Signpost (PSP) are in a client-server relationship. There are two phases in the communication between an SC and a PSP:

1. Unencrypted call setup establishing a shared secret and a ticket id, an id unique for the session.
2. HTTP requests from the SC to the PSP accessing a resource. These requests are all encrypted using the shared session secret.

Call setup

The call setup is initiated by the SC. It sends a HTTP POST request to the path /tickets on the PSP. This results in a ticket id, not currently in use, being assigned to the conversation. A shared secret is also established.

Request parameters

The body of the POST request should be a JSON object of the following form:

{"client": {"id":"macbook", "signpost":"signpost.probsteide.com", "key_version":"aFAwda"}, "encrypted_client_secret":"aksjdkapUZg5UZj/0kv0OXtp4o/A=="}

The required parameters are:

• client id: The id used for the connecting client by the clients own PSP
• client signpost: The signpost responsible for the client
• client key_version: The version of the clients public-key currently in use. This lets the PSP being connected to, use cached public-keys
• encrypted_client_secret: The client half of what will make up the shared secret for the session. It is encrypted using the PSPs public-key

Response

The PSP responds with a json object containing a status field. The status indicates whether the ticket was created successfully or not. If it failed, and additional message indicated the reason for the failure

Success

{"status":"success", "server_shared_secret":"Zg5UZj/0kv0OXtasdp4o/B==", "ticket_id":"id_of_current_ticket"}

Failure

{"status":"failure", "message":"reason"}

HTTP requests

The PSP exposes a RESTful webservice. It provides the following resources:

• foo
• bar
• to
• be
• filled
• in