Wildland documentation

# Forest

All containers owned by a particular user put together constitute a namespace. We call this namespace a forest.

There is 1-1 mapping between users and forests. This means that we can think of the user ID (in the container address) as a forest ID, and vice versa.

# Forest Manifest

A Forest Manifest is the fundamental data structure used to describe the user forest, together with all its containers, their paths, their storages' location, and encryption keys. A whole forest is fully described by the (exactly one) forest manifest, and a number of (perhaps tens of thousands!) container descriptors.

Forest manifest defines the following crucial information about the forest:

  1. The globally-unique forest identifier, i.e. Forest ID, which is a hash of the master signing key (see below),
  2. The address (endpoint) of the Active Catalog Backend (opens new window) service,
  3. The list of keys approved to sign the operations to modify containers within the forest, called the signer,
  4. The master key, approved to modify the forest manifest itself.

Note that even though this is a self-signing scheme, a change of the master key would automatically result in a different Forest ID.

type: forest
forestid: 0xmyforest # has of the master key
master: 0xmasterhash # approved signer for forest manifest (this file)
signers: # approved signers of container manifests
- 0xmasterhash # optional
- 0xhash1
- 0xhash2
- 0xhash3
catalog: https:// # TBD (compare to legacy Link object)
metadata: {} // # arbitrary data encrypted to the master, optionally (or even likely) it might be merely a pointer to that data to reduce the size of the forest manifest

# Bridges to other forests

Wildland allows cascading navigation between forests. This gives the possibility to create "directories" which contain links to other forests. These links are a special kind of containers, which we call bridges.

The three important pieces of information every bridge provides is:

  1. The public key of the forest which it leads to,

  2. The address of the user manifest for this target forest (which in turn contains all the information required to mount such a forest),

  3. The path(s) claimed by the bridge within the (source) forest, placing it at a particular location within the filesystem representing the directory forest.

Additionally, each bridge, like any other container, has an owner (who we can consider the directory's admin) who signs its manifest, otherwise they would not be present within the directory forest filesystem. This way, even if a directory is kept on untrusted infrastructure, the integrity of the bridges is maintained by the digital signatures of the owner.

Of course it is up to the directory forest owner to decide if a bridge should be published within their forest or not, and under what paths. Wildland does not, and cannot, enforce any policy with regard to how directories could, or should, be constructed and maintained.

# Cascading Addressing

Bridges allow for what we call cascading addressing, which in turn allows others to navigate between forests in different ways.

Consider the following path:

wildland:@default:/mydirs/kartoteka:/forests/pandora:/docs/Container Addressing:/addressing.pdf

It comprises two bridge addresses, plus a final container address, i.e.:

  1. The first bridge placed at /mydirs/kartoteka: within the user's default forest (see below),

  2. The second bridge, placed at /forests/pandora: within the kartoteka forest,

  3. Finally, the /docs/Container Addressing is the address of the container within the pandora forest, and /addressing.pdf is the specific file within that container.

This means that Wildland is a bit like the Internet, except it doesn't rely on any centralized directories, like the DNS system (which is centralized because of the fixed, well known pool of the root DNS servers). Anyone can create a directory, distribute its address to a group of friends or a local community, and thus bootstrap a small network of forests. It can later grow in width -- by including more bridges to other user forests -- and in depth -- by allowing to reach an increasing number of forests indirectly through the forests to which it contains bridges. We like to think about this process as one resembling the bottom-up growth encountered e.g. in the world of plants.

← Forest discovery and addressing →