Time of page creation
Time of last modification
Kueea (author)
Inumi <inumi@fumu-no-kagomeko.kueea.cyou>

Kueea Network: Framework

Draft; do not implement.

Introduction

Kueea Network is a general-purpose transmission protocol model, on top of which various network services may be defined.

Packets are sent between nodes of a subnet, which must publish its node configuration requirements. All participating nodes must also publish their conforming configuration, which includes a list of offered services, node administrator designation, means of authenticating that a packet came from the node and a network protocol and address on which the node listens for incoming packets.

This document defines the structure and semantics of a packet. Definition of a concrete packet transmission protocol is out of scope.

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.

Terminology

A kueea /kwiːa/ (uncountable) is a network resource, which is distinct from other network resources in that it has the ability to act. All acts done by a kueea are cryptographically signed by said kueea. Sending a packet is one of many acts a kueea can do. Kueea are controlled by users of some system. A kueea represents itself, not the user that controls it.

A user is a physical entity (usually a human) that controls their kueea by interacting with a system. The distinction is important because kueea can be automated, a kueea may be controlled by multiple users (with or without consent); kueea control is also transferrable between users.

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 node administrator of a Kueea Node is a kueea, which is held fully responsible for its network activity.

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

A Kueea Router is a Kueea Node, which MAY NOT belong to any Kueea Subnet. In other words, Kueea Routers cannot be packet destinations. They only route, transfer packets closer to their destination.

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

Descriptor

A descriptor is a set of parameters, which contains configuration parameters associated with a network resource.

Parameters

A parameter is a pair of name and value.

A name is a reference.

All parameter names referenced in this document MUST be prefixed with URI-TO-BE-DECIDED# in order to form the full name of the parameter.

A value is either:

Number

A number is a real number.

Integer

An integer is a number with no fractional part.

Unsigned integer

An unsigned integer is a non-negative integer.

Boolean

A boolean is a number which MUST be equal to either 0 (false) or 1 (true).

String

A string is a sequence of up to 8191 characters.

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

Bitstring

A bitstring is a string.

The string is generated from a sequence of bits as follows:

  1. Let str be an empty string.
  2. Pad the bit sequence with cleared bits at the end until the sequence's length is a multiple of eight bits.
  3. Append the amount of padding bits (U+0030 DIGIT ZERO to U+0037 DIGIT SEVEN) to str.
  4. Append a U+003A COLON character to str.
  5. Encode the padded bit sequence with base64 [RFC4648] and append the resulting character sequence to str.
  6. Return str.

Reference

An reference is a Uniform Resource Identifier, which SHOULD be a name, not a location, of a resource. [RFC3986]

Array

An array is an ordered list of values.

Set of parameters

A set of parameters is an unordered list of parameters with a unique name within the list.

Canonical serialization

A descriptor is serialized into a sequence of octets.

The format of the canonical serialization of a descriptor uses JSON [RFC8259] as serialization format.

A set of parameters is encoded as a JSON object.

A number is encoded as a JSON number.

An array is encoded as a JSON array.

A string is encoded as a JSON string.

A reference is encoded as a JSON string.

This serialization MUST NOT contain any whitespace between JSON values and, within JSON objects, values are ordered by their name in ascending order by Unicode code point.

Network database

Each node contains a network database. It is a collection of kueea descriptors, subnet descriptors and their node descriptors.

All information in this database is public.

A node is not required to store a complete copy of the database. Necessary data is obtained from the [network][] as needed.

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

When a router receives a packet to an unknown subnet or node, it can request the relevant data from the sender and consequently automatically populate the database.

Subnet descriptor

A subnet descriptor is a descriptor, which consists of service parameters. A subnet descriptor is associated with a specific subnet.

The subnet parameter subnet is REQUIRED. Its value is a subnet identifier.

Node descriptor

A node descriptor is a descriptor, which consists of node parameters. A node descriptor is associated with a specific node in a specific subnet.

The node parameter node is REQUIRED. Its value is a node identifier.

Effective node descriptor

An effective node descriptor is a descriptor, which consists of effective node parameters. An effective node descriptor is associated with a specific node in a specific subnet.

It is the result of adding a node's node descriptor to its subnet descriptor.

