Publishing in Freenet

A Guide to Freenet Keys

0. Introduction

As Freenet nears a state where it should be usable by casual computer users, it is probably about time we actually provided a good explanation about how content can be placed on Freenet for people to view, and also to detail a few tricks which may be useful.

This guide describes each type of key and explains how to use each one.

0.1 The Basics

Freenet, as far as the user is concerned, stores and retrieves information. When you store some information you can choose a key, or in some cases one is chosen for you. If you are chosing your own key it must be unique or Freenet will not allow you to store anything under that key. At some later date, you, or someone else, can retrieve the information by giving Freenet the key. Freenet doesn't guarantee that you will be able to retrieve a piece of information stored previously, as sometimes Freenet needs to delete older information to make room for newer content.

0.2 Clients

Freenet itself merely provides the infrastructure for storing and retrieving information, it does not provide an easy-to-use interface for the user. To address this issue we encourage the creation of Freenet clients. A client may be specific, such as one which allows the storing of music in Freenet, or may be generic, such as one which can store and retrieve files from and to your hard-disk. One client which we anticipate will be particularly useful is FProxy which allows you to access information on Freenet through your web-browser as if you were just accessing websites on the World Wide Web. This presents a familiar interface to the end user while taking advantage of the web-browser to handle the presentation of information. Some of these clients will just provide means to access information on Freenet, where as some will allow you to place information of Freenet too.

Fproxy lets you insert and retrieve keys but the command line interfaces give you more options. Windows users have frequest.exe and finsert.exe to request and download keys. *nix users have freenet_request and freenet_insert.

One option Fproxy doesn't let you specify is HTL or hops to live. HTL specifies the depth of your insertion or search. The higher the HTL the farther your data will spread when inserting or the farther Freenet searches for data when you make a request.

In any of the examples that follow you can specify the HTL by adding -htl number. Freenet uses the default value specified in your configuration file if you do not use the -htl option.

This guide details the use of the command line interfaces. The Fproxy web interface is easy to use and should be familiar to the casual Web user.

0.3 Key types

I mentioned in section 0.1 that sometimes you get to choose your own key, and sometimes one is chosen for you. At present there are four types of key in Freenet that you have at your disposal:

0.3.1 Content Hash Key (CHK)

CHKs are the work-horses of Freenet. Normally data is not stored under KSKs or SSKs (see below), but is stored under a CHK and a "redirect" to the data is stored under the KSK or SSK. A redirect is a mechanism supported by all clients where the data under one key can instruct the client to download the data under another key and pretend that the data was found under the first key. When you insert a CHK you insert it as CHK@, after the data has been inserted the client will tell you what the CHK's actual name is. The reason for this is that the name of the CHK is determined by the data itself, two CHKs containing the same data will have the same CHK, and two CHKs with different data will have different names.

Note the format - all Freenet keys start with freenet:, then the three letter acronym of the keytype, then an @, and then some stuff specific to the key. You can sometimes leave out the freenet: part and a client will fill it in for you.

With the command line interface you would insert a file named boat.gif as a CHK key like this:

Example:

(Windows users)
finsert freenet:CHK@ boat.gif

(*nix users)
freenet_insert freenet:CHK@ boat.gif

When the insertion is complete you will be told the CHK value which will look something like:

freenet:CHK@zdfaGTyeEygcbWqBOmVYW0BcGC8JAwE,fpR1hig2f0YqrYARYI0KHg

0.3.2 Keyword Signed Key (KSK)

A KSK is probably the simplest and most user-friendly keytype, since it is simply a name that you choose yourself when you insert the data. A typical KSK might look like:

freenet:KSK@meaningful_name.txt

With some clients you can sometimes leave out KSK@ and it will be assumed that you are referring to a KSK.

If you have an image file named 1000.jpg and you want to insert it in Freenet as house.jpg using a KSK key you would do this:

Example:

(Windows users)
finsert freenet:KSK@house.jpg 1000.jpg

