Arivi Protocol Specification

Arivi Protocol Specification

Arivi contains the following protocol layers:

Arivi Layer 1 – Offers a secure transport layer which handles key exchange (ephemeral keys using IES) and encryption/message authentication. This layer uses length prefixed frames over a TCP stream. The first 3 bytes specifies the payload length.

Arivi Layer 2 – Handles service capability negotiation, service multiplexing & chunking/re-assembly of large payloads. The Arivi layer-2 frames containing header meta data and binary payload are encoded using CBOR binary format.

Arivi Layer 1 Handshake

This type of frame contains handshake of the connection.

  1. Handshake Initiation: It follows an integrated handshake pattern where key exchange and version/ encryption negotiation happens simultaneously. Handshake-Init contains the following fields which are together encrypted using the remote party’s public key. as part of negotiation,
    • supported protocol version list
    • supported encryption mode list
    • unique connection id

    and for key-exchange,

    • public key
    • ephemeral public

    The recipient computes a shared secret key for subsequent encrypted communication using the below:

    • freshly generated ephemeral key pair
    • received remote-ephemeral-public-key
  2. Handshake Acknowledgement:
    The Ack frame contains the following fields which will be encrypted using the remote party’s (initiator’s) public key.

    • ephemeral public
    • negotiated protocol version
    • negotiated encryption mode

Arivi Layer 1 Regular Frame

  • The layer 1 frame is length prefixed, i.e. the first 3 bytes are reserved to specify the length in bytes of the ensuing payload. The Arivi Layer 2 frame (described below) will essentially be the payload which will be encrypted in Layer 1 using the negotiated symmetric encryption algorithm i.e. AES 256 in CTR mode, AEAD schemes such as ChaCha20Poly1305 , etc.

Arivi Layer 2 Fields

The following fields will be included in the Arivi Layer 2 CBOR encoded frames.

Version:

Version of the protocol Spec this will be negotiated at the initial messages, Client and server will negotiated this by taking latest of common version, For Ex. Client has v1,v2 and Server has v1,v2,v3 then the communication version will be v2 .

Opcode:

  • Error – 0x00 Indicates an error processing a request. The Error descriptor of the message will contain an error code followed by a error message. Then, depending on the exception, more content may follow. The error codes are defined in along with their additional content if any
  • Data – 0x01 This opcode indicates this frame is regular data carrying frame.
  • Options 0x02 Asks the server to return what service options are supported. The body of an OPTIONS message should be empty and the server will respond with a SUPPORTED message such as services Kademlia,Chord,Block
  • Supported 0x03 Indicates the descriptor field contains the list of supported services.

NodeType

  • This indicates it is Initiator or Recipient.

TransportType:

  • Indicates TCP or UDP.

Descriptor

  • This is optional field in the frame. If opcode value is ERROR, then this field serves as an Error descriptor.
  • Else if the opcode value is SUPPORTED then this field will contain a list of supported Services. This field is not used for other opcodes.

Message id/Sequence No:

  • Integer field value that will be incremented for each message. All fragments of a given message will have the same message id. Starts from 0 for given connection.

Fragment number (Optional)

  • If this field is present then it indicates the fragment no of chunked message.

Payload marker

  • Indicates the service being multiplexed.

Payload

  • This is the actual payload of the frame which will be limited to max size of 500KB.