PoWebSocket: Parcel Delivery over WebSocket

  • Id: RS-016.
  • Status: Working draft.
  • Type: Implementation.
  • Proof of concept: https://github.com/relaynet/poc/tree/master/PoWebSocket

Abstract

This document describes PoWebSocket, a binding for internal Parcel Delivery Connections (PDC) on top of the WebSocket (RFC-6455) protocol.

Table of contents

  1. Introduction
  2. Handshake
  3. Operations
    1. Parcel Collection Request
    2. Parcel Delivery
    3. Endpoint Certificate Request
    4. Parcel Delivery Deauthorization
  4. Message Serialization
  5. WebSocket Considerations
  6. TLS Considerations
  7. Relevant Specifications
  8. Open Questions

Introduction

PoWebSocket allows an endpoint and its gateway to maintain a long-lived PDC over WebSockets. This binding is functionally equivalent to PoSocket, but is based on a standard Application Layer protocol to make integration easier.

As an internal PDC, in addition to allowing both nodes to send parcels in either direction, the endpoint can use this connection to request a certificate from its gateway in order to issue Parcel Delivery Authorizations (PDAs) or revoke them with Parcel Delivery Deauthorizations (PDD).

The messages sent over WebSockets are serialized with Protocol Buffers.

Handshake

Per Relaynet Core, the handshake involves three steps:

  1. The gateway challenges the endpoint to sign a nonce with its key(s).
  2. The endpoint signs the nonce with each of its keys and sends the signatures to the gateway.
  3. The gateway verifies the signatures and confirms the end of the handshake.

These messages are serialized using the following Protocol Buffers definition:

syntax = "proto3";

package relaynet.powebsocket.handshake;

message Challenge {
    // Sent by the gateway at the start of the connection

    string gateway_nonce = 1;
}

message Response {
    // Sent by the endpoint in response to Challenge

    // The gateway's nonce signed by each endpoint certificate.
    repeated bytes gateway_nonce_signatures = 1;
}

message Complete {
    // Sent by the gateway after successfully validating Response

    bool success = 1;
}

Operations

The connection can be used to exchange parcels and perform other actions as soon as the handshake is completed successfully.

Parcel Collection Request

The endpoint will send a parcel collection request message when it is ready to collect parcels from the gateway. Per Relaynet Core, the gateway would not attempt to deliver parcels until then.

Parcel Delivery

To deliver a parcel, the sending node MUST encapsulate it in a parcel delivery message. The receiving node MUST respond with a parcel delivery acknowledgement once the parcel has been safely stored/forwarded.

When the gateway does not have any further parcels to deliver, it MUST send a parcel delivery complete message. This may be useful in cases where the application behind the endpoint is short-lived and is meant to exit as soon as it has collected all the parcel from the gateway.

Endpoint Certificate Request

To request a certificate from the gateway, the endpoint MUST send an endpoint certificate request message with the endpoint’s public key attached to it. This is analogous to a Certificate Signing Request.

Once the certificate has been generated, the server MUST attach it to an endpoint certificate response message.

Parcel Delivery Deauthorization

To revoke all or some PDAs, the endpoint MUST send a parcel delivery deauthorization message with the data required per Relaynet PKI.

Message Serialization

The following Protocol Buffers file defines the messages in this connection:

syntax = "proto3";

package relaynet.powebsocket;

import "google/protobuf/timestamp.proto";

message ParcelDelivery {
    string id = 1;
    bytes parcel = 2;
}

message ParcelDeliveryAck {
    string id = 1;
}

message ParcelCollectionRequest {}

message ParcelDeliveryComplete {}

message EndpointCertificateRequest {
    bytes public_key = 1;
}

message EndpointCertificateResponse {
    bytes certificate = 1;
}

message ParcelDeliveryDeauthorization {
    string endpoint_address = 1;
    repeated string pda_serial_numbers = 2;
    google.protobuf.Timestamp expiry = 3;
}

And since Protocol Buffers messages do not contain any information to identify their message type, each message MUST be prefixed with a corresponding 8-bit integer to specify its type:

  • 0x0: ParcelDelivery.
  • 0x1: ParcelDeliveryAck.
  • 0x2: ParcelCollectionRequest.
  • 0x3: ParcelDeliveryComplete.
  • 0x4: EndpointCertificateRequest.
  • 0x5: EndpointCertificateResponse.
  • 0x6: ParcelDeliveryDeauthorization.

WebSocket Considerations

Clients and servers implementing this specification MUST support HTTP version 1.1.

Both the client and the server SHOULD send each other ping messages and they MUST respond with a pong message for every ping they receive.

TLS Considerations

Server Name Identification MUST be supported by clients and MAY be used by servers.

Relevant Specifications

Relaynet Core (RS-000) defines the requirements for message transport bindings in general and parcel delivery bindings specifically, all of which apply to PoWebSocket. Relaynet PKI (RS-002) is also particularly relevant to this specification.

Open Questions