(*nix users)
freenet_insert freenet:KSK@house.jpg

Users could then retrieve your image file with:

(Windows users)
frequest freenet:KSK@house.jpg house.jpg

(*nix users)
freenet_request freenet:KSK@house.jpg house.jpg

This would save the file as house.jpg in your current directory.

If you try to insert a file that someone has already inserted, but under a different name, you will be informed that a duplicate copy exists. Although your file shares the same CHK your KSK will be inserted with a reference to the CHK.

So, if you insert freenet:KSK@coolboat.jpg and another user inserted the same file previously but under the key freenet:KSK@red_sailboat.jpg you would be informed that the CHK exists already but your KSK will still be inserted. There will be two KSK keys referencing the same CHK key.

When referring to KSK key types you can sometimes leave off the freenet:KSK@ and clients will assume you mean a KSK.

If you want to retrieve a key with your web browser through Fproxy, you would use your computer's address and Fproxy port with the key. The default port is 8081 but can be changed in your configuration file or with a configuration program. To retrieve your house image file you inserted use this URI in your web browser:

http://127.0.0.1:8081/freenet:KSK@house.jpg

The '127.0.0.1:8081' tells your web browser to connect to your own computer via Fproxy on port 8081.

0.3.3 SubSpace Key (SSK)

Like CHKs you don't get a choice as to what a SSK is called. When you create an SSK you are told what the SSK is, and you are also given a "private key" to the SSK. The main purpose of SSKs are for the creation of files in a common namespace such as:

SSK@public_key/music/bach/song1.mp3
SSK@public_key/music/bach/song1.mp3
SSK@public_key/music/mozart/song1.mp3
SSK@public_key/music/mozart/song2.mp3

SSKs allow you to insert a document (which you name yourself, like a KSK) "under" an SSK namespace, but only if you have the private key (ie. if you are the creator of the SSK, or the creator has given you the private key). If the SSK was SSK@ASDF (it would actually be much longer than that), with private key PRIV and you wanted to insert an SSK under the name "fred" under that SVK, you would insert it as SSK@PRIV/fred. If someone then wanted to request it they would request SSK@ASDF/fred.

SSKs are useful because they provide a mechanism for regular publication in Freenet under a namespace where you know the creator is the same person. You don't know if KSK@books/story1.txt and KSK@books/story2.txt were created by one person or two different people.

Because only the private key holder can publish within an SSK namespace you can be confident that only the key holders are publishing in that particular SSK namespace.

To create your private and public SSK keys:

(Windows users)
finsert -makeKeypair

(*nix users)
freenet_insert -makeKeypair

Make a note of the pair of keys and keep them somewhere safe. If you lose the private key you are out of luck.

SSK keys and namespace lead the way to creating more dynamic content in Freenet. The most common are freesites or websites in Freenet using MSK keys which rely on SSK keys.

Note: SSK keys rely on SVK (Signature Verified Key) keys which work behind the scenes. In future versions of Freenet you will be able to update data using SVKs, but for now you don't need to worry about them.

0.3.4 MapSpace Keys (MSK)

MSKs provide a mechanism for publishers to create dynamic content. While you can't update data directly in Freenet at this time, you can use MSKs to simulate the same effect.

Freesites, or websites in Freenet, are accessed via Fproxy and appear as a regular website.

You will notice freesites with addresses such as:

MSK@SSK@enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/homepage//

Viewers will visit the same address, but the content will change over time like a regular website.

What the MSK key actually provides is a date based method of accessing namespaces. When your web browser uses an MSK key, Freenet actually translates the MSK key into an address based on the current date. So our example above is translated internally to:

MSK@SSK@enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/20010510000000-homepage//

This example is for the site on May 10, 2001. You can actually enter that address in your browser or change the date portion manually to see 'older' versions of the site if they still exist in Freenet. Most sites are updated every 24 hours at midnight GMT. You can choose a different update interval when you create an MSK based site.

For a complete guide to publishing with MSK keys please see Creating Freesites