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.
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.
By default FCP is port 8481. but any FCP client should just use this as a default, rather than as a fixed value (because at some time in the future this could change or some user could change Freenet on their own machine to use a different port).
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
This is the complete set of client to node messages, with the possible node to client responses (only the headers are listed).
-
ClientGet
-
URIError
-
Restarted
-
DataNotFound
-
RouteNotFound
-
DataFound
-
ClientPut
-
URIError
-
Restarted
-
RouteNotFound
-
KeyCollision
-
Pending
-
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:
FormatError
[Reason=<descriptive string>]
EndMessage
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.
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
(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:
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:
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.
(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:
Pending
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.
Success
URI=<string: fully specified URI, such as freenet:KSK@gpl.txt>
[PublicKey=<string: public key>]
[PrivateKey=<string: private key>]
EndMessage
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:
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:
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:
GenerateSVKPair
EndMessage
The node generates a key pair and returns:
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>
-- TravisBemann - 05 Jan 2002
|