Skip to content

PROTOCOL.md

Latest commit

 

History

History
64 lines (44 loc) · 3.4 KB

PROTOCOL.md

File metadata and controls

64 lines (44 loc) · 3.4 KB
Raw

Protocol

Format

Messages are encoded using Google Protocol Buffers version 3 (proto3).

Peer Connections

Establishment

Peer connection requests consist of three messages: Syn, Ack and SynAck. These messages are named similarly to the TCP handshake, but they are not related to a TCP/IP network connection establishment. Syn is sent by a sending peer making an outbound connection, and if the connection is accepted, the receiving peer replies with an Ack. Finally, the sending peer replies to Ack with a SynAck.

Syn

message Syn {
    uint32 prot_ver = 1;
    bytes session_pub_key = 2;
    bytes id_pub_key = 3;
}

  1. Syn messages include a protocol version. Any breaking change to the core Luxelot message requires an increment of the protocol version.

  2. A CRYSTALS-Kyber public/private keypair is generated by the sending node FOR THE PURPOSES OF THIS CONNECTION ONLY, and the Kyber public key is shared. This will form the basis of a shared session key establishment between the sender and the receiver after the Ack is received. This is a session key that is only used for the duration of this session and is not persisted for subsequent connections with this or any other nodes.

  3. A CRYSTALS-Dilithium public/private keypair is generated by the node to identify it. The public key is shared here. Future messages originated from this sending node will be signed using the private portion of this key pair, and this allows the receiving node on this connection request to validate message integrity.

Ack

message Ack {
    uint32 prot_ver = 1;
    bytes cipher_text = 2;
    bytes id_pub_key = 3;
    fixed32 addr1 = 4;
    fixed32 addr2 = 5;
    fixed32 addr3 = 6;
    fixed32 addr4 = 7;
}

Receiving nodes respond with the Ack message if they wish to accept the connection.

  1. Similar to Syn, the receiving node replies with its protocol version. Receiving nodes MAY choose to accept connections from sending nodes with any lower protocol version, provided they offer backwards compatibility for the core message set. Receiving nodes MUST NOT accept connections from nodes with a higher protocol version number, as they cannot know whether they will be forwards compatible.

  2. The cipher text is generated using the Kyber public key received from the sending node in the Syn message and the private Kyber key generated by this node. This is the Kyber Key Encapsulation Mechanism (KEM) and will be decoded by the receiving node and will complete the shared session key establishment.

  3. The receiving node replies with its own public Dilithium key that is consistently used in all its identification and message signing on the network. Similar to the use of this field in Syn, this allows the sending node to validate future messages from this receiving node that it may see originated from it.

  4. The receiving node also provides the IP address of the sender, as it perceives it. If the sender is behind network address translation (NAT), then this will help the ndoe know its publicly perceivable IP address, at least as attested to by this specific receiver.

SynAck

message SynAck {
    fixed32 addr1 = 1;
    fixed32 addr2 = 2;
    fixed32 addr3 = 3;
    fixed32 addr4 = 4;
}
  1. As the first fully encrypted message, the sender replies to the receiver's Ack with a SynAck. In this message, the sending node provides the IP address of the receiver, as it perceives it.