Time of page creation
Time of last modification
Author
Inumi <inumi@fumu-no-kagomeko.kueea.cyou>

Kueea Network: Framework

Draft; do not implement.

Introduction

Kueea Network is a networking system composed of subnets and actors.

A subnet is defined by its immutable descriptor, which includes a list of offered services as well as the policy for each of them.

Nodes of a subnet are contracted by the subnet's descriptor. A host wishing to become a node of a subnet must comply with the requirements laid out in the subnet's descriptor. Otherwise the host is not considered to be a node.

The core part of the system is automatic detection of service policy violations and subsequent detection of bad network actors. Every packet is cryptographically signed by the actor that sent it.

An actor's identity is globally unique and not tied to any particular host, subnet nor service.

The behaviour of an actor is recorded into its descriptor, so that the whole network has information about it, not just a single service or a single subnet. Actors are rewarded for their good behaviour and punished for their bad behaviour (policy violations).

Hosts are not actors in this system. Hosts are instructed by actors to send packets.

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.

Basic terms

Kueea Network is the sum of all kueea, all nodes and all subnets.

Kueea and users

A kueea /kwiːa/ (uncountable) is a network actor. All acts done by a kueea are cryptographically signed by said kueea. Sending a packet is one of many acts a kueea can do.

A user is a physical entity (usually a human) that controls kueea by interacting with a Kueea Node and supplying it with data necessary for creating signatures.

While kueea are controlled by users, they do not represent them. One kueea may be controlled by multiple different users and it is not against the system for users to trade this control. Kueea control is meant to be seen as a tradeable asset and kueea themselves hold value.

One analogy is that kueea are characters and users are those who play as them. Anyone could play as the character, but its value is determined by how it is being played.

Nodes and subnets

A Kueea Node is a virtual or physical machine with computing and data storage capabilities, which can send and receive packets 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.

Software

A Kueea Service is a program executing on a node, which processes packets sent to it by a kueea.

Each service has an assciated policy, a network resource that specifies service configuration parameters. Formats of policies depend on the associated service.

A Kueea Transfer Protocol transforms a packet to a concrete binary representation for actual transfer over a network link. It also implement functions for the management of the network database.

Kueea Services and Kueea Transfer Protocols are defined by other documents.

Kueea Network Software is an operating system component which sits between [transfer protcols][] and services.

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 sequence of bits.

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.

An array is encoded as a JSON array.

A number is encoded as a JSON number.

A string is encoded as a JSON string prepended with s:.

A reference is encoded as a JSON string prepended with r:.

A bitstring is encoded as a JSON string 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.

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.

Kueea descriptor

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

There is a one-to-one relation between a kueea and its associated kueea descriptor.

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

The kueea parameter verifiers is REQUIRED. Its value is an array of verifier descriptors.

Kueea identifier

A kueea identifier is a bitstring, which uniquely identifies a kueea within Kueea Network.

Subnet descriptor

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

There is a one-to-one relation between a subnet and its associated subnet descriptor.

The subnet parameter schemes is REQUIRED. Its value is an array of supported signature scheme identifiers.

The subnet parameter services is REQUIRED. Its value is an array of service descriptors.

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

The subnet parameter endpoints is REQUIRED. Its value is an array of endpoint descriptors, the proto endpoint parameter of which MUST be one of the protocol identifiers listed within the subnet parameter protocols.

The subnet parameter nodes is OPTIONAL. Its value is an array of node descriptors.

Subnet identifier

A subnet identifier is an array of at least 2, at most 255, subnet hashes.

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

A subnet hash is a bitstring, which contains a name in binary format as defined in RFC6920, Section 6, containing a subnet hash value.

A subnet hash value is a hash value, computed over the canonical serialization of a subnet descriptor, after removal of the nodes subnet parameter.

For a subnet identifier to match a subnet descriptor, all its subnet hashes MUST contain a subnet hash value that is computed from the descriptor.

Service descriptor

A service descriptor is a descriptor, which consists of service parameters.

A service descriptor is associated with a service offered by every node of a subnet.

The service parameter id is REQUIRED. Its value is a service identifier.

The service parameter policy is REQUIRED. Its value is a reference to a policy.

Service identifier

A service identifier is a reference, which uniquely identifies a service within Kueea Network.

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.

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

The node parameter endpoints is REQUIRED. Its value is an array of endpoint descriptors, the proto endpoint parameter of which MUST be one of the protocol identifiers listed within the subnet parameter protocols.

