[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [gnunet-texinfo] branch master updated (6abc704 -> a42c8a3)
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] [gnunet-texinfo] branch master updated (6abc704 -> a42c8a3) |
|
Date: |
Wed, 24 May 2017 23:50:00 +0200 |
This is an automated email from the git hooks/post-receive script.
ng0 pushed a change to branch master
in repository gnunet-texinfo.
from 6abc704 switch from texi2* to makeinfo. Almost bikeshed painting.
new 3a1e4b6 some more warnings eliminated from developer.texi
new a42c8a3 almost all warnings eliminated. Only a few left
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
developer.texi | 926 +++++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 766 insertions(+), 160 deletions(-)
diff --git a/developer.texi b/developer.texi
index 13a1eba..07c4234 100644
--- a/developer.texi
+++ b/developer.texi
@@ -42,9 +42,136 @@ these restrictions on your account. We're sorry for this
inconvenience;
however, few people would want to read this site if 99% of it was
advertisements for bogus websites.
+
+
@c ***************************************************************************
address@hidden DevelperIntroduction
address@hidden DeveloperIntroduction
+
+
+
+
+
+
+
+
address@hidden
+* Developer Introduction::
+* Code overview::
+* System Architecture::
+* Subsystem stability::
+* Naming conventions and coding style guide::
+* Build-system::
+* Developing extensions for GNUnet using the gnunet-ext template::
+* Writing testcases::
+* GNUnet's TESTING library::
+* API::
+* Finer control over peer stop::
+* Helper functions::
+* Testing with multiple processes::
+* Performance regression analysis with Gauger::
+* GNUnet's TESTBED Subsystem::
+* libgnunetutil::
+* Logging::
+* Interprocess communication API (IPC)::
+* Cryptography API::
+* Message Queue API::
+* Service API::
+* Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps::
+* The CONTAINER_MDLL API::
+* The Automatic Restart Manager (ARM)::
+* Basic functionality::
+* Key configuration options::
+* Availability2::
+* Reliability::
+* GNUnet's TRANSPORT Subsystem::
+* Address validation protocol::
+* NAT library::
+* Distance-Vector plugin::
+* SMTP plugin::
+* Bluetooth plugin::
+* WLAN plugin::
+* The ATS Subsystem::
+* GNUnet's CORE Subsystem::
+* Limitations::
+* When is a peer "connected"?::
+* libgnunetcore::
+* The CORE Client-Service Protocol::
+* The CORE Peer-to-Peer Protocol::
+* GNUnet's CADET subsystem::
+* libgnunetcadet::
+* GNUnet's NSE subsystem::
+* libgnunetnse::
+* The NSE Client-Service Protocol::
+* The NSE Peer-to-Peer Protocol::
+* GNUnet's HOSTLIST subsystem::
+* HELLOs::
+* Overview for the HOSTLIST subsystem::
+* Interacting with the HOSTLIST daemon::
+* Hostlist security address validation::
+* The HOSTLIST daemon::
+* The HOSTLIST server::
+* The HOSTLIST client::
+* Usage::
+* GNUnet's IDENTITY subsystem::
+* libgnunetidentity::
+* The IDENTITY Client-Service Protocol::
+* GNUnet's NAMESTORE Subsystem::
+* libgnunetnamestore::
+* GNUnet's PEERINFO subsystem::
+* Features2::
+* Limitations3::
+* DeveloperPeer Information::
+* Startup::
+* Managing Information::
+* Obtaining Information::
+* The PEERINFO Client-Service Protocol::
+* libgnunetpeerinfo::
+* GNUnet's PEERSTORE subsystem::
+* Functionality::
+* Architecture::
+* libgnunetpeerstore::
+* GNUnet's SET Subsystem::
+* Local Sets::
+* Set Modifications::
+* Set Operations::
+* Result Elements::
+* libgnunetset::
+* The SET Client-Service Protocol::
+* The SET-Intersection Peer-to-Peer Protocol::
+* The SET-Union Peer-to-Peer Protocol::
+* GNUnet's STATISTICS subsystem::
+* libgnunetstatistics::
+* The STATISTICS Client-Service Protocol::
+* GNUnet's Distributed Hash Table (DHT)::
+* Block library and plugins::
+* libgnunetdht::
+* The DHT Client-Service Protocol::
+* The DHT Peer-to-Peer Protocol::
+* The GNU Name System (GNS)::
+* libgnunetgns::
+* libgnunetgnsrecord::
+* GNS plugins::
+* The GNS Client-Service Protocol::
+* Hijacking the DNS-Traffic using gnunet-service-dns::
+* Serving DNS lookups via GNS on W32::
+* The GNS Namecache::
+* libgnunetnamecache::
+* The NAMECACHE Client-Service Protocol::
+* The NAMECACHE Plugin API::
+* The REVOCATION Subsystem::
+* Dissemination::
+* Revocation Message Design Requirements::
+* libgnunetrevocation::
+* The REVOCATION Client-Service Protocol::
+* The REVOCATION Peer-to-Peer Protocol::
+* GNUnet's File-sharing (FS) Subsystem::
+* Encoding for Censorship-Resistant Sharing (ECRS)::
+* File-sharing persistence directory structure::
+* GNUnet's REGEX Subsystem::
+* How to run the regex profiler::
address@hidden menu
+
address@hidden Developer Introduction
address@hidden Developer Introduction
This developer handbook is intended as first introduction to GNUnet for new
developers that want to extend the GNUnet framework. After the introduction,
@@ -100,9 +227,15 @@ Automatically generated, current reports on the test suite
are here.
Current reports on test coverage are here.
@end itemize
+
+
@c ***************************************************************************
address@hidden
+* Project overview::
address@hidden menu
+
@node Project overview
address@hidden Project overview
address@hidden Project overview
The GNUnet project consists at this point of several sub-projects. This section
is supposed to give an initial overview about the various sub-projects. Note
@@ -477,11 +610,31 @@ This subsystem does not have an
API/IPC-protocol/P2P-protocol
Here you can find some rules to help you write code for GNUnet.
+
+
@c ***************************************************************************
address@hidden
+* Naming conventions::
+* Coding style::
address@hidden menu
+
@node Naming conventions
@subsection Naming conventions
+
@c ***************************************************************************
address@hidden
+* include files::
+* binaries::
+* logging::
+* configuration::
+* exported symbols::
+* private (library-internal) symbols (including structs and macros)::
+* testcases::
+* performance tests::
+* src/ directories::
address@hidden menu
+
@node include files
@subsubsection include files
@@ -808,7 +961,7 @@ and run @code{ldconfig} or your add it to the environmental
variable
@c ***************************************************************************
@node Writing testcases
address@hidden Writing testcases
address@hidden Writing testcases
Ideally, any non-trivial GNUnet code should be covered by automated testcases.
Testcases should reside in the same place as the code that is being tested. The
@@ -1151,7 +1304,18 @@ use this path to start helper binaries both locally and
remotely.
Testbed API can accessed by including "gnunet_testbed_service.h" file and
linking with -lgnunettestbed.
+
+
@c ***************************************************************************
address@hidden
+* Supported Topologies::
+* Hosts file format::
+* Topology file format::
+* Testbed Barriers::
+* Automatic large-scale deployment of GNUnet in the PlanetLab testbed::
+* TESTBED Caveats::
address@hidden menu
+
@node Supported Topologies
@subsection Supported Topologies
@@ -1328,7 +1492,12 @@ uninitialised barrier results in failure.
@code{GNUNET_TESTBED_barrier_wait_cancel()} cancels the notification registered
by @code{GNUNET_TESTBED_barrier_wait()}.
+
@c ***************************************************************************
address@hidden
+* Implementation::
address@hidden menu
+
@node Implementation
@subsubsection Implementation
@@ -1409,7 +1578,15 @@ Please also check
@uref{https://gnunet.org/installation-fedora8-svn} and@
@uref{https://gnunet.org/installation-fedora12-svn} to find detailled
instructions how to install GNUnet on a PlanetLab node.
+
@c ***************************************************************************
address@hidden
+* PlanetLab Automation for Fedora8 nodes::
+* Install buildslave on PlanetLab nodes running fedora core 8::
+* Setup a new PlanetLab testbed using GPLMT::
+* Why do i get an ssh error when using the regex profiler?::
address@hidden menu
+
@node PlanetLab Automation for Fedora8 nodes
@subsubsection PlanetLab Automation for Fedora8 nodes
@@ -1517,7 +1694,13 @@ login, then you should be good to go.
This section documents a few caveats when using the GNUnet testbed
subsystem.
+
@c ***************************************************************************
address@hidden
+* CORE must be started::
+* ATS must want the connections::
address@hidden menu
+
@node CORE must be started
@subsubsection CORE must be started
@@ -1548,8 +1731,8 @@ largely arises for dense overlay topologies, especially
if you try to create
cliques with more than 20 peers.
@c ***************************************************************************
address@hidden libgnunetutil
@node libgnunetutil
address@hidden libgnunetutil
libgnunetutil is the fundamental library that all GNUnet code builds upon.
Ideally, this library should contain most of the platform dependent code
@@ -1747,7 +1930,13 @@ At the moment GNUnet will stop processing a log
definition when it encounters
an error in definition formatting or an error in regular expression syntax, and
will not report the failure in any way.
+
@c ***************************************************************************
address@hidden
+* Examples::
+* Log files::
address@hidden menu
+
@node Examples
@subsection Examples
@@ -1792,6 +1981,7 @@ definition, as opposed to earlier examples, which use the
shell).@ Another
limitation, on Windows, GNUNET_FORCE_LOGFILE @strong{MUST} be set in order to
GNUNET_FORCE_LOG to work.
+
@c ***************************************************************************
@node Log files
@subsection Log files
@@ -1829,7 +2019,12 @@ kept for 4 years and the logs from the first year would
be deleted once year 5
begins. If you do not use any date-related string format codes, logs would
never be automatically deleted by GNUnet.
+
@c ***************************************************************************
address@hidden
+* Updated behavior of GNUNET_log::
address@hidden menu
+
@node Updated behavior of GNUNET_log
@subsubsection Updated behavior of GNUNET_log
@@ -1910,7 +2105,15 @@ service and client.@ (Here, a client uses the
@code{struct
AddressLookupMessage} as a request to ask the server to return the address of
any other peer connecting to the service.)
+
@c ***************************************************************************
address@hidden
+* Define new message types::
+* Define message struct::
+* Connection between client and server::
+* Server Setting::
address@hidden menu
+
@node Define new message types
@subsection Define new message types
@@ -1952,7 +2155,16 @@ both ensure correct alignment when sending structs over
the network
For typical communication, the connection should be created first, in other
words, a connection between the client and the service should be
established.
+
+
@c ***************************************************************************
address@hidden
+* Client setting::
+* Establish connection::
+* Initialize request message::
+* Send request and receive response::
address@hidden menu
+
@node Client setting
@subsubsection Client setting
@c %**end of header
@@ -2019,7 +2231,17 @@ message from the service.
@node Server Setting
@subsection Server Setting
+
@c ***************************************************************************
address@hidden
+* Startup service::
+* Add new handles for specified messages::
+* Process request message::
+* Response to client::
+* Notification of clients::
+* Conversion between Network Byte Order (Big Endian) and Host Byte Order::
address@hidden menu
+
@node Startup service
@subsubsection Startup service
@@ -2457,7 +2679,16 @@ sometimes responsible for a large share of GNUnet's
overall memory consumption
API quirks (and their implications for applications) that were recently
introduced to minimize the footprint of the hash map.
+
@c ***************************************************************************
address@hidden
+* Analysis::
+* Solution::
+* Migration::
+* Conclusion::
+* Availability::
address@hidden menu
+
@node Analysis
@subsection Analysis
@c %**end of header
@@ -2641,7 +2872,7 @@ accessing the "next_XX" and/or "prev_XX" members.
@c ***************************************************************************
@node The Automatic Restart Manager (ARM)
address@hidden The Automatic Restart Manager (ARM)
address@hidden The Automatic Restart Manager (ARM)
@c %**end of header
GNUnet's Automated Restart Manager (ARM) is the GNUnet service responsible for
@@ -2830,7 +3061,7 @@ trying to restart a problematic service.
@c ***************************************************************************
@node GNUnet's TRANSPORT Subsystem
address@hidden GNUnet's TRANSPORT Subsystem
address@hidden GNUnet's TRANSPORT Subsystem
@c %**end of header
This chapter documents how the GNUnet transport subsystem works. The GNUnet
@@ -3056,6 +3287,15 @@ performance results presented are quite old and maybe
outdated at this point.
@item Is there any additional documentation?
@end itemize
+
address@hidden
+* Why use SMTP for a peer-to-peer transport?::
+* How does it work?::
+* How do I configure my peer?::
+* How do I test if it works?::
+* How fast is it?::
address@hidden menu
+
@node Why use SMTP for a peer-to-peer transport?
@subsection Why use SMTP for a peer-to-peer transport?
@c %**end of header
@@ -3238,6 +3478,17 @@ have any questions or problems just post them here or
ask on the IRC channel.
@item How can I test it?
@end itemize
+
+
address@hidden
+* What do I need to use the Bluetooth plugin transport?::
+* How does it work2?::
+* What possible errors should I be aware of?::
+* How do I configure my peer2?::
+* How can I test it?::
+* The implementation of the Bluetooth transport plugin::
address@hidden menu
+
@node What do I need to use the Bluetooth plugin transport?
@subsection What do I need to use the Bluetooth plugin transport?
@c %**end of header
@@ -3421,6 +3672,17 @@ platforms.
@item Pending Features
@end itemize
+
+
address@hidden
+* Linux functionality::
+* THE INITIALIZATION::
+* THE LOOP::
+* Details about the broadcast implementation::
+* Windows functionality::
+* Pending features::
address@hidden menu
+
@node Linux functionality
@subsubsection Linux functionality
@c %**end of header
@@ -3635,7 +3897,7 @@ This section documents how the wlan transport plugin
works. Parts which are not
implemented yet or could be better implemented are described at the end.
@node The ATS Subsystem
address@hidden The ATS Subsystem
address@hidden The ATS Subsystem
@c %**end of header
ATS stands for "automatic transport selection", and the function of ATS in
@@ -3656,7 +3918,7 @@ strategies which differ significantly in their
performance and maturity, and it
is still unclear if any particular plugin is generally superior.
@node GNUnet's CORE Subsystem
address@hidden GNUnet's CORE Subsystem
address@hidden GNUnet's CORE Subsystem
@c %**end of header
The CORE subsystem in GNUnet is responsible for securing link-layer
@@ -3813,6 +4075,13 @@ re-established, the applications will be receive
matching connect events.
This section describes the protocol between an application using the CORE
service (the client) and the CORE service process itself.
+
address@hidden
+* Setup2::
+* Notifications::
+* Sending::
address@hidden menu
+
@node Setup2
@subsection Setup2
@c %**end of header
@@ -3882,6 +4151,14 @@ for each request).
@section The CORE Peer-to-Peer Protocol
@c %**end of header
+
address@hidden
+* Creating the EphemeralKeyMessage::
+* Establishing a connection::
+* Encryption and Decryption::
+* Type maps::
address@hidden menu
+
@node Creating the EphemeralKeyMessage
@subsection Creating the EphemeralKeyMessage
@c %**end of header
@@ -3999,7 +4276,7 @@ the correct hash of the type map) is not received, the
sender will retransmit
the type map (with exponential back-off).
@node GNUnet's CADET subsystem
address@hidden GNUnet's CADET subsystem
address@hidden GNUnet's CADET subsystem
The CADET subsystem in GNUnet is responsible for secure end-to-end
communications between nodes in the GNUnet overlay network. CADET builds on the
@@ -4036,8 +4313,9 @@ the sender to send more traffic than the receiver or the
network are able to
process.
@end itemize
address@hidden libgnunetcadet
@node libgnunetcadet
address@hidden libgnunetcadet
+
The CADET API (defined in gnunet_cadet_service.h) is the messaging API used by
P2P applications built using GNUnet. It provides applications the ability to
@@ -4112,8 +4390,9 @@ Finally, when an application no longer wants to use
CADET, it should call
@code{GNUNET_CADET_disconnect}, but first all channels and pending
transmissions must be closed (otherwise CADET will complain).
address@hidden GNUnet's NSE subsystem
@node GNUnet's NSE subsystem
address@hidden GNUnet's NSE subsystem
+
NSE stands for Network Size Estimation. The NSE subsystem provides other
subsystems and users with a rough estimate of the number of peers currently
@@ -4126,8 +4405,16 @@ of [2/3 estimate, 3/2 estimate]. We will now give an
overview of the algorithm
used to calcualte the estimate; all of the details can be found in this
technical report.
address@hidden Motivation
+
+
address@hidden
+* Motivation::
+* Principle::
address@hidden menu
+
@node Motivation
address@hidden Motivation
+
Some subsytems, like DHT, need to know the size of the GNUnet network to
optimize some parameters of their own protocol. The decentralized nature of
@@ -4138,8 +4425,15 @@ protocols may allow any malicious peer to manipulate the
final result or to
take advantage of the system to perform DoS (Denial of Service) attacks against
the network. GNUnet's NSE protocol avoids these drawbacks.
address@hidden Security
+
+
address@hidden
+* Security::
address@hidden menu
+
@node Security
address@hidden Security
+
The NSE subsystem is designed to be resilient against these attacks. It uses
@uref{http://en.wikipedia.org/wiki/Proof-of-work_system, proofs of work} to
@@ -4150,8 +4444,9 @@ calculated periodically and out-of-time traffic is either
ignored or stored for
later retransmission by benign peers. In particular, peers cannot trigger
global network communication at will.
address@hidden Principle
@node Principle
address@hidden Principle
+
The algorithm calculates the estimate by finding the globally closest peer ID
to a random, time-based value.
@@ -4159,8 +4454,20 @@ to a random, time-based value.
The idea is that the closer the ID is to the random value, the more "densely
packed" the ID space is, and therefore, more peers are in the network.
address@hidden Example
+
+
address@hidden
+* Example::
+* Algorithm::
+* Target value::
+* Timing::
+* Controlled Flooding::
+* Calculating the estimate::
address@hidden menu
+
@node Example
address@hidden Example
+
Suppose all peers have IDs between 0 and 100 (our ID space), and the random
value is 42. If the closest peer has the ID 70 we can imagine that the average
@@ -4171,15 +4478,17 @@ them. Naturally, we could have been rather unlucky, and
there is only one peer
and happens to have the ID 44. Thus, the current estimate is calculated as the
average over multiple rounds, and not just a single sample.
address@hidden Algorithm
@node Algorithm
address@hidden Algorithm
+
Given that example, one can imagine that the job of the subsystem is to
efficiently communicate the ID of the closest peer to the target value to all
the other peers, who will calculate the estimate from it.
address@hidden Target value
@node Target value
address@hidden Target value
+
@c %**end of header
The target value itself is generated by hashing the current time, rounded down
@@ -4188,8 +4497,8 @@ to an agreed value. If the rounding amount is 1h
(default) and the time is
rouning amount (in this example would be every hour). Every repetition is
called a round.
address@hidden Timing
@node Timing
address@hidden Timing
@c %**end of header
The NSE subsystem has some timing control to avoid everybody broadcasting its
@@ -4203,8 +4512,9 @@ the middle of the round. If its bigger it will be earlier
and if its smaler
(the most likely case) it will be later. This ensures that the peers closests
to the target value start broadcasting their ID the first.
address@hidden Controlled Flooding
@node Controlled Flooding
address@hidden Controlled Flooding
+
@c %**end of header
When a peer receives a value, first it verifies that it is closer than the
@@ -4220,8 +4530,9 @@ values, since a better value can come before the
broadcast time, rendering the
previous one obsolete and saving the traffic that would have been used to
broadcast it to the neighbors.
address@hidden Calculating the estimate
@node Calculating the estimate
address@hidden Calculating the estimate
+
@c %**end of header
Once the closest ID has been spread across the network each peer gets the exact
@@ -4236,8 +4547,9 @@ size could be half of the estimate or twice as much).
Note that the actual
network size is calculated in powers of two of the raw input, thus one bit of
uncertainty means a factor of two in the size estimate.
address@hidden libgnunetnse
@node libgnunetnse
address@hidden libgnunetnse
+
@c %**end of header
The NSE subsystem has the simplest API of all services, with only two calls:
@@ -4253,8 +4565,16 @@ the first. The default round time is set to 1 hour.
The disconnect call disconnects from the NSE subsystem and the callback is no
longer called with new estimates.
address@hidden Results
+
+
address@hidden
+* Results::
+* Examples2::
address@hidden menu
+
@node Results
address@hidden Results
+
@c %**end of header
The callback provides two values: the average and the
@@ -4289,8 +4609,9 @@ standard deviation value, not only the average (in
particular, if the standard
veriation is very high, the average maybe meaningless: the network size is
changing rapidly).
address@hidden Examples2
@node Examples2
address@hidden Examples2
+
@c %**end of header
Let's close with a couple examples.
@@ -4315,8 +4636,9 @@ To put this in perspective, if someone remembers the LHC
Higgs boson results,
were announced with "5 sigma" and "6 sigma" certainties. In this case a 5 sigma
minimum would be 2 million and a 6 sigma minimum, 1.8 million.
address@hidden The NSE Client-Service Protocol
@node The NSE Client-Service Protocol
address@hidden The NSE Client-Service Protocol
+
@c %**end of header
As with the API, the client-service protocol is very simple, only has 2
@@ -4334,8 +4656,9 @@ respective round.
When the @code{GNUNET_NSE_disconnect} API call is executed, the client simply
disconnects from the service, with no message involved.
address@hidden The NSE Peer-to-Peer Protocol
@node The NSE Peer-to-Peer Protocol
address@hidden The NSE Peer-to-Peer Protocol
+
@c %**end of header
The NSE subsystem only has one message in the P2P protocol, the
@@ -4386,8 +4709,9 @@ Finally, when it comes to send the stored message for the
current round to the
neighbors there is a random delay added for each neighbor, to avoid traffic
spikes and minimize cross-messages.
address@hidden GNUnet's HOSTLIST subsystem
@node GNUnet's HOSTLIST subsystem
address@hidden GNUnet's HOSTLIST subsystem
+
@c %**end of header
Peers in the GNUnet overlay network need address information so that they can
@@ -4412,8 +4736,9 @@ outdated set of HELLO messages from the distribution. In
this case, getting new
peers to connect to the network requires either manual effort or the use of a
HOSTLIST to obtain HELLOs.
address@hidden HELLOs
@node HELLOs
address@hidden HELLOs
+
@c %**end of header
The basic information peers require to connect to other peers are contained in
@@ -4422,8 +4747,9 @@ identity of the peer (based on the cryptographic public
key) a HELLO message
may contain address information that specifies ways to contact a peer. By
obtaining HELLO messages, a peer can learn how to contact other peers.
address@hidden Overview for the HOSTLIST subsystem
@node Overview for the HOSTLIST subsystem
address@hidden Overview for the HOSTLIST subsystem
+
@c %**end of header
The HOSTLIST subsystem provides a way to distribute and obtain contact
@@ -4439,8 +4765,15 @@ hostlist format is a binary blob containing a sequence
of HELLO messages. Note
that any HTTP server can theoretically serve a hostlist, the build-in hostlist
server makes it simply convenient to offer this service.
address@hidden Features
+
address@hidden
+* Features::
+* Limitations2::
address@hidden menu
+
@node Features
address@hidden Features
+
@c %**end of header
The HOSTLIST daemon can:
@@ -4455,8 +4788,9 @@ gossip
@item automatically learn about hostlist servers from the gossip of other peers
@end itemize
address@hidden Limitations2
@node Limitations2
address@hidden Limitations2
+
@c %**end of header
The HOSTLIST daemon does not:
@@ -4466,8 +4800,9 @@ The HOSTLIST daemon does not:
@item verify the address information in the HELLO messages
@end itemize
address@hidden Interacting with the HOSTLIST daemon
@node Interacting with the HOSTLIST daemon
address@hidden Interacting with the HOSTLIST daemon
+
@c %**end of header
The HOSTLIST subsystem is currently implemented as a daemon, so there is no
@@ -4490,8 +4825,9 @@ shutdown if changes to this value are to have any effect
on the daemon (as
HOSTLIST does not monitor STATISTICS for changes to the download
frequency).
address@hidden Hostlist security: address validation
address@hidden Hostlist security: address validation
address@hidden Hostlist security address validation
address@hidden Hostlist security address validation
+
@c %**end of header
Since information obtained from other parties cannot be trusted without
@@ -4508,8 +4844,9 @@ HOSTLIST servers specified in the configuration,
downloads the (unvalidated)
list of HELLO messages and forwards these information to the TRANSPORT server
to validate the addresses.
address@hidden The HOSTLIST daemon
@node The HOSTLIST daemon
address@hidden The HOSTLIST daemon
+
@c %**end of header
The hostlist daemon is the main component of the HOSTLIST subsystem. It is
@@ -4535,8 +4872,9 @@ events.
To clean up on shutdown, the daemon has a cleaning task, shutting down all
subsystems and disconnecting from CORE.
address@hidden The HOSTLIST server
@node The HOSTLIST server
address@hidden The HOSTLIST server
+
@c %**end of header
The server provides a way for other peers to obtain HELLOs. Basically it is a
@@ -4544,8 +4882,15 @@ small web server other peers can connect to and download
a list of HELLOs using
standard HTTP; it may also advertise the URL of the hostlist to other peers
connecting on CORE level.
address@hidden The HTTP Server
+
address@hidden
+* The HTTP Server::
+* Advertising the URL::
address@hidden menu
+
@node The HTTP Server
address@hidden The HTTP Server
+
@c %**end of header
During startup, the server starts a web server listening on the port specified
@@ -4567,8 +4912,9 @@ as a HTTP response and the the server will terminate the
connection with the
result code HTTP 200 OK. The connection will be closed immediately if no
hostlist is available.
address@hidden Advertising the URL
@node Advertising the URL
address@hidden Advertising the URL
+
@c %**end of header
The server also advertises the URL to download the hostlist to other peers if
@@ -4576,8 +4922,9 @@ hostlist advertisement is enabled. When a new peer
connects and has hostlist
learning enabled, the server sends a GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT
message to this peer using the CORE service.
address@hidden The HOSTLIST client
@node The HOSTLIST client
address@hidden The HOSTLIST client
+
@c %**end of header
The client provides the functionality to download the list of HELLOs from a set
@@ -4589,8 +4936,15 @@ validation.
The client supports two modes of operation: download of HELLOs (bootstrapping)
and learning of URLs.
address@hidden Bootstrapping
+
address@hidden
+* Bootstrapping::
+* Learning::
address@hidden menu
+
@node Bootstrapping
address@hidden Bootstrapping
+
@c %**end of header
For bootstrapping, it schedules a task to download the hostlist from the set of
@@ -4611,8 +4965,9 @@ full HELLO was downloaded, the HOSTLIST client offers
this HELLO message to the
TRANSPORT service for validation. When the download is finished or failed,
statistical information about the quality of this URL is updated.
address@hidden Learning
@node Learning
address@hidden Learning
+
@c %**end of header
The client also manages hostlist advertisements from other peers. The HOSTLIST
@@ -4627,8 +4982,9 @@ through successful downloads and number of HELLOs e.g.)
is discarded. During
shutdown the list of URLs is saved to a file for persistance and loaded on
startup. URLs from the configuration file are never discarded.
address@hidden Usage
@node Usage
address@hidden Usage
+
@c %**end of header
To start HOSTLIST by default, it has to be added to the DEFAULTSERVICES section
@@ -4638,8 +4994,9 @@ For more information on how to configure the HOSTLIST
subsystem see the
installation handbook:@ Configuring the hostlist to bootstrap@ Configuring your
peer to provide a hostlist
address@hidden GNUnet's IDENTITY subsystem
@node GNUnet's IDENTITY subsystem
address@hidden GNUnet's IDENTITY subsystem
+
@c %**end of header
Identities of "users" in GNUnet are called egos. Egos can be used as pseudonyms
@@ -4681,12 +5038,22 @@ fixed and known to everyone. Thus, anyone can perform
actions as anonymous.
This can be useful as with this trick, code does not have to contain a special
case to distinguish between anonymous and pseudonymous egos.
address@hidden libgnunetidentity
@node libgnunetidentity
address@hidden libgnunetidentity
@c %**end of header
address@hidden Connecting to the service
+
address@hidden
+* Connecting to the service::
+* Operations on Egos::
+* The anonymous Ego::
+* Convenience API to lookup a single ego::
+* Associating egos with service functions::
address@hidden menu
+
@node Connecting to the service
address@hidden Connecting to the service
+
@c %**end of header
First, typical clients connect to the identity service using
@@ -4718,8 +5085,9 @@ The ego handle passed to the callback remains valid until
the callback is
invoked with a name of NULL, so it is safe to store a reference to the ego's
handle.
address@hidden Operations on Egos
@node Operations on Egos
address@hidden Operations on Egos
+
@c %**end of header
Given an ego handle, the main operations are to get its associated private key
@@ -4739,8 +5107,9 @@ respective continuations would be called. It is not
guaranteed that the
operation will not be completed anyway, only the continuation will no longer be
called.
address@hidden The anonymous Ego
@node The anonymous Ego
address@hidden The anonymous Ego
+
@c %**end of header
A special way to obtain an ego handle is to call
@@ -4751,8 +5120,9 @@ signatures (for example, to avoid a special path in the
code). The anonymous
ego is always valid and accessing it does not require a connection to the
identity service.
address@hidden Convenience API to lookup a single ego
@node Convenience API to lookup a single ego
address@hidden Convenience API to lookup a single ego
+
As applications commonly simply have to lookup a single ego, there is a
convenience API to do just that. Use @code{GNUNET_IDENTITY_ego_lookup} to
@@ -4762,16 +5132,18 @@ will only be valid during that callback. The operation
can be cancelled via
@code{GNUNET_IDENTITY_ego_lookup_cancel} (cancellation is only legal before the
callback is invoked).
address@hidden Associating egos with service functions
@node Associating egos with service functions
address@hidden Associating egos with service functions
+
The @code{GNUNET_IDENTITY_set} function is used to associate a particular ego
with a service function. The name used by the service and the ego are given as
arguments. Afterwards, the service can use its name to lookup the associated
ego using @code{GNUNET_IDENTITY_get}.
address@hidden The IDENTITY Client-Service Protocol
@node The IDENTITY Client-Service Protocol
address@hidden The IDENTITY Client-Service Protocol
+
@c %**end of header
A client connecting to the identity service first sends a message with type
@@ -4797,8 +5169,9 @@ message, which includes the name of the service function.
The identity service
will respond to a GET_DEFAULT request with a SET_DEFAULT message containing the
respective information, or with a RESULT_CODE to indicate an error.
address@hidden GNUnet's NAMESTORE Subsystem
@node GNUnet's NAMESTORE Subsystem
address@hidden GNUnet's NAMESTORE Subsystem
+
@c %**end of header
The NAMESTORE subsystem provides persistent storage for local GNS zone
@@ -4824,8 +5197,9 @@ a specific or all zones and to monitor zones for changes.
NAMESTORE
functionality can be accessed using the NAMESTORE api or the NAMESTORE command
line tool.
address@hidden libgnunetnamestore
@node libgnunetnamestore
address@hidden libgnunetnamestore
+
@c %**end of header
To interact with NAMESTORE clients first connect to the NAMESTORE service using
@@ -4841,8 +5215,16 @@ private keys can be obtained from the IDENTITY subsytem.
Here @address@hidden
can be used to refer to zones or the default ego assigned to the GNS subsystem
can be used to obtained the master zone's private key.}}
address@hidden Editing Zone Information
+
address@hidden
+* Editing Zone Information::
+* Iterating Zone Information::
+* Monitoring Zone Information::
address@hidden menu
+
@node Editing Zone Information
address@hidden Editing Zone Information
+
@c %**end of header
NAMESTORE provides functions to lookup records stored under a label in a zone
@@ -4876,8 +5258,9 @@ and records stored in a zone. Here the client uses the
zone, the nickname as string plus a the callback with the result of the
operation.
address@hidden Iterating Zone Information
@node Iterating Zone Information
address@hidden Iterating Zone Information
+
@c %**end of header
A client can iterate over all information in a zone or all zones managed by
@@ -4893,8 +5276,9 @@ NAMESTORE calls the callback for every result and expects
the client to call@
NAMESTORE reached the last item it will call the callback with a NULL value to
indicate.
address@hidden Monitoring Zone Information
@node Monitoring Zone Information
address@hidden Monitoring Zone Information
+
@c %**end of header
Clients can also monitor zones to be notified about changes. Here the clients
@@ -4910,8 +5294,9 @@ zone, the label and the records and their number.
To stop monitoring, the client call @code{GNUNET_NAMESTORE_zone_monitor_stop}
and passes the handle obtained from the function to start the monitoring.
address@hidden GNUnet's PEERINFO subsystem
@node GNUnet's PEERINFO subsystem
address@hidden GNUnet's PEERINFO subsystem
+
@c %**end of header
The PEERINFO subsystem is used to store verified (validated) information about
@@ -4929,8 +5314,9 @@ subsystems tend to need to store per-peer information in
persistent way. To not
duplicate this functionality we plan to provide a PEERSTORE service providing
this functionality
address@hidden Features2
@node Features2
address@hidden Features2
+
@c %**end of header
@itemize @bullet
@@ -4940,15 +5326,17 @@ this functionality
@item Differentiation between public and friend-only HELLO
@end itemize
address@hidden Limitations3
@node Limitations3
address@hidden Limitations3
+
@itemize @bullet
@item Does not perform HELLO validation
@end itemize
address@hidden DeveloperPeer Information
@node DeveloperPeer Information
address@hidden DeveloperPeer Information
+
@c %**end of header
The PEERINFO subsystem stores these information in the form of HELLO messages
@@ -4975,8 +5363,9 @@ purposes. Clients are for example the HOSTLIST component
providing these
information to other peers in form of a hostlist or the TRANSPORT subsystem
using these information to maintain connections to other peers.
address@hidden Startup
@node Startup
address@hidden Startup
+
@c %**end of header
During startup the PEERINFO services loads persistent HELLOs from disk. First
@@ -4989,8 +5378,9 @@ the distribution. The use of these HELLOs can be
prevented by setting the
@code{USE_INCLUDED_HELLOS} in the @code{PEERINFO} configuration section to
@code{NO}. Files containing invalid information are removed.
address@hidden Managing Information
@node Managing Information
address@hidden Managing Information
+
@c %**end of header
The PEERINFO services stores information about known PEERS and a single HELLO
@@ -5008,8 +5398,9 @@ it finds. Expired TRANSPORT addresses are removed from
the HELLO and if the
HELLO does not contain any valid addresses, it is discarded and removed from
disk.
address@hidden Obtaining Information
@node Obtaining Information
address@hidden Obtaining Information
+
@c %**end of header
When a client requests information from PEERINFO, PEERINFO performs a lookup
@@ -5023,8 +5414,9 @@ list of clients interested in this notifications. Such a
notification occurs if
a HELLO for a peer was updated (due to a merge for example) or a new peer was
added.
address@hidden The PEERINFO Client-Service Protocol
@node The PEERINFO Client-Service Protocol
address@hidden The PEERINFO Client-Service Protocol
+
@c %**end of header
To connect and disconnect to and from the PEERINFO Service PEERINFO utilizes
@@ -5052,16 +5444,25 @@ message is @code{struct GNUNET_MessageHeader} with type
@code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO}. If the client receives this message,
he can proceed with the next request if any is pending
address@hidden libgnunetpeerinfo
@node libgnunetpeerinfo
address@hidden libgnunetpeerinfo
+
@c %**end of header
The PEERINFO API consists mainly of three different functionalities:
maintaining a connection to the service, adding new information and retrieving
information form the PEERINFO service.
address@hidden Connecting to the Service
+
address@hidden
+* Connecting to the Service::
+* Adding Information::
+* Obtaining Information2::
address@hidden menu
+
@node Connecting to the Service
address@hidden Connecting to the Service
+
@c %**end of header
To connect to the PEERINFO service the function @code{GNUNET_PEERINFO_connect}
@@ -5069,8 +5470,9 @@ is used, taking a configuration handle as an argument,
and to disconnect from
PEERINFO the function @code{GNUNET_PEERINFO_disconnect}, taking the PEERINFO
handle returned from the connect function has to be called.
address@hidden Adding Information
@node Adding Information
address@hidden Adding Information
+
@c %**end of header
@code{GNUNET_PEERINFO_add_peer} adds a new peer to the PEERINFO subsystem
@@ -5082,8 +5484,9 @@ operation allowing to cancel the operation with the
respective cancel function
you can iterate over all information stored with PEERINFO or you can tell
PEERINFO to notify if new peer information are available.
address@hidden Obtaining Information2
@node Obtaining Information2
address@hidden Obtaining Information2
+
@c %**end of header
To iterate over information in PEERINFO you use @code{GNUNET_PEERINFO_iterate}.
@@ -5102,8 +5505,9 @@ will notify you about every change and the callback
function will be called to
notify you about changes. The function returns a handle to cancel notifications
with @code{GNUNET_PEERINFO_notify_cancel}.
address@hidden GNUnet's PEERSTORE subsystem
@node GNUnet's PEERSTORE subsystem
address@hidden GNUnet's PEERSTORE subsystem
+
@c %**end of header
GNUnet's PEERSTORE subsystem offers persistent per-peer storage for other
@@ -5119,8 +5523,9 @@ the following fields:
@item expiry: record expiry date.
@end itemize
address@hidden Functionality
@node Functionality
address@hidden Functionality
+
@c %**end of header
Subsystems can store any type of value under a (subsystem, peerid, key)
@@ -5143,8 +5548,9 @@ Subsystems can also request to be notified about any new
values stored under a
(subsystem, peerid, key) combination by sending a "watch" request to
PEERSTORE.
address@hidden Architecture
@node Architecture
address@hidden Architecture
+
@c %**end of header
PEERSTORE implements the following components:
@@ -5157,8 +5563,9 @@ issue commands to the PEERSTORE service.
"sqlite" plugin is implemented.
@end itemize
address@hidden libgnunetpeerstore
@node libgnunetpeerstore
address@hidden libgnunetpeerstore
+
@c %**end of header
libgnunetpeerstore is the library containing the PEERSTORE API. Subsystems
@@ -5197,8 +5604,9 @@ the @code{sync_first} flag is set to @code{GNUNET_YES},
the API will delay the
disconnection until all pending STORE requests are sent to the PEERSTORE
service, otherwise, the pending STORE requests will be destroyed as well.
address@hidden GNUnet's SET Subsystem
@node GNUnet's SET Subsystem
address@hidden GNUnet's SET Subsystem
+
@c %**end of header
The SET service implements efficient set operations between two peers over a
@@ -5207,8 +5615,9 @@ operations. Elements of a set consist of an @emph{element
type} and arbitrary
binary @emph{data}. The size of an element's data is limited to around 62
KB.
address@hidden Local Sets
@node Local Sets
address@hidden Local Sets
+
@c %**end of header
Sets created by a local client can be modified and reused for multiple
@@ -5219,8 +5628,9 @@ of a set is determined upon its creation. If a the
elements of a set are needed
for an operation of a different type, all of the set's element must be copied
to a new set of appropriate type.
address@hidden Set Modifications
@node Set Modifications
address@hidden Set Modifications
+
@c %**end of header
Even when set operations are active, one can add to and remove elements from a
@@ -5230,8 +5640,9 @@ sees a snapshot of the set from the time the operation
was started. This
mechanism is @emph{not} implemented by copying the whole set, but by attaching
@emph{generation information} to each element and operation.
address@hidden Set Operations
@node Set Operations
address@hidden Set Operations
+
@c %**end of header
Set operations can be started in two ways: Either by accepting an operation
@@ -5245,8 +5656,9 @@ application id. Once notified of an incoming set request,
the client can
accept the set request (providing a local set for the operation) or reject
it.
address@hidden Result Elements
@node Result Elements
address@hidden Result Elements
+
@c %**end of header
The SET service has three @emph{result modes} that determine how an operation's
@@ -5267,12 +5679,22 @@ elements. This can be useful if only the remove peer is
actually interested in
the result of the set operation.
@end itemize
address@hidden libgnunetset
@node libgnunetset
address@hidden libgnunetset
+
@c %**end of header
address@hidden Sets
address@hidden
+* Sets::
+* Listeners::
+* Operations::
+* Supplying a Set::
+* The Result Callback::
address@hidden menu
+
@node Sets
address@hidden Sets
+
@c %**end of header
New sets are created with @code{GNUNET_SET_create}. Both the local peer's
@@ -5285,8 +5707,9 @@ functions dealing with sets. This return value must
always be checked.
Elements are added and removed with @code{GNUNET_SET_add_element} and
@code{GNUNET_SET_remove_element}.
address@hidden Listeners
@node Listeners
address@hidden Listeners
+
@c %**end of header
Listeners are created with @code{GNUNET_SET_listen}. Each time time a remote
@@ -5296,8 +5719,9 @@ synchronously call either @code{GNUNET_SET_accept} or
@code{GNUNET_SET_reject}.
Note that the operation will not be started until the client calls
@code{GNUNET_SET_commit} (see Section "Supplying a Set").
address@hidden Operations
@node Operations
address@hidden Operations
+
@c %**end of header
Operations to be initiated by the local peer are created with
@@ -5305,8 +5729,9 @@ Operations to be initiated by the local peer are created
with
the client calls @code{GNUNET_SET_commit} (see Section "Supplying a
Set").
address@hidden Supplying a Set
@node Supplying a Set
address@hidden Supplying a Set
+
@c %**end of header
To create symmetry between the two ways of starting a set operation (accepting
@@ -5318,8 +5743,9 @@ The client must call @code{GNUNET_SET_commit} to specify
a set to use for an
operation. @code{GNUNET_SET_commit} may only be called once per set
operation.
address@hidden The Result Callback
@node The Result Callback
address@hidden The Result Callback
+
@c %**end of header
Clients must specify both a result mode and a result callback with
@@ -5330,12 +5756,22 @@ result mode. The callback needs to know which result
mode it is used in, as the
arguments do not indicate if an element is part of the full result set, or if
it is in the difference between the original set and the final set.
address@hidden The SET Client-Service Protocol
@node The SET Client-Service Protocol
address@hidden The SET Client-Service Protocol
+
@c %**end of header
address@hidden Creating Sets
address@hidden
+* Creating Sets::
+* Listeners2::
+* Initiating Operations::
+* Modifying Sets::
+* Iterating Sets::
address@hidden menu
+
@node Creating Sets
address@hidden Creating Sets
+
@c %**end of header
For each set of a client, there exists a client connection to the service. Sets
@@ -5343,8 +5779,9 @@ are created by sending the
@code{GNUNET_SERVICE_SET_CREATE} message over a new
client connection. Multiple operations for one set are multiplexed over one
client connection, using a request id supplied by the client.
address@hidden Listeners2
@node Listeners2
address@hidden Listeners2
+
@c %**end of header
Each listener also requires a seperate client connection. By sending the
@@ -5355,29 +5792,39 @@ client connection. In contrast, when accepting an
incoming request, a a
@code{GNUNET_SERVICE_SET_ACCEPT} message must be sent over the@ set that is
supplied for the set operation.
address@hidden Initiating Operations
@node Initiating Operations
address@hidden Initiating Operations
+
@c %**end of header
Operations with remote peers are initiated by sending a
@code{GNUNET_SERVICE_SET_EVALUATE} message to the service. The@ client
connection that this message is sent by determines the set to use.
address@hidden Modifying Sets
@node Modifying Sets
address@hidden Modifying Sets
+
@c %**end of header
Sets are modified with the @code{GNUNET_SERVICE_SET_ADD} and
@code{GNUNET_SERVICE_SET_REMOVE} messages.
+
address@hidden
+* Results and Operation Status::
+* Iterating Sets::
address@hidden menu
+
@node Results and Operation Status
address@hidden Results and Operation Status
@c %**end of header
The service notifies the client of result elements and success/failure of a set
operation with the @code{GNUNET_SERVICE_SET_RESULT} message.
address@hidden Iterating Sets
@node Iterating Sets
address@hidden Iterating Sets
+
@c %**end of header
All elements of a set can be requested by sending
@@ -5387,8 +5834,9 @@ with @code{GNUNET_SERVICE_SET_ITER_DONE}. After each
received element, the
client@ must send @code{GNUNET_SERVICE_SET_ITER_ACK}. Note that only one set
iteration may be active for a set at any given time.
address@hidden The SET-Intersection Peet-to-Peer Protocol
@node The SET-Intersection Peer-to-Peer Protocol
address@hidden The SET-Intersection Peet-to-Peer Protocol
+
@c %**end of header
The intersection protocol operates over CADET and starts with a
@@ -5411,8 +5859,15 @@ Bloom filter exchange, unless the set size is indicated
to be zero, in which
case the intersection is considered finished after just the initial
handshake.
address@hidden The Bloom filter exchange
+
address@hidden
+* The Bloom filter exchange::
+* Salt::
address@hidden menu
+
@node The Bloom filter exchange
address@hidden The Bloom filter exchange
+
@c %**end of header
In this phase, each peer transmits a Bloom filter over the remaining keys of
@@ -5434,8 +5889,9 @@ a@ GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_DONE back to
indicate that the
latest set is the final result. Otherwise, the receiver starts another Bloom
fitler exchange, except this time as the sender.
address@hidden Salt
@node Salt
address@hidden Salt
+
@c %**end of header
Bloomfilter operations are probablistic: With some non-zero probability the
@@ -5451,8 +5907,9 @@ The iterations terminate once both peers have established
that they have sets
of the same size, and where the XOR over all keys computes the same 512-bit
value (leaving a failure probability of 2-511).
address@hidden The SET-Union Peer-to-Peer Protocol
@node The SET-Union Peer-to-Peer Protocol
address@hidden The SET-Union Peer-to-Peer Protocol
+
@c %**end of header
The SET union protocol is based on Eppstein's efficient set reconciliation
@@ -5490,8 +5947,9 @@ All Bloom filter operations use a salt to mingle keys
before hasing them into
buckets, such that future iterations have a fresh chance of succeeding if they
failed due to collisions before.
address@hidden GNUnet's STATISTICS subsystem
@node GNUnet's STATISTICS subsystem
address@hidden GNUnet's STATISTICS subsystem
+
@c %**end of header
In GNUnet, the STATISTICS subsystem offers a central place for all subsystems
@@ -5532,8 +5990,9 @@ before terminating itself. This is to prevent the loss of
data during peer
shutdown --- delaying the STATISTICS service shutdown helps other services to
store important data to STATISTICS during shutdown.
address@hidden libgnunetstatistics
@node libgnunetstatistics
address@hidden libgnunetstatistics
+
@c %**end of header
@strong{libgnunetstatistics} is the library containing the API for the
@@ -5553,8 +6012,16 @@ configuration all calls to
@code{GNUNET_STATISTICS_create()} return @code{NULL}
as the STATISTICS subsystem is unavailable and no other functions from the API
can be used.
address@hidden Statistics retrieval
+
address@hidden
+* Statistics retrieval::
+* Setting statistics and updating them::
+* Watches::
address@hidden menu
+
@node Statistics retrieval
address@hidden Statistics retrieval
+
@c %**end of header
Once a connection to the statistics service is obtained, information about any
@@ -5574,8 +6041,9 @@ the function @code{GNUNET_STATISTICS_get_cancel()}. This
is helpful when
retrieving statistics takes too long and especially when we want to shutdown
and cleanup everything.
address@hidden Setting statistics and updating them
@node Setting statistics and updating them
address@hidden Setting statistics and updating them
+
@c %**end of header
So far we have seen how to retrieve statistics, here we will learn how we can
@@ -5599,8 +6067,9 @@ the client performs requests at a rate that is faster
than the available IPC
with the STATISTICS service. Thus, the client does not have to worry about
sending requests too quickly.
address@hidden Watches
@node Watches
address@hidden Watches
+
@c %**end of header
As interesting feature of STATISTICS lies in serving notifications whenever a
@@ -5616,12 +6085,20 @@ A registered watch will keep notifying any value
changes until
@code{GNUNET_STATISTICS_watch_cancel()} is called with the same parameters that
are used for registering the watch.
address@hidden The STATISTICS Client-Service Protocol
@node The STATISTICS Client-Service Protocol
address@hidden The STATISTICS Client-Service Protocol
@c %**end of header
address@hidden Statistics retrieval2
+
address@hidden
+* Statistics retrieval2::
+* Setting and updating statistics::
+* Watching for updates::
address@hidden menu
+
@node Statistics retrieval2
address@hidden Statistics retrieval2
+
@c %**end of header
To retrieve statistics, the client transmits a message of type
@@ -5632,8 +6109,9 @@ statistics parameters that match the client request for
the client. The end of
information retrieved is signaled by the service by sending a message of type
@code{GNUNET_MESSAGE_TYPE_STATISTICS_END}.
address@hidden Setting and updating statistics
@node Setting and updating statistics
address@hidden Setting and updating statistics
+
@c %**end of header
The subsystem name, parameter name, its value and the persistence flag are
@@ -5653,8 +6131,9 @@ relative update by sending a message of type
(@code{GNUNET_STATISTICS_SETFLAG_RELATIVE}) signifying that the value in the
message should be treated as an update value.
address@hidden Watching for updates
@node Watching for updates
address@hidden Watching for updates
+
@c %**end of header
The function registers the watch at the service by sending a message of type
@@ -5663,8 +6142,9 @@ notifications through messages of type
@code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH_VALUE} whenever the statistic
parameter's value is changed.
address@hidden GNUnet's Distributed Hash Table (DHT)
@node GNUnet's Distributed Hash Table (DHT)
address@hidden GNUnet's Distributed Hash Table (DHT)
+
@c %**end of header
GNUnet includes a generic distributed hash table that can be used by developers
@@ -5698,12 +6178,22 @@ significant delay. Your application logic must be
written to tolerate this
(naturally, some loss of performance or quality of service is expected in this
case).
address@hidden Block library and plugins
@node Block library and plugins
address@hidden Block library and plugins
+
@c %**end of header
address@hidden What is a Block?
address@hidden
+* What is a Block?::
+* The API of libgnunetblock::
+* Queries::
+* Sample Code::
+* Conclusion2::
address@hidden menu
+
@node What is a Block?
address@hidden What is a Block?
+
@c %**end of header
Blocks are small (< 63k) pieces of data stored under a key (struct
@@ -5716,8 +6206,9 @@ for the maintenance of the DHT are both stored using
blocks). The block
subsystem provides a few common functions that must be available for any type
of block.
address@hidden The API of libgnunetblock
@node The API of libgnunetblock
address@hidden The API of libgnunetblock
+
@c %**end of header
The block library requires for each (family of) block type(s) a block plugin
@@ -5744,8 +6235,8 @@ replies (by adding the current response to the Bloom
filter and rejecting it if
it is encountered again). If a plugin fails to do this, responses may loop in
the network.
address@hidden Queries
@node Queries
address@hidden Queries
@c %**end of header
The query format for any block in GNUnet consists of four main components.
@@ -5768,8 +6259,9 @@ Depending on the results from the plugin, the DHT will
then discard the
(invalid) query, forward the query, discard the (invalid) reply, cache the
(valid) reply, and/or forward the (valid and non-duplicate) reply.
address@hidden Sample Code
@node Sample Code
address@hidden Sample Code
+
@c %**end of header
The source code in @strong{plugin_block_test.c} is a good starting point for
@@ -5777,8 +6269,9 @@ new block plugins --- it does the minimal work by
implementing a plugin that
performs no validation at all. The respective @strong{Makefile.am} shows how to
build and install a block plugin.
address@hidden Conclusion2
@node Conclusion2
address@hidden Conclusion2
+
@c %**end of header
In conclusion, GNUnet subsystems that want to use the DHT need to define a
@@ -5788,8 +6281,9 @@ and any reply as matching any query. This type is also
used for the DHT command
line tools. However, it should NOT be used for normal applications due to the
lack of error checking that results from this primitive implementation.
address@hidden libgnunetdht
@node libgnunetdht
address@hidden libgnunetdht
+
@c %**end of header
The DHT API itself is pretty simple and offers the usual GET and PUT functions
@@ -5797,8 +6291,17 @@ that work as expected. The specified block type refers
to the block library
which allows the DHT to run application-specific logic for data stored in the
network.
address@hidden GET
+
address@hidden
+* GET::
+* PUT::
+* MONITOR::
+* DHT Routing Options::
address@hidden menu
+
@node GET
address@hidden GET
+
@c %**end of header
When using GET, the main consideration for developers (other than the block
@@ -5821,8 +6324,9 @@ more). This way, the DHT will filter the respective
blocks using the block
library in the network, which may result in a significant reduction in
bandwidth consumption.
address@hidden PUT
@node PUT
address@hidden PUT
+
@c %**end of header
In contrast to GET operations, developers @strong{must} manually re-run PUT
@@ -5839,8 +6343,9 @@ rule of thumb is that there should be at least a dozen
PUT operations within
the content lifetime. Content in the DHT typically expires after one day, so
DHT PUT operations should be repeated at least every 1-2 hours.
address@hidden MONITOR
@node MONITOR
address@hidden MONITOR
+
@c %**end of header
The DHT API also allows applications to monitor messages crossing the local
@@ -5858,8 +6363,9 @@ workers have no good way to guess the keys under which
work would be stored.
Naturally, additional protocols might be needed to ensure that the desired
number of workers will process the distributed workload.
address@hidden DHT Routing Options
@node DHT Routing Options
address@hidden DHT Routing Options
+
@c %**end of header
There are two important options for GET and PUT requests:
@@ -5887,12 +6393,20 @@ the DHT's peer discovery mechanism and should not be
used by applications.
the future offer performance improvements for clique topologies.
@end table
address@hidden The DHT Client-Service Protocol
@node The DHT Client-Service Protocol
address@hidden The DHT Client-Service Protocol
+
@c %**end of header
address@hidden PUTting data into the DHT
address@hidden
+* PUTting data into the DHT::
+* GETting data from the DHT::
+* Monitoring the DHT::
address@hidden menu
+
@node PUTting data into the DHT
address@hidden PUTting data into the DHT
+
@c %**end of header
To store (PUT) data into the DHT, the client sends a@ @code{struct
@@ -5910,8 +6424,9 @@ the same key-value pair was already stored in the DHT.
However, changing this
would also require additional state and messages in the P2P
interaction.
address@hidden GETting data from the DHT
@node GETting data from the DHT
address@hidden GETting data from the DHT
+
@c %**end of header
To retrieve (GET) data from the DHT, the client sends a@ @code{struct
@@ -5946,8 +6461,9 @@ is more common as this allows a client to run many
concurrent GET operations
over the same connection with the DHT service --- and to stop them
individually.
address@hidden Monitoring the DHT
@node Monitoring the DHT
address@hidden Monitoring the DHT
+
@c %**end of header
To begin monitoring, the client sends a @code{struct
@@ -5961,12 +6477,20 @@ GNUNET_DHT_MonitorPutMessage} for PUT events and@
@code{struct
GNUNET_DHT_MonitorGetRespMessage} for RESULTs. Each of these messages contains
all of the information about the event.
address@hidden The DHT Peer-to-Peer Protocol
@node The DHT Peer-to-Peer Protocol
address@hidden The DHT Peer-to-Peer Protocol
@c %**end of header
address@hidden Routing GETs or PUTs
+
address@hidden
+* Routing GETs or PUTs::
+* PUTting data into the DHT2::
+* GETting data from the DHT2::
address@hidden menu
+
@node Routing GETs or PUTs
address@hidden Routing GETs or PUTs
+
@c %**end of header
When routing GETs or PUTs, the DHT service selects a suitable subset of
@@ -5978,8 +6502,9 @@ estimate, the selection of the peers maybe randomized or
by proximity to the
key. Furthermore, requests include a set of peers that a request has already
traversed; those peers are also excluded from the selection.
address@hidden PUTting data into the DHT2
@node PUTting data into the DHT2
address@hidden PUTting data into the DHT2
+
@c %**end of header
To PUT data into the DHT, the service sends a @code{struct PeerPutMessage} of
@@ -5996,8 +6521,9 @@ previous hop; however, the path should not include the
identity of the previous
hop and the receiver should append the identity of the sender to the path, not
its own identity (this is done to reduce bandwidth).
address@hidden GETting data from the DHT2
@node GETting data from the DHT2
address@hidden GETting data from the DHT2
+
@c %**end of header
A peer can search the DHT by sending @code{struct PeerGetMessage}s of type
@@ -6027,8 +6553,9 @@ filter accordingly, to ensure that the same result is
never forwarded more than
once. The DHT service may also cache forwarded results locally if the
"CACHE_RESULTS" option is set to "YES" in the configuration.
address@hidden The GNU Name System (GNS)
@node The GNU Name System (GNS)
address@hidden The GNU Name System (GNS)
+
@c %**end of header
The GNU Name System (GNS) is a decentralized database that enables users to
@@ -6064,8 +6591,9 @@ users, the NAMESTORE to store information specific to the
local users, and the
DHT to exchange data between users. A plugin API is used to enable applications
to define new GNS record types.
address@hidden libgnunetgns
@node libgnunetgns
address@hidden libgnunetgns
+
@c %**end of header
The GNS API itself is extremely simple. Clients first connec to the GNS service
@@ -6074,8 +6602,17 @@ using @code{GNUNET_GNS_connect}. They can then perform
lookups using
@code{GNUNET_GNS_lookup_cancel}. Once finished, clients disconnect using
@code{GNUNET_GNS_disconnect}.
address@hidden Looking up records
+
address@hidden
+* Looking up records::
+* Accessing the records::
+* Creating records::
+* Future work::
address@hidden menu
+
@node Looking up records
address@hidden Looking up records
+
@c %**end of header
@code{GNUNET_GNS_lookup} takes a number of arguments:
@@ -6113,8 +6650,9 @@ longer be cancelled.
@item proc_cls The closure for proc.
@end table
address@hidden Accessing the records
@node Accessing the records
address@hidden Accessing the records
+
@c %**end of header
The @code{libgnunetgnsrecord} library provides an API to manipulate the GNS
@@ -6126,8 +6664,9 @@ applications.
For DNS records, the @code{libgnunetdnsparser} library provides functions for
parsing (and serializing) common types of DNS records.
address@hidden Creating records
@node Creating records
address@hidden Creating records
+
@c %**end of header
Creating GNS records is typically done by building the respective record
@@ -6136,16 +6675,18 @@ information (possibly with the help of
@code{libgnunetgnsrecord} and
publish the information. The GNS API is not involved in this
operation.
address@hidden Future work
@node Future work
address@hidden Future work
+
@c %**end of header
In the future, we want to expand @code{libgnunetgns} to allow applications to
observe shortening operations performed during GNS resolution, for example so
that users can receive visual feedback when this happens.
address@hidden libgnunetgnsrecord
@node libgnunetgnsrecord
address@hidden libgnunetgnsrecord
+
@c %**end of header
The @code{libgnunetgnsrecord} library is used to manipulate GNS records (in
@@ -6162,8 +6703,15 @@ We will now discuss the four commonly used functions of
the API.@
uses plugins to perform the operation. GNUnet includes plugins to support
common DNS record types as well as standard GNS record types.
address@hidden Value handling
+
address@hidden
+* Value handling::
+* Type handling::
address@hidden menu
+
@node Value handling
address@hidden Value handling
+
@c %**end of header
@code{GNUNET_GNSRECORD_value_to_string} can be used to convert the (binary)
@@ -6175,8 +6723,9 @@ available plugin.
readable string to the respective (binary) representation of a GNS record
value.
address@hidden Type handling
@node Type handling
address@hidden Type handling
+
@c %**end of header
@code{GNUNET_GNSRECORD_typename_to_number} can be used to obtain the numeric
@@ -6191,8 +6740,9 @@ time.}
associated with a given numeric value. For example, given the type number 1,
the function will return the typename "A".
address@hidden GNS plugins
@node GNS plugins
address@hidden GNS plugins
+
@c %**end of header
Adding a new GNS record type typically involves writing (or extending) a
@@ -6214,8 +6764,9 @@ The central functions of the block APIs (plugin and main
library) are the same
four functions for converting between values and strings, and typenames and
numbers documented in the previous section.
address@hidden The GNS Client-Service Protocol
@node The GNS Client-Service Protocol
address@hidden The GNS Client-Service Protocol
+
@c %**end of header
The GNS client-service protocol consists of two simple messages, the
@@ -6231,8 +6782,9 @@ The response includes the number of records and the
records themselves in the
format created by @code{GNUNET_GNSRECORD_records_serialize}. They can thus be
deserialized using @code{GNUNET_GNSRECORD_records_deserialize}.
address@hidden Hijacking the DNS-Traffic using gnunet-service-dns
@node Hijacking the DNS-Traffic using gnunet-service-dns
address@hidden Hijacking the DNS-Traffic using gnunet-service-dns
+
@c %**end of header
This section documents how the gnunet-service-dns (and the gnunet-helper-dns)
@@ -6257,8 +6809,14 @@ application using the DNS service will be sent to the
original recipient. The
answer to the query will always be sent back through the virtual interface with
the original nameserver as source address.
address@hidden Network Setup Details
+
address@hidden
+* Network Setup Details::
address@hidden menu
+
@node Network Setup Details
address@hidden Network Setup Details
+
@c %**end of header
The DNS interceptor adds the following rules to the Linux kernel:
@@ -6273,8 +6831,9 @@ beforehand (@code{$LOCALPORT}) will be routed normally.
Line 2 marks every
other packet to a DNS-Server with mark 3 (chosen arbitrarily). The third line
adds a routing policy based on this mark 3 via the routing table.
address@hidden Serving DNS lookups via GNS on W32
@node Serving DNS lookups via GNS on W32
address@hidden Serving DNS lookups via GNS on W32
+
@c %**end of header
This section documents how the libw32nsp (and gnunet-gns-helper-service-w32) do
@@ -6337,8 +6896,9 @@ use alternative means of resolving names (such as sending
queries to a DNS
server directly by themselves). This includes some of well known utilities,
like "ping" and "nslookup".
address@hidden The GNS Namecache
@node The GNS Namecache
address@hidden The GNS Namecache
+
@c %**end of header
The NAMECACHE subsystem is responsible for caching (encrypted) resolution
@@ -6364,8 +6924,9 @@ always small enough (a few MB) to fit on the drive.
The NAMECACHE supports the use of different database backends via a plugin API.
address@hidden libgnunetnamecache
@node libgnunetnamecache
address@hidden libgnunetnamecache
+
@c %**end of header
The NAMECACHE API consists of five simple functions. First, there is
@@ -6384,8 +6945,9 @@ the NAMECACHE.
The maximum size of a block that can be stored in the NAMECACHE is
@code{GNUNET_NAMECACHE_MAX_VALUE_SIZE}, which is defined to be 63 kB.
address@hidden The NAMECACHE Client-Service Protocol
@node The NAMECACHE Client-Service Protocol
address@hidden The NAMECACHE Client-Service Protocol
+
@c %**end of header
All messages in the NAMECACHE IPC protocol start with the @code{struct
@@ -6394,8 +6956,15 @@ standard message header. The request ID is used to match
requests with the
respective responses from the NAMECACHE, as they are allowed to happen
out-of-order.
address@hidden Lookup
+
address@hidden
+* Lookup::
+* Store::
address@hidden menu
+
@node Lookup
address@hidden Lookup
+
@c %**end of header
The @code{struct LookupBlockMessage} is used to lookup a block stored in the
@@ -6405,8 +6974,9 @@ sets the expiration time in the response to zero.
Otherwise, the response is
expected to contain the expiration time, the ECDSA signature, the derived key
and the (variable-size) encrypted data of the block.
address@hidden Store
@node Store
address@hidden Store
+
@c %**end of header
The @code{struct BlockCacheMessage} is used to cache a block in the NAMECACHE.
@@ -6415,16 +6985,23 @@ service responds with a @code{struct
BlockCacheResponseMessage} which contains
the result of the operation (success or failure). In the future, we might want
to make it possible to provide an error message as well.
address@hidden The NAMECACHE Plugin API
@node The NAMECACHE Plugin API
address@hidden The NAMECACHE Plugin API
@c %**end of header
The NAMECACHE plugin API consists of two functions, @code{cache_block} to store
a block in the database, and @code{lookup_block} to lookup a block in the
database.
address@hidden Lookup2
+
address@hidden
+* Lookup2::
+* Store2::
address@hidden menu
+
@node Lookup2
address@hidden Lookup2
+
@c %**end of header
The @code{lookup_block} function is expected to return at most one block to the
@@ -6432,8 +7009,9 @@ iterator, and return @code{GNUNET_NO} if there were no
non-expired results. If
there are multiple non-expired results in the cache, the lookup is supposed to
return the result with the largest expiration time.
address@hidden Store2
@node Store2
address@hidden Store2
+
@c %**end of header
The @code{cache_block} function is expected to try to store the block in the
@@ -6447,8 +7025,8 @@ can done either by simply adding new blocks and selecting
for the most recent
expiration time during lookup, or by checking which block is more recent during
the store operation.
address@hidden The REVOCATION Subsystem
@node The REVOCATION Subsystem
address@hidden The REVOCATION Subsystem
@c %**end of header
The REVOCATION subsystem is responsible for key revocation of Egos. If a user
@@ -6457,8 +7035,9 @@ REVOCATION system to inform all of the other users that
this private key is no
longer valid. The subsystem thus includes ways to query for the validity of
keys and to propagate revocation messages.
address@hidden Dissemination
@node Dissemination
address@hidden Dissemination
+
@c %**end of header
When a revocation is performed, the revocation is first of all disseminated by
@@ -6478,8 +7057,9 @@ messages whenever two peers (that both support REVOCATION
dissemination)
connect. The SET service is used to perform this operation
efficiently.
address@hidden Revocation Message: Design Requirements
address@hidden Revocation Message: Design Requirements
address@hidden Revocation Message Design Requirements
address@hidden Revocation Message Design Requirements
+
@c %**end of header
However, flooding is also quite costly, creating O(|E|) messages on a network
@@ -6498,15 +7078,24 @@ revoked. Thus, they can only be created while the
private key is in the
possession of the respective user. This is another reason to create a
revocation message ahead of time and store it in a secure location.
address@hidden libgnunetrevocation
@node libgnunetrevocation
address@hidden libgnunetrevocation
+
@c %**end of header
The REVOCATION API consists of two parts, to query and to issue
revocations.
address@hidden Querying for revoked keys
+
address@hidden
+* Querying for revoked keys::
+* Preparing revocations::
+* Issuing revocations::
address@hidden menu
+
@node Querying for revoked keys
address@hidden Querying for revoked keys
+
@c %**end of header
@code{GNUNET_REVOCATION_query} is used to check if a given ECDSA public key has
@@ -6514,8 +7103,9 @@ been revoked. The given callback will be invoked with the
result of the check.
The query can be cancelled using @code{GNUNET_REVOCATION_query_cancel} on the
return value.
address@hidden Preparing revocations
@node Preparing revocations
address@hidden Preparing revocations
+
@c %**end of header
It is often desirable to create a revocation record ahead-of-time and store it
@@ -6544,8 +7134,9 @@ the future) is to be revoked and returns the signature.
The signature can again
be saved to disk for later use, which will then allow performing a revocation
even without access to the private key.
address@hidden Issuing revocations
@node Issuing revocations
address@hidden Issuing revocations
+
Given a ECDSA public key, the signature from @code{GNUNET_REVOCATION_sign} and
the proof-of-work, @code{GNUNET_REVOCATION_revoke} can be used to perform the
@@ -6554,8 +7145,9 @@ operation. @code{GNUNET_REVOCATION_revoke_cancel} can be
used to stop the
library from calling the continuation; however, in that case it is undefined
whether or not the revocation operation will be executed.
address@hidden The REVOCATION Client-Service Protocol
@node The REVOCATION Client-Service Protocol
address@hidden The REVOCATION Client-Service Protocol
+
The REVOCATION protocol consists of four simple messages.
@@ -6572,8 +7164,9 @@ and the proof-of-work, The service responds with a
@code{RevokeMessage} was invalid (i.e. proof of work incorrect), or otherwise
indicates that the revocation has been processed successfully.
address@hidden The REVOCATION Peer-to-Peer Protocol
@node The REVOCATION Peer-to-Peer Protocol
address@hidden The REVOCATION Peer-to-Peer Protocol
+
@c %**end of header
Revocation uses two disjoint ways to spread revocation information among peers.
@@ -6600,8 +7193,9 @@ peers at any time; however, well-behaved peers should
only initiate this
operation once after establishing a connection to a peer with a larger hashed
peer identity.
address@hidden GNUnet's File-sharing (FS) Subsystem
@node GNUnet's File-sharing (FS) Subsystem
address@hidden GNUnet's File-sharing (FS) Subsystem
+
@c %**end of header
This chapter describes the details of how the file-sharing service works. As
@@ -6627,8 +7221,9 @@ in the FS service.
NOTE: The documentation in this chapter is quite incomplete.
address@hidden Encoding for Censorship-Resistant Sharing (ECRS)
@node Encoding for Censorship-Resistant Sharing (ECRS)
address@hidden Encoding for Censorship-Resistant Sharing (ECRS)
+
@c %**end of header
When GNUnet shares files, it uses a content encoding that is called ECRS, the
@@ -6642,8 +7237,15 @@ extensions are not in the paper is that we felt that
they were obvious or
trivial extensions to the original scheme and thus did not warrant space in
the research report.
address@hidden Namespace Advertisements
+
address@hidden
+* Namespace Advertisements::
+* KSBlocks::
address@hidden menu
+
@node Namespace Advertisements
address@hidden Namespace Advertisements
+
@c %**end of header
An @code{SBlock} with identifier â²all zerosâ² is a signed
@@ -6654,8 +7256,9 @@ namespace. The URI should always be empty. The
@code{SBlock} is signed with
the content provderâ²s RSA private key (just like any other SBlock). Peers
can search for @code{SBlock}s in order to find out more about a namespace.
address@hidden KSBlocks
@node KSBlocks
address@hidden KSBlocks
+
@c %**end of header
GNUnet implements @code{KSBlocks} which are @code{KBlocks} that, instead of
@@ -6681,8 +7284,9 @@ Collections are also advertised using @code{KSBlock}s.
@item https://gnunet.org/sites/default/files/ecrs.pdf
@end table
address@hidden File-sharing persistence directory structure
@node File-sharing persistence directory structure
address@hidden File-sharing persistence directory structure
+
@c %**end of header
This section documents how the file-sharing library implements persistence of
@@ -6752,8 +7356,9 @@ this directory structure is flat and does not mirror the
structure of the
publishing operation. Note that unindex operations cannot have associated child
operations.
address@hidden GNUnet's REGEX Subsystem
@node GNUnet's REGEX Subsystem
address@hidden GNUnet's REGEX Subsystem
+
@c %**end of header
Using the REGEX subsystem, you can discover peers that offer a particular
@@ -6766,8 +7371,9 @@ For the technical details, we have "Max's defense talk
and Max's Master's
thesis. An additional publication is under preparation and available to team
members (in Git).
address@hidden How to run the regex profiler
@node How to run the regex profiler
address@hidden How to run the regex profiler
+
@c %**end of header
The gnunet-regex-profiler can be used to profile the usage of mesh/regex for a
--
To stop receiving notification emails like this one, please contact
address@hidden
- [GNUnet-SVN] [gnunet-texinfo] branch master updated (6abc704 -> a42c8a3),
gnunet <=