Front Page

Explorers
- What is Freenet
- Donate!
- People
- Publicity
- Philosophy
- Translations

Users
- Download
- ScreenShots
- Documentation
- FAQ
- Third Party Tools
- Report Bug
- Mailing Lists

Authors
- Publishing

Developers
- Papers
- Architecture
- Browse CVS
- Public Area
- About This Site

Login & Edit

Hosted by
SourceForge


Abstract

The FreenetClientProtocol (FCP) is designed to abstract the basics of Freenet so that client developers do not have to track the main Freenet protocol. FCP should be the bare bones of Freenet - metadata handling is not included in FCP though an extension to FCP may come about at a later date to avoid writing metadata handling libraries in many languages.

Note

This protocol is never meant to go across a network - only via the loopback. Nodes should not accept FCP connections from hosts other than localhost by default.

Basics

By default FCP is port 8481, but any client that uses FCP should leave this configurable, because this may be changed in the node's configuration file or by some future FCP revision.

FCP follows the FNP setup for session and presentation.

In the following, numbers are always hex-encoded and fields in square-brackets are optional.

FCP allows one transaction per connection, after which the connection is torn down. At the beginning of each connection, the client must send these 4 bytes:

00 00 00 02

These are the 2-byte session identifier and the 2-byte presentation identifier. In the future, different identifiers may be used to allow alternate syntaxes or encrypted FCP connections from remote hosts, for example.

After sending the session and presentation identifiers, the client sends a message to initiate the transaction, then waits for one or more messages from the node until the transaction is complete. Messages are a series of lines terminated by LF or CRLF, in this form:

Header
[Field1=Value1]
.
.
[FieldN=ValueN]
EndMessage

Message summary

This is the complete set of client to node messages, with the possible node to client responses (only the headers are listed).

  • ClientHello
    • NodeHello

  • ClientGet
    • URIError
    • Restarted
    • DataNotFound
    • RouteNotFound
    • DataFound
      • DataChunk

  • ClientPut
    • URIError
    • Restarted
    • RouteNotFound
    • KeyCollision
    • Pending
    • Success

  • GenerateCHK
    • Success

  • GenerateSVKPair
    • Success

Additionally, the node may respond to any client message with a FormatError, meaning the command was not understood, and the node may responsd at any time with a Failed, indicating a fault in the node itself:

(Node -> Client)

FormatError
[Reason=<descriptive string>]
EndMessage

(Node -> Client)

Failed
[Reason=<descriptive string>]
EndMessage

Failed and FormatError will not be discussed in the remainder of this document. Clients should be prepared to handle a Failed at any time, and a FormatError as teh response to any client message. Either of these messages terminates the transaction and the connection.

Handshaking

This is totally optional for the client. Note that this counts as a transation and thus the connection is torn down afterwards.

(Client -> Node)

ClientHello
EndMessage

In response the node sends the following message:

(Node -> Client)

NodeHello
Protocol=<number: protocol version number.  Currently 1>
Node=<string: freeform: Description of the nodes>
EndMessage

Requesting

(Client -> Node)

ClientGet
URI=<string: fully specified URI, such as freenet:KSK@gpl.txt>
HopsToLive=<number: hops to live>
EndMessage

The client is now in the waiting state. The node may return one of the following messages:

  • URIError: Invalid Freenet URL. The transaction is terminated.
  • Restarted: The client should continue waiting.
  • DataNotFound: The transaction is terminated due to not being able to find data.
  • RouteNotFound: The transaction is terminated due to not being able to find a route.

Otherwise a DataFound message is returned:

(Node -> Client)