Node identifier

A node identifier is a bitstring, which uniquely identifies a node within a 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 maximum length of a node identifier in bits is determined by the subnet parameter nodeIDmax. Its value is an unsigned integer.

Endpoint descriptor

An endpoint descriptor is a descriptor, which consists of endpoint parameters.

An endpoint descriptor is associated with an endpoint.

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

Other endpoint parameters are defined by the transfer protocol identified by the endpoint parameter proto.

Protocol identifier

A protocol identifier is a reference, which uniquely identifies a transfer protocol within Kueea Network.

Verifier descriptor

A verifier descriptor is a 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 NOT be greater than 65535.

The value of id MUST be unique within the array of node parameter and kueea parameter verifiers.

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

Other verifier parameters are defined by the signature scheme identified by the verifier parameter scheme.

Signature scheme identifier

A signature scheme identifier is a reference, which uniquely identifies a signature scheme within Kueea Network.

Packet

A packet is a piece of data, sent from a kueea, via a node, addressed to either a kueea, a single node in a subnet or all nodes in a subnet.

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. The packet goes to any of the node's endpoints.

If the destination kueea identifier is empty and the destination node identifier is not empty, the packet is addressed to the given node. The packet goes to any of the node's endpoints.

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][]. The packet goes to any of the subnet's endpoints.

If the destination kueea identifier is empty and the destination node identifier is empty, the packet is addressed to the subnet. The packet goes to any of the subnet's endpoints.

All other [bitstrings][] MUST NOT be empty, except for stream data.

Flow

A program is executing on behalf of a kueea.

The program creates a packet and fills out all fields except for source node identifier and source node signature. Once it computes the source kueea signature, it passes the packet to the network software.

The network software recieves the packet from the program, then fills out the source node identifier and computes the source node signature. It then passes the packet to a transfer protocol for delivery.

The packet is received by a transfer protocol implementation and passed to the network software of the destination node.

The network software verifies both the source node signature and the source kueea signature, then passes the packet to the service.

If a signature is invalid, the packet MUST be dropped.

The destination node MUST verify [signatures][]. Intermediary routers MAY NOT verify [signatures][].

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 subnet parameter 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 stream nonce as in the received packet, in order to associate the two packets with each other.

The maximum value of a stream nonce and whether some of the values have special meaning are all defined by the associated service.

Stream sequence

Most services require a sequential stream of ordered packets sent from a given source to a given destination.

A stream is identified by a packet's:

A stream sequence is an unsigned integer, which designates the position of a packet in its stream.

The initial value of a new stream is zero. It increments by one with each packet sent on the same stream.

Stream data

Stream data is a bitstring, content of which is defined by the associated service.

Signature

A signature scheme is a method of computing a bitstring, called the signature data, from signature input and other scheme-defined data.

Signature schemes are defined by other documents.

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

Signature input

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.

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.

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

Byte encoding of an unsigned integer

In order to encode an unsigned integer num:

  1. Let out be an empty byte sequence.
  2. Let bin be the binary representation of num.
  3. Let shift be one less than byte width.
  4. Let bits be the amount of significant bits of bin, rounded up to the nearest multiple of shift.
  5. While bits is greater than zero:
    1. Let byte be a byte with all bits cleared.
    2. Set shift least significant bits of byte to the corresponding bits of bin.
    3. Shift bin toward the least significant position by shift bits.
    4. Subtract shift from bits.
    5. If bits is greater than zero, set the most significant bit of byte.
    6. Append byte to out.
  6. Return out.

Byte encoding of a bitstring

In order to encode a bitstring seq:

  1. Let out be an empty byte sequence.
  2. Let bits be the length of seq.
  3. Encode bits 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.

Byte encoding of a subnet identifier

A subnet identifier is encoded for signature input as follows:

  1. Let out be an empty byte sequence.
  2. Encode the amount of hashes and append the result to out.
  3. For each hash in the array, encode hash and append the result to out.
  4. Return out.

Byte encoding of a signature

A signature is encoded for signature input as follows:

  1. Let out be an empty byte sequence.
  2. Encode the verifier identifier and append the result to out.
  3. Encode the signature data and append the result to out.
  4. Return out.

Transfer protocol

A transfer protocol is composed of two functions and two events.

Endpoint

An endpoint is a network location of a router.

The same endpoint MAY be shared by multiple routers. An endpoint specifies the first receiver of a packet. 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 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, network software keeps the 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 is the packet, delivery of which is being confirmed.

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