For each parameter with the same name in the subnet descriptor and the node descriptor:

Kueea descriptor

A kueea descriptor is a descriptor, which consists of kueea parameters. A kueea descriptor is associated with a kueea.

Kueea and their descriptor are unique within Kueea Network, although their identifiers are defined by a subnet.

The kueea parameter ids is REQUIRED. Its value is an array of arrays of two values: a subnet identifier and a kueea identifier.

Service descriptor

A service reference is a reference to a service.

A Kueea Service is a node program, which processes packets received from kueea. Kueea Services are defined by other documents. A service is identified by its service reference.

The effective node parameter services is REQUIRED. Its value is an array of descriptors.

Each one is a service descriptor, which consists of service parameters. A service descriptor is associated with a service offered by a node.

The service parameter proto is REQUIRED. Its value is a service reference.

The service parameter testing is REQUIRED. Its value is a boolean, which, when true, indicates that the node is currently testing its service implementation. Kueea are encouraged to send packets even when they do not particularily need to use the service. This parameter MUST NOT appear in a subnet descriptor.

If a service descriptor is part of a subnet descriptor, an associated effective node descriptor will contain it; thus, this means the service is REQUIRED within the subnet. Lack of node support for such a service MAY result in a ban. The ban SHOULD be targetting the node administrator in this case, stripping the kueea of the right to join the subnet.

Endpoint descriptor

A protocol reference is a reference to a transfer protocol.

The subnet parameter protocols is REQUIRED. Its value is an array of protocol references, naming transfer protocols that are supported in the subnet.

The node parameter endpoints is REQUIRED. Its value is an array of descriptors.

Each one is an endpoint descriptor, which consists of endpoint parameters. An endpoint descriptor is associated with an endpoint, a network location of a router.

The endpoint parameter proto is REQUIRED. Its value is a protocol reference.

The effective node descriptor MUST contain at least one endpoint descriptor, proto value of which is included in the subnet parameter protocols array.

The same endpoint MAY be shared by multiple nodes. An endpoint of a node specifies the first receiver of a packet addressed to the node. The router then takes care of subsequent delivery, which might include further transfer of the packet, using protocols other than the endpoint's transfer protocol.

The subnet parameter broadcast is REQUIRED. Its value is an endpoint descriptor for broadcast packets.

Verifier descriptor

A signature scheme reference is a reference to a signature scheme.

A signature scheme is a method of computing a sequence of bits, called the signature data, from a sequence of bytes and other scheme-defined data. Signature schemes are defined by other documents. A signature scheme is identified by its signature scheme reference.

Each signature scheme defines its byte width, an integer greater than zero, which is the amount of bits in a single byte of input to the scheme.

Both a kueea descriptor and a node descriptor MUST include a parameter named verify. Its value is an array of descriptors.

Each one is a verifier descriptor, which consists of verifier parameters. A verifier descriptor is associated with a method and data required to verify a signature.

The verifier parameter id is REQUIRED. Its value is an unsigned integer called a verifier identifier. The value MUST be unique within a verify array and MUST NOT be greater than 65535.

The verifier parameter scheme is REQUIRED. Its value is a signature scheme reference.

The subnet parameter schemes is an array of signature scheme references that are supported in the subnet.

Packet

A packet is a piece of data, sent from a kueea, via a node, addressed to either a kueea or to a node. It is a data structure composed of the following fields:

If the destination kueea identifier is not empty and the destination node identifier is not empty, the packet is addressed to the given kueea, expecting an active user session at the given node.

If the destination kueea identifier is not empty and the destination node identifier is empty, the packet is addressed to the given kueea at any node the kueea has an active user session.

If the destination kueea identifier is empty and the destination node identifier is not empty, the packet is addressed to the given node.

If the destination kueea identifier is empty and the destination node identifier is empty, the packet is a broadcast packet.

All other fields MUST NOT be empty, except for stream data.

Flow

A program is executing on behalf of a kueea.

The program creates a packet, sets the source kueea, destination kueea, destination node and subnet identifiers, the service number and stream nonce, sequence and data.

It then computes the source kueea signature and passes the packet to Kueea Network Software.

Kueea Network Software recieves the packet from the program, sets the source node identifier and computes the source node signature.

