aboutsummaryrefslogtreecommitdiff
path: root/doc/handbook/chapters/developer.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/handbook/chapters/developer.texi')
-rw-r--r--doc/handbook/chapters/developer.texi83
1 files changed, 41 insertions, 42 deletions
diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi
index 9bb74c3de..1bf7a7b24 100644
--- a/doc/handbook/chapters/developer.texi
+++ b/doc/handbook/chapters/developer.texi
@@ -392,9 +392,9 @@ etc.).
392@item @file{transport/} --- transport service 392@item @file{transport/} --- transport service
393The transport service is responsible for managing the 393The transport service is responsible for managing the
394basic P2P communication. It uses plugins to support P2P communication 394basic P2P communication. It uses plugins to support P2P communication
395over TCP, UDP, HTTP, HTTPS and other protocols.The transport service 395over TCP, UDP, HTTP, HTTPS and other protocols. The transport service
396validates peer addresses, enforces bandwidth restrictions, limits the 396validates peer addresses, enforces bandwidth restrictions, limits the
397total number of connections and enforces connectivity restrictions (i.e. 397total number of connections and enforces connectivity restrictions (e.g.
398friends-only). 398friends-only).
399@item @file{peerinfo-tool/} --- gnunet-peerinfo 399@item @file{peerinfo-tool/} --- gnunet-peerinfo
400This directory contains the gnunet-peerinfo binary which can be used to 400This directory contains the gnunet-peerinfo binary which can be used to
@@ -746,21 +746,21 @@ Here you can find some rules to help you write code for GNUnet.
746 746
747@itemize @bullet 747@itemize @bullet
748@item services and daemons use their directory name in 748@item services and daemons use their directory name in
749@code{GNUNET_log_setup} (i.e. 'core') and log using 749@code{GNUNET_log_setup} (e.g. 'core') and log using
750plain 'GNUNET_log'. 750plain 'GNUNET_log'.
751@item command-line tools use their full name in 751@item command-line tools use their full name in
752@code{GNUNET_log_setup} (i.e. 'gnunet-publish') and log using 752@code{GNUNET_log_setup} (e.g. 'gnunet-publish') and log using
753plain 'GNUNET_log'. 753plain 'GNUNET_log'.
754@item service access libraries log using 754@item service access libraries log using
755'@code{GNUNET_log_from}' and use '@code{DIRNAME-api}' for the 755'@code{GNUNET_log_from}' and use '@code{DIRNAME-api}' for the
756component (i.e. 'core-api') 756component (e.g. 'core-api')
757@item pure libraries (without associated service) use 757@item pure libraries (without associated service) use
758'@code{GNUNET_log_from}' with the component set to their 758'@code{GNUNET_log_from}' with the component set to their
759library name (without lib or '@file{.so}'), 759library name (without lib or '@file{.so}'),
760which should also be their directory name (i.e. '@file{nat}') 760which should also be their directory name (e.g. '@file{nat}')
761@item plugins should use '@code{GNUNET_log_from}' 761@item plugins should use '@code{GNUNET_log_from}'
762with the directory name and the plugin name combined to produce 762with the directory name and the plugin name combined to produce
763the component name (i.e. 'transport-tcp'). 763the component name (e.g. 'transport-tcp').
764@item logging should be unified per-file by defining a 764@item logging should be unified per-file by defining a
765@code{LOG} macro with the appropriate arguments, 765@code{LOG} macro with the appropriate arguments,
766along these lines: 766along these lines:
@@ -832,14 +832,14 @@ test
832@subsubsection src/ directories 832@subsubsection src/ directories
833 833
834@itemize @bullet 834@itemize @bullet
835@item gnunet-NAME: end-user applications (i.e., gnunet-search, gnunet-arm) 835@item gnunet-NAME: end-user applications (like gnunet-search or gnunet-arm)
836@item gnunet-service-NAME: service processes with accessor library (i.e., 836@item gnunet-service-NAME: service processes with accessor library (e.g.
837gnunet-service-arm) 837gnunet-service-arm)
838@item libgnunetNAME: accessor library (_service.h-header) or standalone 838@item libgnunetNAME: accessor library (_service.h-header) or standalone
839library (_lib.h-header) 839library (_lib.h-header)
840@item gnunet-daemon-NAME: daemon process without accessor library (i.e., 840@item gnunet-daemon-NAME: daemon process without accessor library (e.g.
841gnunet-daemon-hostlist) and no GNUnet management port 841gnunet-daemon-hostlist) and no GNUnet management port
842@item libgnunet_plugin_DIR_NAME: loadable plugins (i.e., 842@item libgnunet_plugin_DIR_NAME: loadable plugins (e.g.
843libgnunet_plugin_transport_tcp) 843libgnunet_plugin_transport_tcp)
844@end itemize 844@end itemize
845 845
@@ -2305,7 +2305,7 @@ for new developers):
2305@itemize @bullet 2305@itemize @bullet
2306@item logging (common_logging.c) 2306@item logging (common_logging.c)
2307@item memory allocation (common_allocation.c) 2307@item memory allocation (common_allocation.c)
2308@item endianess conversion (common_endian.c) 2308@item endianness conversion (common_endian.c)
2309@item internationalization (common_gettext.c) 2309@item internationalization (common_gettext.c)
2310@item String manipulation (string.c) 2310@item String manipulation (string.c)
2311@item file access (disk.c) 2311@item file access (disk.c)
@@ -4287,7 +4287,7 @@ which will warn you if you don't have the necessary libraries.
4287@c work!@ Finally you just have to be sure that you have the correct drivers 4287@c work!@ Finally you just have to be sure that you have the correct drivers
4288@c for your Bluetooth device installed and that your device is on and in a 4288@c for your Bluetooth device installed and that your device is on and in a
4289@c discoverable mode. The Windows Bluetooth Stack supports only the RFCOMM 4289@c discoverable mode. The Windows Bluetooth Stack supports only the RFCOMM
4290@c protocol so we cannot turn on your device programatically! 4290@c protocol so we cannot turn on your device programmatically!
4291 4291
4292@c FIXME: Change to unique title 4292@c FIXME: Change to unique title
4293@node How does it work2? 4293@node How does it work2?
@@ -4638,7 +4638,7 @@ simply use the socket.
4638@c implementation follows the same principles as the GNU/Linux one: 4638@c implementation follows the same principles as the GNU/Linux one:
4639 4639
4640@c @itemize @bullet 4640@c @itemize @bullet
4641@c @item It has a initalization part where it initializes the 4641@c @item It has a initialization part where it initializes the
4642@c Windows Sockets, creates a RFCOMM socket which will be binded and switched 4642@c Windows Sockets, creates a RFCOMM socket which will be binded and switched
4643@c to the listening mode and registers a SDP service. In the Microsoft 4643@c to the listening mode and registers a SDP service. In the Microsoft
4644@c Bluetooth API there are two ways to work with the SDP: 4644@c Bluetooth API there are two ways to work with the SDP:
@@ -5023,7 +5023,7 @@ key of the other peer
5023ephemeral key of the other peer, but we are waiting for the other peer to 5023ephemeral key of the other peer, but we are waiting for the other peer to
5024confirm it's authenticity (ability to decode) via challenge-response. 5024confirm it's authenticity (ability to decode) via challenge-response.
5025@item @code{KX_STATE_UP} The connection is fully up from the point of 5025@item @code{KX_STATE_UP} The connection is fully up from the point of
5026view of the sender (now performing keep-alives) 5026view of the sender (now performing keep-alive)
5027@item @code{KX_STATE_REKEY_SENT} The sender has initiated a rekeying 5027@item @code{KX_STATE_REKEY_SENT} The sender has initiated a rekeying
5028operation; the other peer has so far failed to confirm a working 5028operation; the other peer has so far failed to confirm a working
5029connection using the new ephemeral key 5029connection using the new ephemeral key
@@ -5653,7 +5653,7 @@ download. The client component is basically a HTTP client
5653(based on libcurl) which can download hostlists from one or more websites. 5653(based on libcurl) which can download hostlists from one or more websites.
5654The hostlist format is a binary blob containing a sequence of HELLO 5654The hostlist format is a binary blob containing a sequence of HELLO
5655messages. Note that any HTTP server can theoretically serve a hostlist, 5655messages. Note that any HTTP server can theoretically serve a hostlist,
5656the build-in hostlist server makes it simply convenient to offer this 5656the built-in hostlist server makes it simply convenient to offer this
5657service. 5657service.
5658 5658
5659 5659
@@ -5895,7 +5895,7 @@ The size of the list of URLs is restricted, so if an additional server is
5895added and the list is full, the URL with the worst quality ranking 5895added and the list is full, the URL with the worst quality ranking
5896(determined through successful downloads and number of HELLOs e.g.) is 5896(determined through successful downloads and number of HELLOs e.g.) is
5897discarded. During shutdown the list of URLs is saved to a file for 5897discarded. During shutdown the list of URLs is saved to a file for
5898persistance and loaded on startup. URLs from the configuration file are 5898persistence and loaded on startup. URLs from the configuration file are
5899never discarded. 5899never discarded.
5900 5900
5901@node Usage 5901@node Usage
@@ -6155,7 +6155,7 @@ To disconnect from NAMESTORE, clients use
6155@code{GNUNET_NAMESTORE_disconnect} and specify the handle to disconnect. 6155@code{GNUNET_NAMESTORE_disconnect} and specify the handle to disconnect.
6156 6156
6157NAMESTORE internally uses the ECDSA private key to refer to zones. These 6157NAMESTORE internally uses the ECDSA private key to refer to zones. These
6158private keys can be obtained from the IDENTITY subsytem. 6158private keys can be obtained from the IDENTITY subsystem.
6159Here @emph{egos} @emph{can be used to refer to zones or the default ego 6159Here @emph{egos} @emph{can be used to refer to zones or the default ego
6160assigned to the GNS subsystem can be used to obtained the master zone's 6160assigned to the GNS subsystem can be used to obtained the master zone's
6161private key.} 6161private key.}
@@ -6640,7 +6640,7 @@ The size of an element's data is limited to around 62 KB.
6640Sets created by a local client can be modified and reused for multiple 6640Sets created by a local client can be modified and reused for multiple
6641operations. As each set operation requires potentially expensive special 6641operations. As each set operation requires potentially expensive special
6642auxiliary data to be computed for each element of a set, a set can only 6642auxiliary data to be computed for each element of a set, a set can only
6643participate in one type of set operation (i.e. union or intersection). 6643participate in one type of set operation (either union or intersection).
6644The type of a set is determined upon its creation. 6644The type of a set is determined upon its creation.
6645If a the elements of a set are needed for an operation of a different 6645If a the elements of a set are needed for an operation of a different
6646type, all of the set's element must be copied to a new set of appropriate 6646type, all of the set's element must be copied to a new set of appropriate
@@ -6811,7 +6811,7 @@ the client.
6811 6811
6812 6812
6813 6813
6814Each listener also requires a seperate client connection. By sending the 6814Each listener also requires a separate client connection. By sending the
6815@code{GNUNET_SERVICE_SET_LISTEN} message, the client notifies the service 6815@code{GNUNET_SERVICE_SET_LISTEN} message, the client notifies the service
6816of the application id and operation type it is interested in. A client 6816of the application id and operation type it is interested in. A client
6817rejects an incoming request by sending @code{GNUNET_SERVICE_SET_REJECT} 6817rejects an incoming request by sending @code{GNUNET_SERVICE_SET_REJECT}
@@ -7147,7 +7147,7 @@ the client.
7147@node Listeners for Intersection 7147@node Listeners for Intersection
7148@subsubsection Listeners for Intersection 7148@subsubsection Listeners for Intersection
7149 7149
7150Each listener also requires a seperate client connection. By sending the 7150Each listener also requires a separate client connection. By sending the
7151@code{GNUNET_SERVICE_SETI_LISTEN} message, the client notifies the service 7151@code{GNUNET_SERVICE_SETI_LISTEN} message, the client notifies the service
7152of the application id and operation type it is interested in. A client 7152of the application id and operation type it is interested in. A client
7153rejects an incoming request by sending @code{GNUNET_SERVICE_SETI_REJECT} 7153rejects an incoming request by sending @code{GNUNET_SERVICE_SETI_REJECT}
@@ -7409,7 +7409,7 @@ the client.
7409@node Listeners for Union 7409@node Listeners for Union
7410@subsubsection Listeners for Union 7410@subsubsection Listeners for Union
7411 7411
7412Each listener also requires a seperate client connection. By sending the 7412Each listener also requires a separate client connection. By sending the
7413@code{GNUNET_SERVICE_SETU_LISTEN} message, the client notifies the service 7413@code{GNUNET_SERVICE_SETU_LISTEN} message, the client notifies the service
7414of the application id and operation type it is interested in. A client 7414of the application id and operation type it is interested in. A client
7415rejects an incoming request by sending @code{GNUNET_SERVICE_SETU_REJECT} 7415rejects an incoming request by sending @code{GNUNET_SERVICE_SETU_REJECT}
@@ -7832,7 +7832,7 @@ performance).
7832Third, an optional Bloom filter can be specified to exclude known results; 7832Third, an optional Bloom filter can be specified to exclude known results;
7833replies that hash to the bits set in the Bloom filter are considered 7833replies that hash to the bits set in the Bloom filter are considered
7834invalid. False-positives can be eliminated by sending the same query 7834invalid. False-positives can be eliminated by sending the same query
7835again with a different Bloom filter mutator value, which parameterizes 7835again with a different Bloom filter mutator value, which parametrizes
7836the hash function that is used. 7836the hash function that is used.
7837Finally, an optional application-specific "eXtended query" (xquery) can 7837Finally, an optional application-specific "eXtended query" (xquery) can
7838be specified to further constrain the results. It is entirely up to 7838be specified to further constrain the results. It is entirely up to
@@ -9030,14 +9030,13 @@ particular key has been revoked. The service responds with a
9030@code{QueryResponseMessage} which simply contains a bit that says if the 9030@code{QueryResponseMessage} which simply contains a bit that says if the
9031given public key is still valid, or if it has been revoked. 9031given public key is still valid, or if it has been revoked.
9032 9032
9033The second possible interaction is for a client to revoke a key by 9033The second possible interaction is for a client to revoke a key by passing a
9034passing a @code{RevokeMessage} to the service. The @code{RevokeMessage} 9034@code{RevokeMessage} to the service. The @code{RevokeMessage} contains the
9035contains the ECDSA public key to be revoked, a signature by the 9035ECDSA public key to be revoked, a signature by the corresponding private key
9036corresponding private key and the proof-of-work, The service responds 9036and the proof-of-work. The service responds with a
9037with a @code{RevocationResponseMessage} which can be used to indicate 9037@code{RevocationResponseMessage} which can be used to indicate that the
9038that the @code{RevokeMessage} was invalid (i.e. proof of work incorrect), 9038@code{RevokeMessage} was invalid (e.g. the proof of work is incorrect), or
9039or otherwise indicates that the revocation has been processed 9039otherwise to indicate that the revocation has been processed successfully.
9040successfully.
9041 9040
9042@node The REVOCATION Peer-to-Peer Protocol 9041@node The REVOCATION Peer-to-Peer Protocol
9043@subsection The REVOCATION Peer-to-Peer Protocol 9042@subsection The REVOCATION Peer-to-Peer Protocol
@@ -9615,9 +9614,9 @@ In order to address the above issues, we want to:
9615 TRANSPORT shall create bi-directional channels from this whenever 9614 TRANSPORT shall create bi-directional channels from this whenever
9616 possible. 9615 possible.
9617@item DV should no longer be a plugin, but part of TRANSPORT. 9616@item DV should no longer be a plugin, but part of TRANSPORT.
9618@item TRANSPORT should provide communicators help communicating (i.e. in the 9617@item TRANSPORT should provide communicators help communicating, for example
9619 case of uni-directional communicators or the need for out-of-band 9618 in the case of uni-directional communicators or the need for out-of-band
9620 signalling for NAT traversal). We call this functionality 9619 signalling for NAT traversal. We call this functionality
9621 @emph{backchannels}. 9620 @emph{backchannels}.
9622@item Transport manipulation should be signalled to CORE on a per-message basis 9621@item Transport manipulation should be signalled to CORE on a per-message basis
9623 instead of an approximate bandwidth. 9622 instead of an approximate bandwidth.
@@ -9715,8 +9714,8 @@ by layer. For example, CADET will always strictly implement reliable and
9715in-order delivery of messages, while the same options are only advisory for 9714in-order delivery of messages, while the same options are only advisory for
9716TRANSPORT and CORE: they should try (using ACKs on unreliable communicators, 9715TRANSPORT and CORE: they should try (using ACKs on unreliable communicators,
9717not changing the message order themselves), but if messages are lost anyway 9716not changing the message order themselves), but if messages are lost anyway
9718(i.e. because a TCP is dropped in the middle), or if messages are reordered 9717(e.g. because a TCP is dropped in the middle), or if messages are reordered
9719(i.e. because they took dierent paths over the network and arrived in a 9718(e.g. because they took different paths over the network and arrived in a
9720different order) TRANSPORT and CORE do not have to correct this. Whether a 9719different order) TRANSPORT and CORE do not have to correct this. Whether a
9721preference is strict or loose is thus dened by the respective layer. 9720preference is strict or loose is thus dened by the respective layer.
9722 9721
@@ -9728,8 +9727,8 @@ The API for communicators is defined in
9728Each communicator must specify its (global) communication characteristics, which 9727Each communicator must specify its (global) communication characteristics, which
9729for now only say whether the communication is reliable (e.g. TCP, HTTPS) or 9728for now only say whether the communication is reliable (e.g. TCP, HTTPS) or
9730unreliable (e.g. UDP, WLAN). Each communicator must specify a unique address 9729unreliable (e.g. UDP, WLAN). Each communicator must specify a unique address
9731prex, or NULL if the communicator cannot establish outgoing connections (i.e. 9730prex, or NULL if the communicator cannot establish outgoing connections
9732is only acting as a TCP server). 9731(for example because it is only acting as a TCP server).
9733A communicator must tell TRANSPORT which addresses it is reachable under. 9732A communicator must tell TRANSPORT which addresses it is reachable under.
9734Addresses may be added or removed at any time. A communicator may have zero 9733Addresses may be added or removed at any time. A communicator may have zero
9735addresses (transmission only). 9734addresses (transmission only).
@@ -9810,7 +9809,7 @@ properties designed for application level usage:
9810@item MESSENGER allows detection for dropped messages by chaining them (messages 9809@item MESSENGER allows detection for dropped messages by chaining them (messages
9811 refer to the last message by their hash) improving accountability 9810 refer to the last message by their hash) improving accountability
9812@item MESSENGER allows requesting messages from other peers explicitly to ensure 9811@item MESSENGER allows requesting messages from other peers explicitly to ensure
9813 availibility 9812 availability
9814@item MESSENGER provides confidentiality by padding messages to few different 9813@item MESSENGER provides confidentiality by padding messages to few different
9815 sizes (512 bytes, 4096 bytes, 32768 bytes and maximal message size from 9814 sizes (512 bytes, 4096 bytes, 32768 bytes and maximal message size from
9816 CADET) 9815 CADET)
@@ -9825,13 +9824,13 @@ Also MESSENGER provides multiple features with privacy in mind:
9825@itemize @bullet 9824@itemize @bullet
9826@item MESSENGER allows deleting messages from all peers in the group by the 9825@item MESSENGER allows deleting messages from all peers in the group by the
9827 original sender (uses the MESSENGER provided verification) 9826 original sender (uses the MESSENGER provided verification)
9828@item MESSENGER allows using the publically known anonymous ego instead of any 9827@item MESSENGER allows using the publicly known anonymous ego instead of any
9829 unique identifying ego 9828 unique identifying ego
9830@item MESSENGER allows your node to decide between acting as host of the used 9829@item MESSENGER allows your node to decide between acting as host of the used
9831 messaging room (sharing your peer's identity with all nodes in the group) 9830 messaging room (sharing your peer's identity with all nodes in the group)
9832 or acting as guest (sharing your peer's identity only with the nodes you 9831 or acting as guest (sharing your peer's identity only with the nodes you
9833 explicitly open a connection to) 9832 explicitly open a connection to)
9834@item MESSENGER handles members independantly of the peer's identity making 9833@item MESSENGER handles members independently of the peer's identity making
9835 forwarded messages indistinguishable from directly received ones ( 9834 forwarded messages indistinguishable from directly received ones (
9836 complicating the tracking of messages and identifying its origin) 9835 complicating the tracking of messages and identifying its origin)
9837@item MESSENGER allows names of members being not unique (also names are 9836@item MESSENGER allows names of members being not unique (also names are
@@ -9977,7 +9976,7 @@ check for completion of a member session requires this information.
9977 9976
9978A member session is a triple of the room key, the member ID and the public key 9977A member session is a triple of the room key, the member ID and the public key
9979of the member's ego. Member sessions allow that a member can change their ID or 9978of the member's ego. Member sessions allow that a member can change their ID or
9980their ego once at a time without loosing the ability to delete old messages or 9979their ego once at a time without losing the ability to delete old messages or
9981identifying the original sender of a message. On every change of ID or EGO a 9980identifying the original sender of a message. On every change of ID or EGO a
9982session will be marked as closed. So every session chain will only contain one 9981session will be marked as closed. So every session chain will only contain one
9983open session with the current ID and public key. 9982open session with the current ID and public key.