Skip to content

pairing-protocol.md

Latest commit

 

History

History
84 lines (60 loc) · 5.57 KB

pairing-protocol.md

File metadata and controls

84 lines (60 loc) · 5.57 KB

Introduction

The BRAID system is used in the context of goods shipping, where three primary actors can be identified:

  • Producer: The entity that manufactures and sells the goods.
  • Carrier: The entity that transports the goods to their destination.
  • Consumer: The entity that receives the goods and needs to verify whether the transportation conditions have affected the goods’ properties.

The protocol described below aims to ensure the highest level of security by guaranteeing that the data and operations relevant to all parties can be trusted.

As it have to be implemented in real use-cases, we identify two main use-case classes:

  • A Scenario: single shipment (e.g. from the producer to the final consumer);
  • B Scenario: bulk shipment (e.g. from the deposit A to the deposit B, from the producer to a distributor, etc.).

This classes are useful to define two protocol variants (A scenario, B scenario), with no impact on information security.

Authentication and Authorization

Each actor type is associated with a specific role in the BRAID authentication and authorization system:

  • Producer: Can pair trackers with the goods being sold.
  • Carrier: May open and close the packaging in certain situations (but not always).
  • Consumer: Can unpair the tracker, thereby concluding the shipment.

To use the BRAID system and its protocol, each user must be registered and assigned one of the roles above. The role also determines which keys of a BRAID tracker shadow can be changed. Every user has a public/private key pair associated with their account; these keys are used to verify who is interacting with the tracker. When any private key is compromised, the owner can upload a new public key.

Tracker Features

The BRAID tracker provides the following features:

  • Controls the opening and closing of a lock.
  • Detects whether the lock is open or closed.
  • Includes a QR code to facilitate the physical operations of pairing, unpairing, opening, and closing the tracker.
  • Stores events of lock openings and closings even when offline, and publishes them once it goes online.
  • Uses sequence numbers in messages payload to make checking for missing data possible.

Terms of the Protocol

Some terms used in this protocol are defined as follows:

  • LOG: An abstraction for the destination of certain messages. Two types of LOGs have been considered: a blockchain, and a traditional server database with signed payloads certified by a trusted CA.
  • ACTION: One of PAIR, OPEN, CLOSE, or UNPAIR, each applicable to a BRAID tracker.
  • TRACKER_ID: Identifier of the tracker.
  • GOOD_ID: Identifier of the good being shipped.
  • PRODUCER_ID: Identifier of the producer in the BRAID authentication system.
  • CARRIER_ID: Identifier of the carrier in the BRAID authentication system.
  • CONSUMER_ID: Identifier of the consumer in the BRAID authentication system.
  • TRACKER_PAIRING_TOPIC: An MQTT topic dedicated to configuring a tracker.

Description of the Protocol

The protocol involves both physical tasks and digital operations, summarized in these steps:

  1. If A scenario, the tracker is attached to the goods. The producer scans the tracker’s QR code to obtain the TRACKER_ID.
  2. The producer fetches the public keys of the actors involved in the shipment, identified by their IDs.
  3. Using the BRAID API, the producer configures the tracker for a specific order by providing the following information:
  • TRACKER_ID
  • GOOD_ID
  • PRODUCER: { ID: PRODUCER_ID, PK: PRODUCER.PK }
  • CARRIER: { ID: CARRIER_ID, PK: CARRIER.PK }
  • CONSUMER: { ID: CONSUMER_ID, PK: CONSUMER.PK }
  • PERMISSIONS: A list, for each ACTION, of the public keys of the actors permitted to perform that action. The PAIR action is excluded because it is being carried out at this time and is verified by the BRAID authentication system, which only allows producer users to pair. For example: { OPEN: [PRODUCER_ID, CARRIER_ID], CLOSE: [PRODUCER_ID, CARRIER_ID], UNPAIR: [PRODUCER_ID, CONSUMER_ID] }
  • SIGNATURE: The signature of the provided payload.
  1. The BRAID server receives the pairing request:
    • Verifies that the request is made by a producer.
    • Verifies that the public keys belong to a producer, carrier, or consumer.
    • Publishes the request payload to the LOG.
    • Sends an MQTT message to the TRACKER_PAIRING_TOPIC of the specified TRACKER_ID, containing all the provided information and the PRODUCER_ID (known because the request is authenticated).
  2. The tracker device receives the pairing request:
    • If the tracker is already paired, it rejects the request.
    • If the tracker is unpaired, it logs the event, reporting producer, carrier and consumer triple, and responds with an accepted message.
    • If the tracker is paired, it starts sending sensor data to the reported MQTT topic.
  3. If B scenario, the tracker is attached to the goods and handed over to the carrier. The carrier delivers the goods. In certain exceptional cases, the carrier may open the package using the BRAID API, which checks whether the carrier has permission to do so and logs the event.
  4. The consumer receives the goods and unpairs the tracker.

In B scenario, the correct match between the tracker and the goods responsibility is on the producers informative system. This variant as no relevance on the security as it happens always before the effective shipment and an error can be easily detected from the receiver.

When this protocol is carried out successfully, any interested party can check the delivery data with a high degree of confidence that it is authentic. The following sequence diagram illustrates the protocol:

image