It then passes the packet to a transfer protocol implementation of choice for delivery.

The packet is received at the destination node by its transfer protocol implementation and passed to Kueea Network Software of the destination node.

Kueea Network Software verifies the node and kueea signatures. If a signature is invalid, the packet MUST be dropped. If the signatures are valid, Kueea Network Software passes the packet to the service.

Kueea Routers MAY NOT verify signatures.

Kueea Nodes that are the packet's destination MUST verify signatures.

Signature input

A signature input is a sequence of bytes, generated from a list of packet fields, by encoding each field into a sequence of bytes, and then concatenating the encoded fields, in list order.

Unsigned integer

In order to encode an unsigned integer num with a limit of max:

  1. Let out be an empty byte sequence.
  2. Let maxbin be the binary representation of max.
  3. Let maxbits be the position of the most significant bit in maxbin that is set, counting from 1 from the least significant bit to the most.
  4. Let bytes be an integer equal to maxbits.
  5. Add one less than byte width to bytes.
  6. Divide bytes by byte width. Discard the remainder if any.
  7. Let bin be the binary representation of num.
  8. While bytes is greater than zero:
    1. Append the least significant byte width bits of bin to out as a byte.
    2. Shift bin toward the least significant position by byte width bits.
    3. Subtract one from bytes.
  9. Return out.

Sequence of bits

In order to encode a bit sequence seq with a maximum length of maxbits:

  1. Let out be an empty byte sequence.
  2. Let bits be the length of seq.
  3. Encode bits with a limit of maxbits and append the result to out.
  4. Let bytes be an integer equal to bits.
  5. Add one less than byte width to bytes.
  6. Divide bytes by byte width. Discard the remainder if any.
  7. While the length of seq is not a multiple of byte width:
    1. Append a cleared bit to seq.
  8. While bytes is greater than zero:
    1. Append the first byte width bits of seq to out as a byte. The bits follow the order of bit significance in a byte. (The first bit of seq will be the least significant.)
    2. Remove the first byte width bits from seq.
    3. Subtract one from bytes.
  9. Return out.

Subnet identifier

A subnet identifier is an array of at least 2, at most 255, hashes, which MUST be in ascending order by their identifier.

A hash is an array of two values: a hash identifier and a hash value.

A hash identifier is an unsigned integer. 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 bitstring. It is computed over the canonical serialization of the identified subnet descriptor without the subnet parameter.

At least two hashes are used as a protection against hash collisions.

All hashes in a subnet identifier being compared MUST match with the corresponding hashes in a compared subnet descriptor, for the subnet identifier to be a valid match.

A subnet identifier is encoded for signature input as follows:

  1. Let out be an empty byte sequence.
  2. Encode the amount of hashes with a limit of 255 and append the result to out.
  3. For each hash in the array:
    1. Encode the hash identifier of hash with a limit of 255 and append the result to out.
    2. Decode the hash value of hash into a sequence of bits and encode it with a maximum length of 4096 and append the result to out.
  4. Return out.

Node identifier

A node identifier is a bitstring, which uniquely identifies a node within its subnet.

A node identifier is associated with a node since the time it joins a subnet until the time it leaves it.

In order to uniquely reference a node within Kueea Network, one needs a pair of a subnet identifier and a node identifier.

The length of a node identifier MUST NOT exceed limits.node bits. The value of the parameter is an unsigned integer.

A node identifier is encoded for signature input by decoding it to a sequence of bits and encoding the sequence with a maximum length of `limits.node`.

Kueea identifier

A kueea identifier is a bitstring, which identifies a kueea within a subnet.

The subnet parameter kueeaderef is REQUIRED. Its value a reference to a Kueea Dereference Protocol.

A Kueea Dereference Protocol is a method of dereferencing a kueea identifier to its associated kueea descriptor. Kueea Dereference Protocols are defined by other documents.

The subnet parameter limits.kueea is REQUIRED. Its value is an unsigned integer. The length of a kueea identifier MUST NOT exceed limits.kueea bits.

A kueea identifier is encoded for signature input by decoding it to a sequence of bits and encoding the sequence with a maximum length of `limits.kueea`.

Service number

Each packet is addressed to a service offered by the destination node.

A service number is an unsigned integer, which is an array index into the effective node parameter services.

