package octez-shell-libs

  1. Overview
  2. Docs
package octez-shell-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Typed and encrypted connections to peers.

This module defines:

  • primitive functions to implement a session-establishment protocol (set up an authentication/encryption symmetric session key, check proof of work target, authenticate hosts, exchange meta data),
  • a higher-level, authenticated and encrypted, type of connection.

It is parametric in two (abstract data) types. 'msg is the unit of communication. 'meta is a type of message sent in session establishment.

Connections defined in this module wrap a P2p_io_scheduler.connection (which is simply a file descriptor on which R/W are regulated.)

Each connection has an associated internal read (resp. write) queue containing messages (of type 'msg), whose size can be limited by providing corresponding arguments to accept.

Types

type 'meta authenticated_connection

Type of a connection that successfully passed the authentication phase, but has not been accepted yet. Parametrized by the type of expected parameter in the `ack` message.

type ('msg, 'meta) t

Type of an accepted connection, parametrized by the type of messages exchanged between peers.

val equal : ('mst, 'meta) t -> ('msg, 'meta) t -> bool

equal t1 t2 returns true iff the identities of the underlying P2p_io_scheduler.connections are equal.

val pp : Format.formatter -> ('msg, 'meta) t -> unit
val info : ('msg, 'meta) t -> 'meta Tezos_base.TzPervasives.P2p_connection.Info.t
val local_metadata : ('msg, 'meta) t -> 'meta

local_metadata t returns the metadata provided when calling authenticate.

val remote_metadata : ('msg, 'meta) t -> 'meta

remote_metadata t returns the remote metadata, communicated by the remote host when the session was established.

val private_node : ('msg, 'meta) t -> bool

Session-establishment functions

These should be used together to implement the session establishment protocol. Session establishment proceeds in three synchronous, symmetric, steps. The first two steps are implemented by authenticate. The third step is implemented by either accept or nack.

1. Hosts send each other an authentication message. The message contains notably a public key, a nonce, and proof of work stamp computed from the public key. PoW work is checked, and a session key is established (authenticated key exchange). The session key will be used to encrypt/authenticate all subsequent messages over this connection.

2. Hosts send each other a 'meta message.

3. Each host send either an Ack message (accept function) or an Nack message (nack function). If both hosts send an Ack, the connection is established and they can start to read/write 'msg.

Note that P2p_errors.Decipher_error can be raised from all functions receiving messages after step 1, when a message can't be decrypted.

Typically, the calling module will make additional checks after step 2 to decide what to do in step 3. For instance, based on network version or 'meta information.

authenticate canceler pow incoming conn point ?port identity version meta returns a couple (info, auth_conn) tries to set up a session with the host connected via conn.

Can fail with

  • P2p_errors.Not_enough_proof_of_work if PoW target isn't reached
  • P2p_errors.Myself if both hosts are the same peer
  • P2p_errors.Connection_closed if the remote peer closes the connection

nack ac motive alts sends a Nack message with the rejection motive and a list of proposed alternative points to the remote peer, notifying it that its connection is rejected. It then closes the connection.

alts must contain less than 100 points or you will be greylisted

val accept : ?incoming_message_queue_size:int -> ?outgoing_message_queue_size:int -> ?binary_chunks_size:int -> canceler:Lwt_canceler.t -> 'meta authenticated_connection -> 'msg Tezos_base.TzPervasives.Data_encoding.t -> ('msg, 'meta) t Tezos_base.TzPervasives.tzresult Lwt.t

Accepts sends an Ack message to the remote peer and wait for an Ack from the remote peer to complete session set up. This can fail with errors:

  • P2p_errors.Rejected_socket_connection on connection closed
  • P2p_errors.Rejected_by_nack if Nack is received
  • P2p_errors.Invalid_auth thrown if P2p_error.Decipher_error
val check_binary_chunks_size : int -> unit Tezos_base.TzPervasives.tzresult

Check for the ?binary_chunks_size parameter of accept.

IO functions on connections

Output functions

val write : ('msg, 'meta) t -> 'msg -> unit Tezos_base.TzPervasives.tzresult Lwt.t

write conn msg returns when msg has successfully been added to conn's internal write queue or fails with a corresponding error.

val write_now : ('msg, 'meta) t -> 'msg -> bool Tezos_base.TzPervasives.tzresult

write_now conn msg is Ok true if msg has been added to conn's internal write queue, Ok false if msg has been dropped, or fails with a corresponding error otherwise.

type 'msg encoded_message

type of an encoded_message parameterized by the type of message it can be encoded from

val copy_encoded_message : 'msg encoded_message -> 'msg encoded_message

Copies and encoded message in a newly allocated one

val encode : ('msg, 'meta) t -> 'msg -> 'msg encoded_message Tezos_base.TzPervasives.tzresult

Encodes a message to be used with write_encoded_now.

val write_encoded_now : ('msg, 'meta) t -> 'msg encoded_message -> bool Tezos_base.TzPervasives.tzresult

Similar to write_now conn msg but with a preencoded message. msg will be overwritten and should not be used after this invocation. It will fail if called on a closed connection with the `P2p_errors.Connection_closed` error.

val write_sync : ('msg, 'meta) t -> 'msg -> unit Tezos_base.TzPervasives.tzresult Lwt.t

write_sync conn msg returns when msg has been successfully sent to the remote end of conn, or fails accordingly.

Input functions

val read : ('msg, 'meta) t -> (int * 'msg) Tezos_base.TzPervasives.tzresult Lwt.t

read conn msg returns when msg has successfully been popped from conn's internal read queue or fails with a corresponding error.

val read_now : ('msg, 'meta) t -> (int * 'msg) Tezos_base.TzPervasives.tzresult option

read_now conn msg is Some msg if conn's internal read queue is not empty, None if it is empty, or fails with a corresponding error otherwise.

val stat : ('msg, 'meta) t -> Tezos_base.TzPervasives.P2p_stat.t

stat conn is a snapshot of current bandwidth usage for conn.

val add_closing_reason : reason:P2p_disconnection_reason.t -> ('msg, 'meta) t -> unit

Stores a reason for which it will be closed in a near future.

val close : ?wait:bool -> reason:P2p_disconnection_reason.t -> ('msg, 'meta) t -> unit Lwt.t
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct