Kueea Network: Framework

Introduction

Kueea Network provides a formal declaration of a computing network.

It defines a general-purpose transmission protocol model, on top of which various network services may be defined.

Key words

The key words ‘MUST,’ ‘MUST NOT,’ ‘REQUIRED,’ ‘SHALL,’ ‘SHALL NOT,’ ‘SHOULD,’ ‘SHOULD NOT,’ ‘RECOMMENDED,’ ‘NOT RECOMMENDED,’ ‘MAY,’ and ‘OPTIONAL’ in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Kueea Network

A kueea /kwiːa/ (uncountable) is a network resource, which is distinct from other network resources in that it has the ability to cause change. A change introduced by a kueea is signed by the kueea. Kueea are controlled by users of some system.

A user is a physical entity (usually a human) that controls their kueea by interacting with a system.

A Kueea Node is a virtual or physical machine with computing and data storage capabilities, which can also transmit data to and from other Kueea Nodes.

A Kueea Subnet is a set of Kueea Nodes, each configured according to the Subnet's configuration. Such confuguration is immutable and self-identify the Subnet.

A Kueea Relay Node is a Kueea Node, which MAY NOT belong to any Kueea Subnet.

Kueea Network is the sum of all kueea, all Kueea Nodes and all Kueea Subnets.

Subnet database

Each Kueea Node contains a Subnet database. It is a collection of information about Kueea Subnets.

Information in this database is considered public knowledge.

When a Kueea Node receives a packet to a Subnet it does not recognize, the receiver can request the relevant data from the sender and consequently automatically populate the database.

The database is initially populated with data obtained out of band.

Parameters

A parameter is a pair of name and value.

A name is a sequence of (case-sensitive) characters, which is unique within a set of parameters. Names SHOULD be in English.

A value is one of either:

• a number,
• a sequence of up to 8191 characters,
• an array of values,
• a set of parameters.

When referring to a parameter by name, names of parameters within a set are separated with the U+002E FULL STOP (.) character. The part before the FULL STOP references the enclosing set.

Character set is the most recent revision of the Universal Coded Character Set. [ISO10646] [UNICODE]

Sequence of bits

Some values are sequences of bits.

When encoding into a character sequence, a sequence is padded with cleared bits at the end until the sequence's length is a multiple of eight bits. The character sequence is a concatenation of:

1. Amount of padding bits (U+0030 DIGIT ZERO to U+0037 DIGIT SEVEN).
2. A U+003A COLON character.
3. The padded bit sequence encoded with base64 [RFC4648].

External reference

An external reference is a value that is a sequence of characters that uniquely references something.

It SHOULD be a Uniform Resource Identifier. [RFC3986] The "urn" scheme is RECOMMENDED. [[RFC2141][]]

Configuration

Kueea Nodes and Kueea Subnets both have an associated configuration.

A configuration is a set of parameters.

Subnet configuration applied to all Nodes in the Subnet.

Node configuration extends the Subnet configuration with additional configuration parameters that are local to the Node.

Node configuration is applied over Subnet configuration. If Node configuration parameter has the same name as one in the corresponding Subnet configuration parameter, then:

• if the value is a character sequence or a number, such parameter MUST NOT appear in the Node configuration;
• if the value is an array, extend the (Subnet) array with the additional (Node) values;
• if the value is a set of parameters, apply these rules to the parameters in the set.

Canonical serialization

A configuration is serialized into a sequence of octets.

The format of the canonical serialization of a configuration is JSON. [RFC8259]

Sets of parameters are encoded as JSON objects.

Numbers are encoded as JSON numbers.

Arrays of values are encoded as JSON arrays.

Sequences of characters are encoded as JSON strings.

This serialization is devoid of any whitespace between JSON values and, within sets, values are ordered by name in ascending order.

Subnet identifier

A Subnet identifier is a set of at least two hashes.

A hash is a pair of a hash identifier and a hash value.

A hash identifier is a number. Recognized hash identifiers are those registered in the IANA Named Information Hash Algorithm Registry. [RFC6920] The number corresponds to the Suite ID field.

A hash value is a sequence of bits. They are computed over the canonical serialization of a given Subnet configuration.

At least two hashes are used as a protection against hash collisions. All hashes in a Subnet identifier MUST match for an indentifier match.

Node identifier

A Kueea Node may freely move around within the underlying network, causing its physical network location to change over time.

A Node identifier is a sequence of bits, which uniquely identifies a Kueea Node within a Kueea Subnet.

Node identifier is permanently attached to a Node since the time it joins a Subnet to the time it leaves it.

In order to uniquely reference a Kueea Node within Kueea Network, one needs to create a pair of Subnet and Node identifiers.

The domain of Node identifiers depends on Subnet configuration. The length of a Node identifier MUST NOT exceed limits.node bits. The value of the parameter is a positive integer.

Kueea identifier

A kueea identifier is a sequence of bits, which uniquely identifies a kueea within a Kueea Subnet.

The domain of kueea identifiers depends on Subnet configuration. The length of a kueea identifier MUST NOT exceed limits.kueea bits. The value of the parameter is a positive integer.

Packet

A packet is a data structure composed of the following fields:

1. packet timestamp
2. destination Subnet identifier,
3. destination Node identifier,
4. source kueea identifier,
5. source Node identifier,
6. service number,
7. stream number,
8. stream payload,
9. source kueea signature.

Clock

A packet timestamp is a positive integer, an amount of ticks since the epoch of the Subnet.

The amount of ticks MUST NOT be greater than limits.ticks ticks. The value of the parameter is a positive integer.

A tick is defined by the parameter named clockResolution. The Subnet epoch is defined by the parameter clockEpoch. The value of both is an external reference.

The value SHOULD be set right before signature computation.

Packets that are too old MAY be dropped while in transit.

Services

Each packet is addressed to a service offered by the destination Node. Configurations contain a parameter named services. Its value is an array of sets of parameters, each set describing a service.

A service parameter is a parameter in such a set. This term is defined for use in service specifications.

A Kueea Service is a network service which communicates via packets defined in this document and specifies its service parameters.

A service number is an index into the services array, after applying destination Node configuration over the Subnet one. It is a positive integer which MUST NOT be greater than limits.services. The value of limits.services is a positive integer.

Service parameters named proto and required MUST exist. The value of proto is an external reference identifying a protocol. The value of required is a number, which when non-zero, indicates that a Node MUST provide the service in question.

Streams

A stream number is a non-negative integer which MUST NOT be greater than limits.streams. The value of limits.streams is a positive integer.

A stream number coupled with the source Node identifier identifies a stream of packets distinct for each service.

Packets can arrive in a different order than they were sent. Timestamp of the packet can be used to order the packets.

Stream number 0 is the main stream of a service protocol. Streams and their numbers are managed by the protocol.

A stream payload is a sequence of bits. Its length MUST NOT be greater than limits.payload bits. The value of limits.payload is a positive integer.

Signature

A signature is a pair of a signature scheme identifier and a sequence of bits - the signature data.

The set of recognized signature scheme identifiers is determined by the parameter sigSchemes, which is an array of external references, each naming a signature scheme.

A signature scheme identifier is a non-negative integer that is an index into the forementioned array. The value MUST be less than the length of the array.

Signature data is computed over the signature input bitstream.

Signature input bitstream

Each signature scheme defines its word width in bits as an integer greater than zero.

Compute whash by adding one less than word width to 16, then dividing the result by word width. Discard the remainder if any.

Compute wscheme by adding one less than word width to the length of the sigSchemes array minus one, then dividing the result by word width. Discard the remainder if any.

For each of limits.node, limits.kueea and limits.payload, compute the corresponding values wnode, wkueea and wpayload by adding one less than word width to the value, then dividing the result by word width. Discard the remainder if any.

For each of limits.ticks, limits.service and limits.stream, compute the corresponding values wticks, wservice and wstream by encoding the numbers as binary unsigned integers, then counting the number of significant bits, then adding one less than word width to the number of bits, then dividing the result by word width. Discard the remainder if any.

In order to pad a bit sequence s to width w, append cleared bits to s until the length of s is a multiple of w times word width.

In order to append an unsigned integer i to a bit sequence s using width w:

1. Let b be a bit sequence that is the unsigned binary integer representation of i ordered from the least significant to the most significant bit.
2. Pad b to w.
3. Append b to s.

In order to append a bit sequence b to a bit sequence s using width w:

1. Let l be the length of the bit sequence.
2. Append l using w to s.
3. Pad b to 1.
4. Append b to s.

In order to encode a packet into a signature input bitstream:

1. Let sigin be an empty sequence of bits.
2. Append the packet timestamp to sigin using width wticks.
3. For each hash in the destination Subnet identifier, iterated in ascending order by hash identifier: Encode the hash into a Binary Name Format [RFC6920], then append the resulting bit sequence to sigin using width whash.
4. Append the destination Node identifier to sigin using width wnode.
5. Append the source kueea identifier to sigin using width wkueea.
6. Append the signature scheme identifier to sigin, using width wscheme.
7. Append the source Node identifier to sigin using width wnode.
8. Append the service number to sigin, using width wservice.
9. Append the stream number to sigin, using width wstream.
10. Append the stream payload to sigin using width wpayload.
11. Return sigin.

Kueea Transfer Protocol

Each Kueea Relay Node MUST implement at least one Kueea Transfer Protocol. A Kueea Transfer Protocol defines the method of packet transfer, which is composed of three functions:

• distance - a function for determining the distance between two Nodes,
• send - a function for sending a packet to a Node,
• recv - an event, which occurs when a packet is received by a Node.

Kueea Nodes MUST implement the protocol of their Kueea Subnet; Kueea Relay Nodes MAY implement multiple protocols simultaneously. They are thus able to pass on packets to and from Kueea Subnets utilizing different Kueea Transfer Protocols. Such a translation would happen when one Kueea Node sends a packet to another one which is not part of the same Kueea Subnet.

The parameter link.proto is an external reference to an implementation. Each implementation MAY define additional parameters within the link set.

Node distance

This section defines the distance function.

Input:

• Subnet identifier
• source Node identifier
• destination Node identifier

Output:

• estimated time of delivery
• amount of routing points between source and destination Nodes

The source Node counts as one routing point (minimum is one).

If the amount of routing points is zero, it means the destination Node is unreachable.

The estimated time SHOULD be in nanoseconds.

Sending a packet

This section defines the send function.

Input: packet.

Output: boolean value or an error code

The function outputs a value indicating whether the packet was successfully accepted for delivery over a physical network link.

Once accepted, the packet is assumed to be delivered by the caller. There is no indication that the packet actually reached its destination. Service protocols must define a reply if a confirmation is needed.

The destination Subnet identifier MUST NOT be empty.

If the destination Node identifier is empty, the packet is broadcasted to all Nodes in the destination Subnet.

The packet structure provides integrity by definition. An implementation SHOULD additionaly provide packet confidentiality. One way to achieve it is to establish an encrypted channel. Broadcast packets are not confidential by nature.

Receiving a packet

This section defines the recv event handler.

Input: packet.

Output: none.

Upon receiving a packet, an implementation verifies the signature. Kueea Relay Nodes MAY NOT verify signatures. The destination Kueea Node MUST verify the signature. A packet which failed signature verification MUST be discarded.

Dereference mechanism of a kueea identifier to data necessary for verification of a signature is defined by the parameter sigVerify. Its value is an external reference to said mechanism. This mechanism also implicitly defines the domain of kueea identifiers.

The recv event handler is executed with the packet as input once the signature in the packet has been successfully verified.

Service: Role assignment

Kueea Nodes may serve a particular role in a Kueea Subnet. The role assignment is managed by the role assignment service, which MUST be defined and MUST be required.

A Node broadcasts to its Subnet an intent to serve a given role. Other Nodes, upon receiving the intent, may accept it or not. The acceptance is done either explicitly by a reply message or implicitly by accepting incoming data associated with the role.

Examples of roles are: value registry, data archive, public cache, etc. Basically, these are Nodes that are frequently accessed by others. Most of them are expected to have fast connections and high availability.

The intent is periodically broadcasted to ensure it reaches every Node. (One cannot obtain this data from a Node that rejected the intent.) Its frequency is a function of how much thr role is used and time. If the role is actively utilized, informing others is unnecessary. If no one utilizes the role, the intent should be sent more often, but if it is still not being used, then it is better to stop for a while. How many Nodes already serve the role SHOULD also be a factor.

A healthy Subnet is one where multiple Nodes take on the same role, so that if one of them becomes unavailable, there are others remaining; the availability of a role-associated service is thus preserved.

An important part here is that roles are established dynamically and may not require any intervention from a user. Role assignment can be made fully automatic.

Joining and leaving a Kueea Subnet

In order to join a Kueea Subnet, the administrator of a Node broadcasts a "join request" message. Its syntactical structure is defined by the implementation.

The message contains identifiers of the Node and its administrator (kueea) as well as Kueea Transfer Protocol's addresses of the Node. The message MUST be signed by the administrator, which is held responsible for the Node's network behaviour.

Note that the administrator is not necessarily a Node's active user, but as an administrator they have the means to know who and when was using the machine and can lecture the user in question.

Recipients individually reply to the message with one that either accepts the new Node into the Subnet or refuses the join request. If a Kueea Node accepts the request, the reply MUST be sent. The refusal message is OPTIONAL but RECOMMENDED.

Each Node updates its Subnet database with the received data.

The request to leave a Subnet is done similarily, although Nodes are also automatically removed if they stay unreachable.