diff options
Diffstat (limited to 'doc/handbook/chapters/developer.texi')
-rw-r--r-- | doc/handbook/chapters/developer.texi | 83 |
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 |
393 | The transport service is responsible for managing the | 393 | The transport service is responsible for managing the |
394 | basic P2P communication. It uses plugins to support P2P communication | 394 | basic P2P communication. It uses plugins to support P2P communication |
395 | over TCP, UDP, HTTP, HTTPS and other protocols.The transport service | 395 | over TCP, UDP, HTTP, HTTPS and other protocols. The transport service |
396 | validates peer addresses, enforces bandwidth restrictions, limits the | 396 | validates peer addresses, enforces bandwidth restrictions, limits the |
397 | total number of connections and enforces connectivity restrictions (i.e. | 397 | total number of connections and enforces connectivity restrictions (e.g. |
398 | friends-only). | 398 | friends-only). |
399 | @item @file{peerinfo-tool/} --- gnunet-peerinfo | 399 | @item @file{peerinfo-tool/} --- gnunet-peerinfo |
400 | This directory contains the gnunet-peerinfo binary which can be used to | 400 | This 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 |
750 | plain 'GNUNET_log'. | 750 | plain '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 |
753 | plain 'GNUNET_log'. | 753 | plain '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 |
756 | component (i.e. 'core-api') | 756 | component (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 |
759 | library name (without lib or '@file{.so}'), | 759 | library name (without lib or '@file{.so}'), |
760 | which should also be their directory name (i.e. '@file{nat}') | 760 | which 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}' |
762 | with the directory name and the plugin name combined to produce | 762 | with the directory name and the plugin name combined to produce |
763 | the component name (i.e. 'transport-tcp'). | 763 | the 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, |
766 | along these lines: | 766 | along 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. |
837 | gnunet-service-arm) | 837 | gnunet-service-arm) |
838 | @item libgnunetNAME: accessor library (_service.h-header) or standalone | 838 | @item libgnunetNAME: accessor library (_service.h-header) or standalone |
839 | library (_lib.h-header) | 839 | library (_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. |
841 | gnunet-daemon-hostlist) and no GNUnet management port | 841 | gnunet-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. |
843 | libgnunet_plugin_transport_tcp) | 843 | libgnunet_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 | |||
5023 | ephemeral key of the other peer, but we are waiting for the other peer to | 5023 | ephemeral key of the other peer, but we are waiting for the other peer to |
5024 | confirm it's authenticity (ability to decode) via challenge-response. | 5024 | confirm 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 |
5026 | view of the sender (now performing keep-alives) | 5026 | view 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 |
5028 | operation; the other peer has so far failed to confirm a working | 5028 | operation; the other peer has so far failed to confirm a working |
5029 | connection using the new ephemeral key | 5029 | connection 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. |
5654 | The hostlist format is a binary blob containing a sequence of HELLO | 5654 | The hostlist format is a binary blob containing a sequence of HELLO |
5655 | messages. Note that any HTTP server can theoretically serve a hostlist, | 5655 | messages. Note that any HTTP server can theoretically serve a hostlist, |
5656 | the build-in hostlist server makes it simply convenient to offer this | 5656 | the built-in hostlist server makes it simply convenient to offer this |
5657 | service. | 5657 | service. |
5658 | 5658 | ||
5659 | 5659 | ||
@@ -5895,7 +5895,7 @@ The size of the list of URLs is restricted, so if an additional server is | |||
5895 | added and the list is full, the URL with the worst quality ranking | 5895 | added 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 |
5897 | discarded. During shutdown the list of URLs is saved to a file for | 5897 | discarded. During shutdown the list of URLs is saved to a file for |
5898 | persistance and loaded on startup. URLs from the configuration file are | 5898 | persistence and loaded on startup. URLs from the configuration file are |
5899 | never discarded. | 5899 | never 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 | ||
6157 | NAMESTORE internally uses the ECDSA private key to refer to zones. These | 6157 | NAMESTORE internally uses the ECDSA private key to refer to zones. These |
6158 | private keys can be obtained from the IDENTITY subsytem. | 6158 | private keys can be obtained from the IDENTITY subsystem. |
6159 | Here @emph{egos} @emph{can be used to refer to zones or the default ego | 6159 | Here @emph{egos} @emph{can be used to refer to zones or the default ego |
6160 | assigned to the GNS subsystem can be used to obtained the master zone's | 6160 | assigned to the GNS subsystem can be used to obtained the master zone's |
6161 | private key.} | 6161 | private key.} |
@@ -6640,7 +6640,7 @@ The size of an element's data is limited to around 62 KB. | |||
6640 | Sets created by a local client can be modified and reused for multiple | 6640 | Sets created by a local client can be modified and reused for multiple |
6641 | operations. As each set operation requires potentially expensive special | 6641 | operations. As each set operation requires potentially expensive special |
6642 | auxiliary data to be computed for each element of a set, a set can only | 6642 | auxiliary data to be computed for each element of a set, a set can only |
6643 | participate in one type of set operation (i.e. union or intersection). | 6643 | participate in one type of set operation (either union or intersection). |
6644 | The type of a set is determined upon its creation. | 6644 | The type of a set is determined upon its creation. |
6645 | If a the elements of a set are needed for an operation of a different | 6645 | If a the elements of a set are needed for an operation of a different |
6646 | type, all of the set's element must be copied to a new set of appropriate | 6646 | type, 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 | ||
6814 | Each listener also requires a seperate client connection. By sending the | 6814 | Each 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 |
6816 | of the application id and operation type it is interested in. A client | 6816 | of the application id and operation type it is interested in. A client |
6817 | rejects an incoming request by sending @code{GNUNET_SERVICE_SET_REJECT} | 6817 | rejects 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 | ||
7150 | Each listener also requires a seperate client connection. By sending the | 7150 | Each 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 |
7152 | of the application id and operation type it is interested in. A client | 7152 | of the application id and operation type it is interested in. A client |
7153 | rejects an incoming request by sending @code{GNUNET_SERVICE_SETI_REJECT} | 7153 | rejects 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 | ||
7412 | Each listener also requires a seperate client connection. By sending the | 7412 | Each 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 |
7414 | of the application id and operation type it is interested in. A client | 7414 | of the application id and operation type it is interested in. A client |
7415 | rejects an incoming request by sending @code{GNUNET_SERVICE_SETU_REJECT} | 7415 | rejects an incoming request by sending @code{GNUNET_SERVICE_SETU_REJECT} |
@@ -7832,7 +7832,7 @@ performance). | |||
7832 | Third, an optional Bloom filter can be specified to exclude known results; | 7832 | Third, an optional Bloom filter can be specified to exclude known results; |
7833 | replies that hash to the bits set in the Bloom filter are considered | 7833 | replies that hash to the bits set in the Bloom filter are considered |
7834 | invalid. False-positives can be eliminated by sending the same query | 7834 | invalid. False-positives can be eliminated by sending the same query |
7835 | again with a different Bloom filter mutator value, which parameterizes | 7835 | again with a different Bloom filter mutator value, which parametrizes |
7836 | the hash function that is used. | 7836 | the hash function that is used. |
7837 | Finally, an optional application-specific "eXtended query" (xquery) can | 7837 | Finally, an optional application-specific "eXtended query" (xquery) can |
7838 | be specified to further constrain the results. It is entirely up to | 7838 | be 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 |
9031 | given public key is still valid, or if it has been revoked. | 9031 | given public key is still valid, or if it has been revoked. |
9032 | 9032 | ||
9033 | The second possible interaction is for a client to revoke a key by | 9033 | The second possible interaction is for a client to revoke a key by passing a |
9034 | passing a @code{RevokeMessage} to the service. The @code{RevokeMessage} | 9034 | @code{RevokeMessage} to the service. The @code{RevokeMessage} contains the |
9035 | contains the ECDSA public key to be revoked, a signature by the | 9035 | ECDSA public key to be revoked, a signature by the corresponding private key |
9036 | corresponding private key and the proof-of-work, The service responds | 9036 | and the proof-of-work. The service responds with a |
9037 | with a @code{RevocationResponseMessage} which can be used to indicate | 9037 | @code{RevocationResponseMessage} which can be used to indicate that the |
9038 | that 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 |
9039 | or otherwise indicates that the revocation has been processed | 9039 | otherwise to indicate that the revocation has been processed successfully. |
9040 | successfully. | ||
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 | |||
9715 | in-order delivery of messages, while the same options are only advisory for | 9714 | in-order delivery of messages, while the same options are only advisory for |
9716 | TRANSPORT and CORE: they should try (using ACKs on unreliable communicators, | 9715 | TRANSPORT and CORE: they should try (using ACKs on unreliable communicators, |
9717 | not changing the message order themselves), but if messages are lost anyway | 9716 | not 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 |
9720 | different order) TRANSPORT and CORE do not have to correct this. Whether a | 9719 | different order) TRANSPORT and CORE do not have to correct this. Whether a |
9721 | preference is strict or loose is thus dened by the respective layer. | 9720 | preference is strict or loose is thus dened by the respective layer. |
9722 | 9721 | ||
@@ -9728,8 +9727,8 @@ The API for communicators is defined in | |||
9728 | Each communicator must specify its (global) communication characteristics, which | 9727 | Each communicator must specify its (global) communication characteristics, which |
9729 | for now only say whether the communication is reliable (e.g. TCP, HTTPS) or | 9728 | for now only say whether the communication is reliable (e.g. TCP, HTTPS) or |
9730 | unreliable (e.g. UDP, WLAN). Each communicator must specify a unique address | 9729 | unreliable (e.g. UDP, WLAN). Each communicator must specify a unique address |
9731 | prex, or NULL if the communicator cannot establish outgoing connections (i.e. | 9730 | prex, or NULL if the communicator cannot establish outgoing connections |
9732 | is only acting as a TCP server). | 9731 | (for example because it is only acting as a TCP server). |
9733 | A communicator must tell TRANSPORT which addresses it is reachable under. | 9732 | A communicator must tell TRANSPORT which addresses it is reachable under. |
9734 | Addresses may be added or removed at any time. A communicator may have zero | 9733 | Addresses may be added or removed at any time. A communicator may have zero |
9735 | addresses (transmission only). | 9734 | addresses (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 | ||
9978 | A member session is a triple of the room key, the member ID and the public key | 9977 | A member session is a triple of the room key, the member ID and the public key |
9979 | of the member's ego. Member sessions allow that a member can change their ID or | 9978 | of the member's ego. Member sessions allow that a member can change their ID or |
9980 | their ego once at a time without loosing the ability to delete old messages or | 9979 | their ego once at a time without losing the ability to delete old messages or |
9981 | identifying the original sender of a message. On every change of ID or EGO a | 9980 | identifying the original sender of a message. On every change of ID or EGO a |
9982 | session will be marked as closed. So every session chain will only contain one | 9981 | session will be marked as closed. So every session chain will only contain one |
9983 | open session with the current ID and public key. | 9982 | open session with the current ID and public key. |