DataFound
DataLength=<number: number of bytes of metadata + data>
[MetadataLength=<number: default = 0, number of bytes of metadata>
EndMessage

After a DataFound message the data itself is sent in chunks:

(Node -> Client)

DataChunk
Length=<number: number of bytes in trailing field>
Data
<@Length bytes of data>

At any time when the full payload of data has not been sent a Restarted message may be sent. This means that the data to verify and the transfer will be restarted. The client should return to the waiting state, and if a DataFound is then received, the data transfer will start over from the beginning. Otherwise, when the final DataChunk is received, the transaction is complete and the connection dies.

Inserting

(Client->Node)

ClientPut
HopsToLive=<number: hops to live>
URI=<string: fully specified URI, such as freenet:KSK@gpl.txt>
DataLength=<number: number of bytes of metadata + data>
[MetadataLength=<number: default = 0, number of bytes of metadata>]
Data
<@DataLength number of bytes>

If the client is inserting a CHK or SVK, the URI may be abbreviated as just CHK@ or SVK@. In the former case, the node will calculate the CHK, and in the latter, the node will generate a new keypair. The node must get all of the trailing field before it can start the insert into Freenet. The node may reply with one of the following messages:

  • URIError: Invalid Freenet URL. The transaction is terminated.
  • Restarted: The client should continue waiting.
  • RouteNotFound: The transaction is terminated due to not being able to find a route.
  • KeyCollision: The transaction is terminated due to a document with the same key already existing in Freenet. This message contains a URI field with the Freenet URI of the document.
  • SizeError: The transaction is terminated due to the data being too large for the key type; all non-CHK keys have a limit of 32 kB of data.

During an insertion, multiple Pending messages may be returned. These messages signal that the data is being successfully inserted, but insertion is not complete, and the node has not received a StoreData message yet:

(Node -> Client)

Pending
URI=<string: fully specified URI, such as freenet:KSK@gpl.txt>
[PublicKey=<string: public key>]
[PrivateKey=<string: private key>]
EndMessage

When the node receives a StoreData message (and thus insertion is complete), a Success message is returned with the Freenet URI of the new document and possibly a private/public keypair, if the inserted document was an SVK. See the section on key generation about this.

(Node -> Client)

Success
URI=<string: fully specified URI, such as freenet:KSK@gpl.txt>
[PublicKey=<string: public key>]
[PrivateKey=<string: private key>]
EndMessage

Key generation

These messages allow a client to generate keys. This does not affect Freenet at all - the calculations are carried out at the node.

Key generation requests are done via a GenerateKey message. Either a CHK or an SVK keypair can be generated:

(Client -> Node)

GenerateCHK
DataLength=<number: number of bytes of data + metadata>
[MetadataLength=<nubmer: defaul = 0, number of bytes of metadata>]
Data
<@DataLength number of bytes>

The node calculates the CHK as it would do if inserting, but instead returns it. This completes the transaction:

(Node -> Client)

Success
URI=<string: fully specified URI, such as freenet:KSK@gpl.txt>
EndMessage

The format for generating SVKs is very similar but generates a pair of keys (public and private) which are independent of any data. This is generally used for setting up SSKs:

(Client -> Node)

GenerateSVKPair
EndMessage

The node generates a key pair and returns:

(Node -> Client)

Success
PublicKey=<string: public Freenet key>
PrivateKey=<string: private Freenet key>
EndMessage

The PublicKey and PrivateKey are returned as Freenet-base64 encoded strings. These can be used to construct URIs for requesting or inserting SSKs:

(insert)  freenet:SSK@<PrivateKey>/<name>
(request) freenet:SSK@<PublicKey>/<name>

Postscript

I (TravisBemann) originally transcribed this document from a converted to HTML version of an SGML document by Adam Langley which originally documented FCP, along with a few changes to document the introduction of the Pending message, and changing wording and formatting in some circumstances. Thus I will credit Adam Langley with the majority of the content in this. However, someome else (DeltaFourOhSeven) attempted to take credit for this by deleting my signature and date stamp and replacing it with his or her own (without making any other significant modifications or additions, and if he or she did he or she should have just put his or her signature and date stamp by his or her modifications). I personally regard this as a major breach of etiquette. To the best of my knowledge this person is not Adam Langley, so I am removing this person's signature and date stamp from its position and just leaving it below mine for the reader to read.

-- TravisBemann - 05 Jan 2002, 07 Jan 2002

This person attempted to take credit for putting this on freenetproject.org, dishonestly:

-- DeltaFourOhSeven - 06 Jan 2002