Cryptographic and Network Primitives

From xx network wiki
Revision as of 22:50, 21 June 2021 by Jono (talk | contribs) (Created page with "{{Note|Two TLS credentials (a certificate and private key pair) and an identification file define the identity of a Node. These files are extremely important to back up and st...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
This is a team contributed page
Two TLS credentials (a certificate and private key pair) and an identification file define the identity of a Node. These files are extremely important to back up and store securely. Loss of these files will make it impossible to reconnect a Node to the network. In following the default guide, these files are named node_cert.crt, node_key.key, gateway_cert.crt, gateway_key.key, and nodeIDF.json. Refer to the Lost Certificate and Important Files Policy for more information.

There are various cryptographic primitives used in the xx network; some are provided by the xx network and some are generated by the Node operator.

Primitives Provided by xx network

The following primitives are provided to you by xx network, either emailed directly or they are downloaded from public repositories.

Registration Code Sent via email The registration code is a 256-bit random number encoded in Base64. It is a single-use code used only on initial registration after which, the Node’s ID and TLS certificate can be used to identify it within the network. This will be provided to each Node operator prior to the network going live.
Permissioning TLS Certificate Provided inside the tarball A TLS certificate is provided to be used to identify the Permissioning server.
Permissioning Server Address Provided inside the tarball The DNS address of the Permissioning server is pre-populated inside the YAML files for Node and Gateway.
Wrapper Script Bucket Address Provided inside the tarball The IP address the Wrapper Script uses to update the binaries. It is pre-populated in the Wrapper Script.
Log Bucket Address Provided inside the tarball The IP address the Wrapper Script uses to upload logs to. It is pre-populated in the Wrapper Script.
cMix Cyclic Group Provided as part of the NDF on initial registration The cMix cyclic group is the modulo cyclic group in which cMix operations are conducted. At launch, this will be defined by a 2048-bit strong and safe prime with a generator of 2.
E2E Cyclic Group Provided as part of the NDF on initial registration The E2E cyclic group is the modulo cyclic group in which end to end encryption operations by clients will be conducted. At launch, this will be defined by a 3192-bit strong and safe prime with a generator of 2.

Primitives Created by the Node Operator

The following primitives are generated prior to and during the initial registration of the Node. More details about generation can be found in Generate TLS Credentials.

TLS Credentials

The TLS credentials are generated as X.509, SHA-256, RSA 4096-bits, and are recommended to last 730 days (2 years). The generated credentials include:

  • Node TLS certificate
  • Node private key
  • Gateway TLS certificate
  • Gateway private key

ID File (IDF)

IDs are 264 bits and consist of a 256-bit hash (BLAKE2b) of a salt and the RSA public key from the Node’s TLS certificate appended with a 8 bits that describe the ID type.

ID = Hash(Node_PubKey, Salt) + TYPE

Due to the construction of the ID, the ownership of the ID can be proved under RSA’s cryptographic assumptions. Due to the hash, IDs are unpredictably generated in a large sparse space so it is overwhelmingly improbable that independently generated IDs will ever collide, so no central checking of ID generation is necessary.

The last byte of the ID is a type byte which describes what type of entity it belongs to. The options for type are:

Type Hex Note
Generic 0x00 Used for one-off entities such as the Permissioning server, the notifications server, and others
Gateway 0x01 The Gateways in the network
Node 0x02 The Nodes in the network
User 0x03 Unique client ID

On first run, the Node automatically generates the ID and saves it to a JSON file with the following structure.

{
	"id": "1Mo9im6HHpoTDt/lTYjSkWV7dAD0Eh+18xUFfxlm4I4C",

The ID of the Node or Gateway, presented as a base 64 encoded string.

	"type": "node",

The type of ID is shown here for readability.

	"salt": [119, 234, 246, 209, 166, 166, 72, 17, 253, 196, 172, 187, 230, 2, 132, 137, 49, 219, 142, 58, 82, 169, 60, 230, 112, 17, 30, 112, 30, 68, 217, 92],

The salt used to generate the ID.

	"idBytes": [212, 202, 61, 138, 110, 135, 30, 154, 19, 14, 223, 229, 77, 136, 210, 145, 101, 123, 116, 0, 244, 18, 31, 181, 243, 21, 5, 127, 25, 102, 224, 142, 2],
}

The ID of the Node or Gateway, presented as an array of bytes.