The subnet parameter limits.services is REQUIRED. Its value is an unsigned integer. Service numbers MUST be less than limits.services.

Service numbers are encoded for signature input by encoding the number with a limit of `limits.services`.

Stream nonce

A stream nonce is an unsigned integer, which identifies a stream of packets.

The value MUST be unique within a reasonable period of time. It SHOULD be randomly generated if possible. A timestamp can be used, too, but it is NOT RECOMMENDED.

Replies use the same nonce as in the received packet, in order to associate the two packets with each other.

The subnet parameter limits.nonce is REQUIRED. Its value is an unsigned integer. A stream nonce MUST NOT be greater than limits.nonce.

Stream nonces are encoded for signature input by encoding the value with a limit of `limits.nonce`.

Stream sequence

Most communications require packets to be ordered into a sequential stream of packets, sent from a given source and addressed to a given destination.

A stream is identified by a packet's subnet identifier, source and destination [node identifiers][], kueea identifier, service number and stream nonce.

A stream sequence is an unsigned integer, which designated the position of the packet in its stream. The value increments by one with each packet on the same stream.

The subnet parameter limits.sequence is REQUIRED. Its value is an unsigned integer. A stream sequence MUST NOT be greater than limits.sequence.

If stream sequence is equal to 0, then there is no stream; or rather, the stream starts and ends with this one packet. A transfer protocol can optimize delivery accordingly.

The service defines how to handle a situation when the stream sequence reaches limits.sequence.

Stream sequences are encoded for signature input by encoding the value with a limit of `limits.sequence`.

Stream data

Stream data is a sequence of bits, content of which is defined by the service.

The subnet parameter limits.data is REQUIRED. Its value is an unsigned integer. The length of stream data MUST NOT be greater than limits.data bits.

Stream data is encoded for signature input by encoding it with a maximum length of `limits.data`.

Signature

A signature is a pair of a verifier identifier and signature data.

A signature is encoded for signature input as follows:

  1. Let out be an empty byte sequence.
  2. Encode the verifier identifier with a limit of 65535 and append the result to out.
  3. Encode the signature data with a maximum length of 65535 and append the result to out.
  4. Return out.

Kueea signature

For a kueea signature, the signature input is generated from the following list of fields:

  1. subnet identifier
  2. destination node identifier
  3. destination kueea identifier
  4. source kueea identifier
  5. service number
  6. stream nonce
  7. stream sequence
  8. stream data

Node signature

For a node signature, the signature input is generated from the following list of fields:

  1. source kueea identifier
  2. source kueea signature
  3. source node identifier

Transfer protocol

A Kueea Transfer Protocol is a method of packet transfer, identified with its protocol reference.

The protocol is composed of two functions and two events.

The distance function

Input
subnet: subnet identifier
source: node identifier
destination: node identifier
Output
duration: [unsinged integer][]
points: unsigned integer

The distance function computes the estimated time duration and the amount of routing points between a source node and the destination node within a subnet.

The source node counts as one routing point. If routes is zero, it means destination node is unreachable.

The duration SHOULD be in nanoseconds.

The send function

Input
packet: packet
confirm: boolean
Output
error: integer

The send function accepts a packet for delivery.

If confirm is true, packet MUST be sent together with a delivery confimation request. The method of confirming is implementation-defined.

For packets that were sent with confirm set to true, Kueea Network Software keeps packet in its cache until it receives a confirmed event from the implementation.

The error is an implementation-defined error code. It indicates whether packet was successfully accepted for delivery over an implementaion-defined network link or not.

The structure of a packet provides integrity by definition. An implementation SHOULD additionaly provide confidentiality. One way to achieve it is to establish an encrypted channel.

The confirmed event

Input
packet: packet

A confirmed event handler is invoked when the implementation receives a delivery confirmation message.

The packet MUST have the following fields set to exactly the same values as in the packet, delivery of which is being confirmed:

The value of all other fields is undefined.

The received event

Input
packet: packet

A received event handler is invoked when the implementation completely receives a packet on its endpoint.

The packet is the received packet.

Appendix A: Table of parameters

Subnet parameters

Node parameters

Kueea parameters

Signature parameters

Service parameters

Endpoints parameters