diff options
Diffstat (limited to 'doc/handbook/chapters/developer.texi')
-rw-r--r-- | doc/handbook/chapters/developer.texi | 443 |
1 files changed, 230 insertions, 213 deletions
diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi index cd81fcfb7..6c426ebad 100644 --- a/doc/handbook/chapters/developer.texi +++ b/doc/handbook/chapters/developer.texi | |||
@@ -202,7 +202,8 @@ Gtk+-based user interfaces, including: | |||
202 | @item @command{gnunet-statistics-gtk} (statistics over time), | 202 | @item @command{gnunet-statistics-gtk} (statistics over time), |
203 | @item @command{gnunet-peerinfo-gtk} | 203 | @item @command{gnunet-peerinfo-gtk} |
204 | (information about current connections and known peers), | 204 | (information about current connections and known peers), |
205 | @item @command{gnunet-chat-gtk} (chat GUI) and | 205 | @item @command{gnunet-namestore-gtk} (GNS record editor), |
206 | @item @command{gnunet-conversation-gtk} (voice chat GUI) and | ||
206 | @item @command{gnunet-setup} (setup tool for "everything") | 207 | @item @command{gnunet-setup} (setup tool for "everything") |
207 | @end itemize | 208 | @end itemize |
208 | 209 | ||
@@ -2176,7 +2177,7 @@ work): | |||
2176 | @example | 2177 | @example |
2177 | export PYPI=@value{PYPI-URL} | 2178 | export PYPI=@value{PYPI-URL} |
2178 | wget $PYPI/z/zope.interface/zope.interface-3.8.0.tar.gz | 2179 | wget $PYPI/z/zope.interface/zope.interface-3.8.0.tar.gz |
2179 | tar zvfz zope.interface-3.8.0.tar.gz | 2180 | tar xzvf zope.interface-3.8.0.tar.gz |
2180 | cd zope.interface-3.8.0 | 2181 | cd zope.interface-3.8.0 |
2181 | sudo python setup.py install | 2182 | sudo python setup.py install |
2182 | @end example | 2183 | @end example |
@@ -2401,10 +2402,11 @@ the program at various levels. | |||
2401 | @file{gnunet_common.h} defines several @strong{log levels}: | 2402 | @file{gnunet_common.h} defines several @strong{log levels}: |
2402 | @table @asis | 2403 | @table @asis |
2403 | 2404 | ||
2404 | @item ERROR for errors (really problematic situations, often leading to | 2405 | @item ERROR for errors |
2405 | crashes) | 2406 | (really problematic situations, often leading to crashes) |
2406 | @item WARNING for warnings (troubling situations that might have | 2407 | @item WARNING for warnings |
2407 | negative consequences, although not fatal) | 2408 | (troubling situations that might have negative consequences, although |
2409 | not fatal) | ||
2408 | @item INFO for various information. | 2410 | @item INFO for various information. |
2409 | Used somewhat rarely, as GNUnet statistics is used to hold and display | 2411 | Used somewhat rarely, as GNUnet statistics is used to hold and display |
2410 | most of the information that users might find interesting. | 2412 | most of the information that users might find interesting. |
@@ -2830,7 +2832,7 @@ which both ensure correct alignment when sending structs over the network. | |||
2830 | @c *********************************************************************** | 2832 | @c *********************************************************************** |
2831 | @node Client - Establish connection | 2833 | @node Client - Establish connection |
2832 | @subsubsection Client - Establish connection | 2834 | @subsubsection Client - Establish connection |
2833 | @c %**end of header | 2835 | |
2834 | 2836 | ||
2835 | 2837 | ||
2836 | At first, on the client side, the underlying API is employed to create a | 2838 | At first, on the client side, the underlying API is employed to create a |
@@ -2845,7 +2847,7 @@ client = GNUNET_CLIENT_connect ("transport", cfg); | |||
2845 | @c *********************************************************************** | 2847 | @c *********************************************************************** |
2846 | @node Client - Initialize request message | 2848 | @node Client - Initialize request message |
2847 | @subsubsection Client - Initialize request message | 2849 | @subsubsection Client - Initialize request message |
2848 | @c %**end of header | 2850 | |
2849 | 2851 | ||
2850 | When the connection is ready, we initialize the message. In this step, | 2852 | When the connection is ready, we initialize the message. In this step, |
2851 | all the fields of the message should be properly initialized, namely the | 2853 | all the fields of the message should be properly initialized, namely the |
@@ -2878,7 +2880,7 @@ Big Endian and Little Endian. | |||
2878 | @c *********************************************************************** | 2880 | @c *********************************************************************** |
2879 | @node Client - Send request and receive response | 2881 | @node Client - Send request and receive response |
2880 | @subsubsection Client - Send request and receive response | 2882 | @subsubsection Client - Send request and receive response |
2881 | @c %**end of header | 2883 | |
2882 | 2884 | ||
2883 | @b{FIXME: This is very outdated, see the tutorial for the current API!} | 2885 | @b{FIXME: This is very outdated, see the tutorial for the current API!} |
2884 | 2886 | ||
@@ -2913,7 +2915,7 @@ int main(int argc, char**argv) @{ | |||
2913 | @c *********************************************************************** | 2915 | @c *********************************************************************** |
2914 | @node Server - Add new handles for specified messages | 2916 | @node Server - Add new handles for specified messages |
2915 | @subsubsection Server - Add new handles for specified messages | 2917 | @subsubsection Server - Add new handles for specified messages |
2916 | @c %**end of header | 2918 | |
2917 | 2919 | ||
2918 | in the function above the argument @code{run} is used to initiate | 2920 | in the function above the argument @code{run} is used to initiate |
2919 | transport service,and defined like this: | 2921 | transport service,and defined like this: |
@@ -2971,7 +2973,7 @@ depicted as @code{@{NULL, NULL, 0, 0@}} is set in the last area. | |||
2971 | @c *********************************************************************** | 2973 | @c *********************************************************************** |
2972 | @node Server - Process request message | 2974 | @node Server - Process request message |
2973 | @subsubsection Server - Process request message | 2975 | @subsubsection Server - Process request message |
2974 | @c %**end of header | 2976 | |
2975 | 2977 | ||
2976 | After the initialization of transport service, the request message would | 2978 | After the initialization of transport service, the request message would |
2977 | be processed. Before handling the main message data, the validity of this | 2979 | be processed. Before handling the main message data, the validity of this |
@@ -3022,7 +3024,7 @@ message. | |||
3022 | @c *********************************************************************** | 3024 | @c *********************************************************************** |
3023 | @node Server - Response to client | 3025 | @node Server - Response to client |
3024 | @subsubsection Server - Response to client | 3026 | @subsubsection Server - Response to client |
3025 | @c %**end of header | 3027 | |
3026 | 3028 | ||
3027 | Once the processing of current request is done, the server should give the | 3029 | Once the processing of current request is done, the server should give the |
3028 | response to the client. A new @code{struct AddressLookupMessage} would be | 3030 | response to the client. A new @code{struct AddressLookupMessage} would be |
@@ -3058,7 +3060,7 @@ to send the message. | |||
3058 | @c *********************************************************************** | 3060 | @c *********************************************************************** |
3059 | @node Server - Notification of clients | 3061 | @node Server - Notification of clients |
3060 | @subsubsection Server - Notification of clients | 3062 | @subsubsection Server - Notification of clients |
3061 | @c %**end of header | 3063 | |
3062 | 3064 | ||
3063 | Often a service needs to (repeatedly) transmit notifications to a client | 3065 | Often a service needs to (repeatedly) transmit notifications to a client |
3064 | or a group of clients. In these cases, the client typically has once | 3066 | or a group of clients. In these cases, the client typically has once |
@@ -3087,7 +3089,7 @@ messages to the server. | |||
3087 | @node Conversion between Network Byte Order (Big Endian) and Host Byte Order | 3089 | @node Conversion between Network Byte Order (Big Endian) and Host Byte Order |
3088 | @subsubsection Conversion between Network Byte Order (Big Endian) and Host Byte Order | 3090 | @subsubsection Conversion between Network Byte Order (Big Endian) and Host Byte Order |
3089 | @c %** subsub? it's a referenced page on the ipc document. | 3091 | @c %** subsub? it's a referenced page on the ipc document. |
3090 | @c %**end of header | 3092 | |
3091 | 3093 | ||
3092 | Here we can simply comprehend big endian and little endian as Network Byte | 3094 | Here we can simply comprehend big endian and little endian as Network Byte |
3093 | Order and Host Byte Order respectively. What is the difference between | 3095 | Order and Host Byte Order respectively. What is the difference between |
@@ -3143,7 +3145,7 @@ byte order. | |||
3143 | @cindex Cryptography API | 3145 | @cindex Cryptography API |
3144 | @node Cryptography API | 3146 | @node Cryptography API |
3145 | @subsection Cryptography API | 3147 | @subsection Cryptography API |
3146 | @c %**end of header | 3148 | |
3147 | 3149 | ||
3148 | The gnunetutil APIs provides the cryptographic primitives used in GNUnet. | 3150 | The gnunetutil APIs provides the cryptographic primitives used in GNUnet. |
3149 | GNUnet uses 2048 bit RSA keys for the session key exchange and for signing | 3151 | GNUnet uses 2048 bit RSA keys for the session key exchange and for signing |
@@ -3180,7 +3182,7 @@ should be considered secure for traditional applications of RSA. | |||
3180 | @cindex Message Queue API | 3182 | @cindex Message Queue API |
3181 | @node Message Queue API | 3183 | @node Message Queue API |
3182 | @subsection Message Queue API | 3184 | @subsection Message Queue API |
3183 | @c %**end of header | 3185 | |
3184 | 3186 | ||
3185 | @strong{ Introduction }@ | 3187 | @strong{ Introduction }@ |
3186 | Often, applications need to queue messages that | 3188 | Often, applications need to queue messages that |
@@ -3324,7 +3326,7 @@ callback. When canceling an envelope, it is not necessary@ to call | |||
3324 | @cindex Service API | 3326 | @cindex Service API |
3325 | @node Service API | 3327 | @node Service API |
3326 | @subsection Service API | 3328 | @subsection Service API |
3327 | @c %**end of header | 3329 | |
3328 | 3330 | ||
3329 | Most GNUnet code lives in the form of services. Services are processes | 3331 | Most GNUnet code lives in the form of services. Services are processes |
3330 | that offer an API for other components of the system to build on. Those | 3332 | that offer an API for other components of the system to build on. Those |
@@ -3400,7 +3402,7 @@ clients to set (possibly persistent) statistic values before terminating. | |||
3400 | @c *********************************************************************** | 3402 | @c *********************************************************************** |
3401 | @node Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps | 3403 | @node Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps |
3402 | @subsection Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps | 3404 | @subsection Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps |
3403 | @c %**end of header | 3405 | |
3404 | 3406 | ||
3405 | A commonly used data structure in GNUnet is a (multi-)hash map. It is most | 3407 | A commonly used data structure in GNUnet is a (multi-)hash map. It is most |
3406 | often used to map a peer identity to some data structure, but also to map | 3408 | often used to map a peer identity to some data structure, but also to map |
@@ -3424,7 +3426,7 @@ the hash map. | |||
3424 | 3426 | ||
3425 | @node Analysis | 3427 | @node Analysis |
3426 | @subsubsection Analysis | 3428 | @subsubsection Analysis |
3427 | @c %**end of header | 3429 | |
3428 | 3430 | ||
3429 | The main reason for the "excessive" memory consumption by the hash map is | 3431 | The main reason for the "excessive" memory consumption by the hash map is |
3430 | that GNUnet uses 512-bit cryptographic hash codes --- and the | 3432 | that GNUnet uses 512-bit cryptographic hash codes --- and the |
@@ -3475,7 +3477,7 @@ we tend to really try to keep the entries small. | |||
3475 | @c *********************************************************************** | 3477 | @c *********************************************************************** |
3476 | @node Solution | 3478 | @node Solution |
3477 | @subsubsection Solution | 3479 | @subsubsection Solution |
3478 | @c %**end of header | 3480 | |
3479 | 3481 | ||
3480 | The solution that has now been implemented is to @strong{optionally} | 3482 | The solution that has now been implemented is to @strong{optionally} |
3481 | allow the hash map to not make a (deep) copy of the hash but instead have | 3483 | allow the hash map to not make a (deep) copy of the hash but instead have |
@@ -3493,7 +3495,7 @@ pointer and undefined behavior of the (multi-)hash map API. | |||
3493 | @c *********************************************************************** | 3495 | @c *********************************************************************** |
3494 | @node Migration | 3496 | @node Migration |
3495 | @subsubsection Migration | 3497 | @subsubsection Migration |
3496 | @c %**end of header | 3498 | |
3497 | 3499 | ||
3498 | To use the new feature, first check that the values contain the respective | 3500 | To use the new feature, first check that the values contain the respective |
3499 | key (and never modify it). Then, all calls to | 3501 | key (and never modify it). Then, all calls to |
@@ -3542,7 +3544,7 @@ removed from the map, undefined behavior is likely to be observed. | |||
3542 | @c *********************************************************************** | 3544 | @c *********************************************************************** |
3543 | @node Conclusion | 3545 | @node Conclusion |
3544 | @subsubsection Conclusion | 3546 | @subsubsection Conclusion |
3545 | @c %**end of header | 3547 | |
3546 | 3548 | ||
3547 | The new optimization can is often applicable and can result in a | 3549 | The new optimization can is often applicable and can result in a |
3548 | reduction in memory consumption of up to 30% in practice. However, it | 3550 | reduction in memory consumption of up to 30% in practice. However, it |
@@ -3555,10 +3557,11 @@ at least until benchmarks exist). | |||
3555 | @c *********************************************************************** | 3557 | @c *********************************************************************** |
3556 | @node Availability | 3558 | @node Availability |
3557 | @subsubsection Availability | 3559 | @subsubsection Availability |
3558 | @c %**end of header | ||
3559 | 3560 | ||
3560 | The new multi hash map code was committed in SVN 24319 (will be in GNUnet | 3561 | |
3561 | 0.9.4). Various subsystems (transport, core, dht, file-sharing) were | 3562 | The new multi hash map code was committed in SVN 24319 (which made its |
3563 | way into GNUnet version 0.9.4). | ||
3564 | Various subsystems (transport, core, dht, file-sharing) were | ||
3562 | previously audited and modified to take advantage of the new capability. | 3565 | previously audited and modified to take advantage of the new capability. |
3563 | In particular, memory consumption of the file-sharing service is expected | 3566 | In particular, memory consumption of the file-sharing service is expected |
3564 | to drop by 20-30% due to this change. | 3567 | to drop by 20-30% due to this change. |
@@ -3567,7 +3570,7 @@ to drop by 20-30% due to this change. | |||
3567 | @cindex CONTAINER_MDLL API | 3570 | @cindex CONTAINER_MDLL API |
3568 | @node CONTAINER_MDLL API | 3571 | @node CONTAINER_MDLL API |
3569 | @subsection CONTAINER_MDLL API | 3572 | @subsection CONTAINER_MDLL API |
3570 | @c %**end of header | 3573 | |
3571 | 3574 | ||
3572 | This text documents the GNUNET_CONTAINER_MDLL API. The | 3575 | This text documents the GNUNET_CONTAINER_MDLL API. The |
3573 | GNUNET_CONTAINER_MDLL API is similar to the GNUNET_CONTAINER_DLL API in | 3576 | GNUNET_CONTAINER_MDLL API is similar to the GNUNET_CONTAINER_DLL API in |
@@ -3633,7 +3636,7 @@ Iterating over the list should be done by directly accessing the | |||
3633 | @cindex ARM | 3636 | @cindex ARM |
3634 | @node Automatic Restart Manager (ARM) | 3637 | @node Automatic Restart Manager (ARM) |
3635 | @section Automatic Restart Manager (ARM) | 3638 | @section Automatic Restart Manager (ARM) |
3636 | @c %**end of header | 3639 | |
3637 | 3640 | ||
3638 | GNUnet's Automated Restart Manager (ARM) is the GNUnet service responsible | 3641 | GNUnet's Automated Restart Manager (ARM) is the GNUnet service responsible |
3639 | for system initialization and service babysitting. ARM starts and halts | 3642 | for system initialization and service babysitting. ARM starts and halts |
@@ -3654,7 +3657,7 @@ about how ARM works and how to interact with it. | |||
3654 | @c *********************************************************************** | 3657 | @c *********************************************************************** |
3655 | @node Basic functionality | 3658 | @node Basic functionality |
3656 | @subsection Basic functionality | 3659 | @subsection Basic functionality |
3657 | @c %**end of header | 3660 | |
3658 | 3661 | ||
3659 | @itemize @bullet | 3662 | @itemize @bullet |
3660 | @item ARM source code can be found under "src/arm".@ Service processes are | 3663 | @item ARM source code can be found under "src/arm".@ Service processes are |
@@ -3678,7 +3681,7 @@ it to start a service "resolver", stops the "resolver" then stops "ARM". | |||
3678 | @c *********************************************************************** | 3681 | @c *********************************************************************** |
3679 | @node Key configuration options | 3682 | @node Key configuration options |
3680 | @subsection Key configuration options | 3683 | @subsection Key configuration options |
3681 | @c %**end of header | 3684 | |
3682 | 3685 | ||
3683 | Configurations for ARM and services should be available in a .conf file | 3686 | Configurations for ARM and services should be available in a .conf file |
3684 | (As an example, see test_arm_api_data.conf). When running ARM, the | 3687 | (As an example, see test_arm_api_data.conf). When running ARM, the |
@@ -3747,7 +3750,7 @@ services that are going to run. | |||
3747 | @c *********************************************************************** | 3750 | @c *********************************************************************** |
3748 | @node ARM - Availability | 3751 | @node ARM - Availability |
3749 | @subsection ARM - Availability | 3752 | @subsection ARM - Availability |
3750 | @c %**end of header | 3753 | |
3751 | 3754 | ||
3752 | As mentioned before, one of the features provided by ARM is starting | 3755 | As mentioned before, one of the features provided by ARM is starting |
3753 | services on demand. Consider the example of one service "client" that | 3756 | services on demand. Consider the example of one service "client" that |
@@ -3835,7 +3838,7 @@ problematic service. | |||
3835 | @cindex TRANSPORT Subsystem | 3838 | @cindex TRANSPORT Subsystem |
3836 | @node TRANSPORT Subsystem | 3839 | @node TRANSPORT Subsystem |
3837 | @section TRANSPORT Subsystem | 3840 | @section TRANSPORT Subsystem |
3838 | @c %**end of header | 3841 | |
3839 | 3842 | ||
3840 | This chapter documents how the GNUnet transport subsystem works. The | 3843 | This chapter documents how the GNUnet transport subsystem works. The |
3841 | GNUnet transport subsystem consists of three main components: the | 3844 | GNUnet transport subsystem consists of three main components: the |
@@ -3893,7 +3896,7 @@ transport service. | |||
3893 | 3896 | ||
3894 | @node Address validation protocol | 3897 | @node Address validation protocol |
3895 | @subsection Address validation protocol | 3898 | @subsection Address validation protocol |
3896 | @c %**end of header | 3899 | |
3897 | 3900 | ||
3898 | This section documents how the GNUnet transport service validates | 3901 | This section documents how the GNUnet transport service validates |
3899 | connections with other peers. It is a high-level description of the | 3902 | connections with other peers. It is a high-level description of the |
@@ -3956,7 +3959,7 @@ implementation details). | |||
3956 | @cindex NAT library | 3959 | @cindex NAT library |
3957 | @node NAT library | 3960 | @node NAT library |
3958 | @section NAT library | 3961 | @section NAT library |
3959 | @c %**end of header | 3962 | |
3960 | 3963 | ||
3961 | The goal of the GNUnet NAT library is to provide a general-purpose API for | 3964 | The goal of the GNUnet NAT library is to provide a general-purpose API for |
3962 | NAT traversal @strong{without} third-party support. So protocols that | 3965 | NAT traversal @strong{without} third-party support. So protocols that |
@@ -4003,7 +4006,7 @@ This way, it is easy to test if the current NAT configuration is valid. | |||
4003 | 4006 | ||
4004 | @node Distance-Vector plugin | 4007 | @node Distance-Vector plugin |
4005 | @section Distance-Vector plugin | 4008 | @section Distance-Vector plugin |
4006 | @c %**end of header | 4009 | |
4007 | 4010 | ||
4008 | The Distance Vector (DV) transport is a transport mechanism that allows | 4011 | The Distance Vector (DV) transport is a transport mechanism that allows |
4009 | peers to act as relays for each other, thereby connecting peers that would | 4012 | peers to act as relays for each other, thereby connecting peers that would |
@@ -4072,7 +4075,8 @@ message, and delivers it to Carol as though it came directly from Alice. | |||
4072 | @cindex SMTP plugin | 4075 | @cindex SMTP plugin |
4073 | @node SMTP plugin | 4076 | @node SMTP plugin |
4074 | @section SMTP plugin | 4077 | @section SMTP plugin |
4075 | @c %**end of header | 4078 | |
4079 | @c TODO: Update! | ||
4076 | 4080 | ||
4077 | This section describes the new SMTP transport plugin for GNUnet as it | 4081 | This section describes the new SMTP transport plugin for GNUnet as it |
4078 | exists in the 0.7.x and 0.8.x branch. SMTP support is currently not | 4082 | exists in the 0.7.x and 0.8.x branch. SMTP support is currently not |
@@ -4080,6 +4084,9 @@ available in GNUnet 0.9.x. This page also describes the transport layer | |||
4080 | abstraction (as it existed in 0.7.x and 0.8.x) in more detail and gives | 4084 | abstraction (as it existed in 0.7.x and 0.8.x) in more detail and gives |
4081 | some benchmarking results. The performance results presented are quite | 4085 | some benchmarking results. The performance results presented are quite |
4082 | old and maybe outdated at this point. | 4086 | old and maybe outdated at this point. |
4087 | For the readers in the year 2019, you will notice by the mention of | ||
4088 | version 0.7, 0.8, and 0.9 that this section has to be taken with your | ||
4089 | usual grain of salt and be updated eventually. | ||
4083 | 4090 | ||
4084 | @itemize @bullet | 4091 | @itemize @bullet |
4085 | @item Why use SMTP for a peer-to-peer transport? | 4092 | @item Why use SMTP for a peer-to-peer transport? |
@@ -4101,7 +4108,7 @@ old and maybe outdated at this point. | |||
4101 | 4108 | ||
4102 | @node Why use SMTP for a peer-to-peer transport? | 4109 | @node Why use SMTP for a peer-to-peer transport? |
4103 | @subsection Why use SMTP for a peer-to-peer transport? | 4110 | @subsection Why use SMTP for a peer-to-peer transport? |
4104 | @c %**end of header | 4111 | |
4105 | 4112 | ||
4106 | There are many reasons why one would not want to use SMTP: | 4113 | There are many reasons why one would not want to use SMTP: |
4107 | 4114 | ||
@@ -4136,7 +4143,7 @@ type of situation. | |||
4136 | 4143 | ||
4137 | @node How does it work? | 4144 | @node How does it work? |
4138 | @subsection How does it work? | 4145 | @subsection How does it work? |
4139 | @c %**end of header | 4146 | |
4140 | 4147 | ||
4141 | When a GNUnet peer needs to send a message to another GNUnet peer that has | 4148 | When a GNUnet peer needs to send a message to another GNUnet peer that has |
4142 | advertised (only) an SMTP transport address, GNUnet base64-encodes the | 4149 | advertised (only) an SMTP transport address, GNUnet base64-encodes the |
@@ -4149,7 +4156,7 @@ GNUnet E-mail messages by searching for a generic filter. | |||
4149 | 4156 | ||
4150 | @node How do I configure my peer? | 4157 | @node How do I configure my peer? |
4151 | @subsection How do I configure my peer? | 4158 | @subsection How do I configure my peer? |
4152 | @c %**end of header | 4159 | |
4153 | 4160 | ||
4154 | First, you need to configure @code{procmail} to filter your inbound E-mail | 4161 | First, you need to configure @code{procmail} to filter your inbound E-mail |
4155 | for GNUnet traffic. The GNUnet messages must be delivered into a pipe, for | 4162 | for GNUnet traffic. The GNUnet messages must be delivered into a pipe, for |
@@ -4194,7 +4201,7 @@ This should be it, but you may probably want to test it first. | |||
4194 | 4201 | ||
4195 | @node How do I test if it works? | 4202 | @node How do I test if it works? |
4196 | @subsection How do I test if it works? | 4203 | @subsection How do I test if it works? |
4197 | @c %**end of header | 4204 | |
4198 | 4205 | ||
4199 | Any transport can be subjected to some rudimentary tests using the | 4206 | Any transport can be subjected to some rudimentary tests using the |
4200 | @code{gnunet-transport-check} tool. The tool sends a message to the local | 4207 | @code{gnunet-transport-check} tool. The tool sends a message to the local |
@@ -4217,7 +4224,7 @@ to send and receive messages. | |||
4217 | 4224 | ||
4218 | @node How fast is it? | 4225 | @node How fast is it? |
4219 | @subsection How fast is it? | 4226 | @subsection How fast is it? |
4220 | @c %**end of header | 4227 | |
4221 | 4228 | ||
4222 | We have measured the performance of the UDP, TCP and SMTP transport layer | 4229 | We have measured the performance of the UDP, TCP and SMTP transport layer |
4223 | directly and when used from an application using the GNUnet core. | 4230 | directly and when used from an application using the GNUnet core. |
@@ -4284,7 +4291,7 @@ benchmarking results. | |||
4284 | @cindex Bluetooth plugin | 4291 | @cindex Bluetooth plugin |
4285 | @node Bluetooth plugin | 4292 | @node Bluetooth plugin |
4286 | @section Bluetooth plugin | 4293 | @section Bluetooth plugin |
4287 | @c %**end of header | 4294 | |
4288 | 4295 | ||
4289 | This page describes the new Bluetooth transport plugin for GNUnet. The | 4296 | This page describes the new Bluetooth transport plugin for GNUnet. The |
4290 | plugin is still in the testing stage so don't expect it to work | 4297 | plugin is still in the testing stage so don't expect it to work |
@@ -4310,7 +4317,7 @@ ask on the IRC channel. | |||
4310 | 4317 | ||
4311 | @node What do I need to use the Bluetooth plugin transport? | 4318 | @node What do I need to use the Bluetooth plugin transport? |
4312 | @subsection What do I need to use the Bluetooth plugin transport? | 4319 | @subsection What do I need to use the Bluetooth plugin transport? |
4313 | @c %**end of header | 4320 | |
4314 | 4321 | ||
4315 | If you are a GNU/Linux user and you want to use the Bluetooth | 4322 | If you are a GNU/Linux user and you want to use the Bluetooth |
4316 | transport plugin you should install the | 4323 | transport plugin you should install the |
@@ -4337,7 +4344,7 @@ protocol so we cannot turn on your device programatically! | |||
4337 | @c FIXME: Change to unique title | 4344 | @c FIXME: Change to unique title |
4338 | @node How does it work2? | 4345 | @node How does it work2? |
4339 | @subsection How does it work2? | 4346 | @subsection How does it work2? |
4340 | @c %**end of header | 4347 | |
4341 | 4348 | ||
4342 | The Bluetooth transport plugin uses virtually the same code as the WLAN | 4349 | The Bluetooth transport plugin uses virtually the same code as the WLAN |
4343 | plugin and only the helper binary is different. The helper takes a single | 4350 | plugin and only the helper binary is different. The helper takes a single |
@@ -4367,7 +4374,7 @@ discovery. | |||
4367 | 4374 | ||
4368 | @node What possible errors should I be aware of? | 4375 | @node What possible errors should I be aware of? |
4369 | @subsection What possible errors should I be aware of? | 4376 | @subsection What possible errors should I be aware of? |
4370 | @c %**end of header | 4377 | |
4371 | 4378 | ||
4372 | @emph{This section is dedicated for GNU/Linux users} | 4379 | @emph{This section is dedicated for GNU/Linux users} |
4373 | 4380 | ||
@@ -4406,7 +4413,7 @@ the device and to send some particular commands to it. | |||
4406 | @c FIXME: A more unique name | 4413 | @c FIXME: A more unique name |
4407 | @node How do I configure my peer2? | 4414 | @node How do I configure my peer2? |
4408 | @subsection How do I configure my peer2? | 4415 | @subsection How do I configure my peer2? |
4409 | @c %**end of header | 4416 | |
4410 | 4417 | ||
4411 | On GNU/Linux, you just have to be sure that the interface name | 4418 | On GNU/Linux, you just have to be sure that the interface name |
4412 | corresponds to the one that you want to use. | 4419 | corresponds to the one that you want to use. |
@@ -4440,7 +4447,7 @@ transport service. | |||
4440 | 4447 | ||
4441 | @node How can I test it? | 4448 | @node How can I test it? |
4442 | @subsection How can I test it? | 4449 | @subsection How can I test it? |
4443 | @c %**end of header | 4450 | |
4444 | 4451 | ||
4445 | If you have two Bluetooth devices on the same machine and you are using | 4452 | If you have two Bluetooth devices on the same machine and you are using |
4446 | GNU/Linux you must: | 4453 | GNU/Linux you must: |
@@ -4487,7 +4494,7 @@ transport service. | |||
4487 | 4494 | ||
4488 | @node The implementation of the Bluetooth transport plugin | 4495 | @node The implementation of the Bluetooth transport plugin |
4489 | @subsection The implementation of the Bluetooth transport plugin | 4496 | @subsection The implementation of the Bluetooth transport plugin |
4490 | @c %**end of header | 4497 | |
4491 | 4498 | ||
4492 | This page describes the implementation of the Bluetooth transport plugin. | 4499 | This page describes the implementation of the Bluetooth transport plugin. |
4493 | 4500 | ||
@@ -4521,7 +4528,7 @@ platforms. | |||
4521 | 4528 | ||
4522 | @node Linux functionality | 4529 | @node Linux functionality |
4523 | @subsubsection Linux functionality | 4530 | @subsubsection Linux functionality |
4524 | @c %**end of header | 4531 | |
4525 | 4532 | ||
4526 | In order to implement the plugin functionality on GNU/Linux I | 4533 | In order to implement the plugin functionality on GNU/Linux I |
4527 | used the BlueZ stack. | 4534 | used the BlueZ stack. |
@@ -4617,7 +4624,7 @@ support for @strong{broadcast messages}.} | |||
4617 | 4624 | ||
4618 | @node Details about the broadcast implementation | 4625 | @node Details about the broadcast implementation |
4619 | @subsubsection Details about the broadcast implementation | 4626 | @subsubsection Details about the broadcast implementation |
4620 | @c %**end of header | 4627 | |
4621 | 4628 | ||
4622 | First I want to point out that the broadcast functionality for the CONTROL | 4629 | First I want to point out that the broadcast functionality for the CONTROL |
4623 | messages is not implemented in a conventional way. Since the inquiry scan | 4630 | messages is not implemented in a conventional way. Since the inquiry scan |
@@ -4664,7 +4671,7 @@ simply use the socket. | |||
4664 | 4671 | ||
4665 | @node Windows functionality | 4672 | @node Windows functionality |
4666 | @subsubsection Windows functionality | 4673 | @subsubsection Windows functionality |
4667 | @c %**end of header | 4674 | |
4668 | 4675 | ||
4669 | For Windows I decided to use the Microsoft Bluetooth stack which has the | 4676 | For Windows I decided to use the Microsoft Bluetooth stack which has the |
4670 | advantage of coming standard from Windows XP SP2. The main disadvantage is | 4677 | advantage of coming standard from Windows XP SP2. The main disadvantage is |
@@ -4719,7 +4726,7 @@ broadcast messages. When it receives a broadcast message it will skip it. | |||
4719 | 4726 | ||
4720 | @node Pending features | 4727 | @node Pending features |
4721 | @subsubsection Pending features | 4728 | @subsubsection Pending features |
4722 | @c %**end of header | 4729 | |
4723 | 4730 | ||
4724 | @itemize @bullet | 4731 | @itemize @bullet |
4725 | @item Implement the broadcast functionality on Windows @emph{(currently | 4732 | @item Implement the broadcast functionality on Windows @emph{(currently |
@@ -4735,7 +4742,7 @@ contact me. | |||
4735 | 4742 | ||
4736 | @node WLAN plugin | 4743 | @node WLAN plugin |
4737 | @section WLAN plugin | 4744 | @section WLAN plugin |
4738 | @c %**end of header | 4745 | |
4739 | 4746 | ||
4740 | This section documents how the wlan transport plugin works. Parts which | 4747 | This section documents how the wlan transport plugin works. Parts which |
4741 | are not implemented yet or could be better implemented are described at | 4748 | are not implemented yet or could be better implemented are described at |
@@ -4744,7 +4751,7 @@ the end. | |||
4744 | @cindex ATS Subsystem | 4751 | @cindex ATS Subsystem |
4745 | @node ATS Subsystem | 4752 | @node ATS Subsystem |
4746 | @section ATS Subsystem | 4753 | @section ATS Subsystem |
4747 | @c %**end of header | 4754 | |
4748 | 4755 | ||
4749 | ATS stands for "automatic transport selection", and the function of ATS in | 4756 | ATS stands for "automatic transport selection", and the function of ATS in |
4750 | GNUnet is to decide on which address (and thus transport plugin) should | 4757 | GNUnet is to decide on which address (and thus transport plugin) should |
@@ -4767,7 +4774,7 @@ superior. | |||
4767 | @cindex CORE Subsystem | 4774 | @cindex CORE Subsystem |
4768 | @node CORE Subsystem | 4775 | @node CORE Subsystem |
4769 | @section CORE Subsystem | 4776 | @section CORE Subsystem |
4770 | @c %**end of header | 4777 | |
4771 | 4778 | ||
4772 | The CORE subsystem in GNUnet is responsible for securing link-layer | 4779 | The CORE subsystem in GNUnet is responsible for securing link-layer |
4773 | communications between nodes in the GNUnet overlay network. CORE builds | 4780 | communications between nodes in the GNUnet overlay network. CORE builds |
@@ -4811,7 +4818,7 @@ message counters and ephemeral keys) | |||
4811 | @cindex core subsystem limitations | 4818 | @cindex core subsystem limitations |
4812 | @node Limitations | 4819 | @node Limitations |
4813 | @subsection Limitations | 4820 | @subsection Limitations |
4814 | @c %**end of header | 4821 | |
4815 | 4822 | ||
4816 | CORE does not perform | 4823 | CORE does not perform |
4817 | @uref{http://en.wikipedia.org/wiki/Routing, routing}; using CORE it is | 4824 | @uref{http://en.wikipedia.org/wiki/Routing, routing}; using CORE it is |
@@ -4845,7 +4852,7 @@ control is needed, applications should use the CADET service. | |||
4845 | @cindex when is a peer connected | 4852 | @cindex when is a peer connected |
4846 | @node When is a peer "connected"? | 4853 | @node When is a peer "connected"? |
4847 | @subsection When is a peer "connected"? | 4854 | @subsection When is a peer "connected"? |
4848 | @c %**end of header | 4855 | |
4849 | 4856 | ||
4850 | In addition to the security features mentioned above, CORE also provides | 4857 | In addition to the security features mentioned above, CORE also provides |
4851 | one additional key feature to applications using it, and that is a | 4858 | one additional key feature to applications using it, and that is a |
@@ -4878,7 +4885,7 @@ connection. | |||
4878 | @cindex libgnunetcore | 4885 | @cindex libgnunetcore |
4879 | @node libgnunetcore | 4886 | @node libgnunetcore |
4880 | @subsection libgnunetcore | 4887 | @subsection libgnunetcore |
4881 | @c %**end of header | 4888 | |
4882 | 4889 | ||
4883 | The CORE API (defined in @file{gnunet_core_service.h}) is the basic | 4890 | The CORE API (defined in @file{gnunet_core_service.h}) is the basic |
4884 | messaging API used by P2P applications built using GNUnet. It provides | 4891 | messaging API used by P2P applications built using GNUnet. It provides |
@@ -4943,7 +4950,7 @@ re-established, the applications will be receive matching connect events. | |||
4943 | @cindex core clinet-service protocol | 4950 | @cindex core clinet-service protocol |
4944 | @node The CORE Client-Service Protocol | 4951 | @node The CORE Client-Service Protocol |
4945 | @subsection The CORE Client-Service Protocol | 4952 | @subsection The CORE Client-Service Protocol |
4946 | @c %**end of header | 4953 | |
4947 | 4954 | ||
4948 | This section describes the protocol between an application using the CORE | 4955 | This section describes the protocol between an application using the CORE |
4949 | service (the client) and the CORE service process itself. | 4956 | service (the client) and the CORE service process itself. |
@@ -4957,7 +4964,7 @@ service (the client) and the CORE service process itself. | |||
4957 | 4964 | ||
4958 | @node Setup2 | 4965 | @node Setup2 |
4959 | @subsubsection Setup2 | 4966 | @subsubsection Setup2 |
4960 | @c %**end of header | 4967 | |
4961 | 4968 | ||
4962 | When a client connects to the CORE service, it first sends a | 4969 | When a client connects to the CORE service, it first sends a |
4963 | @code{InitMessage} which specifies options for the connection and a set of | 4970 | @code{InitMessage} which specifies options for the connection and a set of |
@@ -4986,7 +4993,7 @@ both CORE and the client can send messages. | |||
4986 | 4993 | ||
4987 | @node Notifications | 4994 | @node Notifications |
4988 | @subsubsection Notifications | 4995 | @subsubsection Notifications |
4989 | @c %**end of header | 4996 | |
4990 | 4997 | ||
4991 | The CORE will send @code{ConnectNotifyMessage}s and | 4998 | The CORE will send @code{ConnectNotifyMessage}s and |
4992 | @code{DisconnectNotifyMessage}s whenever peers connect or disconnect from | 4999 | @code{DisconnectNotifyMessage}s whenever peers connect or disconnect from |
@@ -5002,7 +5009,7 @@ identity given is that of the receiver. | |||
5002 | 5009 | ||
5003 | @node Sending | 5010 | @node Sending |
5004 | @subsubsection Sending | 5011 | @subsubsection Sending |
5005 | @c %**end of header | 5012 | |
5006 | 5013 | ||
5007 | When a client wants to transmit a message, it first requests a | 5014 | When a client wants to transmit a message, it first requests a |
5008 | transmission slot by sending a @code{SendMessageRequest} which specifies | 5015 | transmission slot by sending a @code{SendMessageRequest} which specifies |
@@ -5022,7 +5029,7 @@ for each request). | |||
5022 | @cindex CORE Peer-to-Peer Protocol | 5029 | @cindex CORE Peer-to-Peer Protocol |
5023 | @node The CORE Peer-to-Peer Protocol | 5030 | @node The CORE Peer-to-Peer Protocol |
5024 | @subsection The CORE Peer-to-Peer Protocol | 5031 | @subsection The CORE Peer-to-Peer Protocol |
5025 | @c %**end of header | 5032 | |
5026 | 5033 | ||
5027 | 5034 | ||
5028 | @menu | 5035 | @menu |
@@ -5035,7 +5042,7 @@ for each request). | |||
5035 | @cindex EphemeralKeyMessage creation | 5042 | @cindex EphemeralKeyMessage creation |
5036 | @node Creating the EphemeralKeyMessage | 5043 | @node Creating the EphemeralKeyMessage |
5037 | @subsubsection Creating the EphemeralKeyMessage | 5044 | @subsubsection Creating the EphemeralKeyMessage |
5038 | @c %**end of header | 5045 | |
5039 | 5046 | ||
5040 | When the CORE service starts, each peer creates a fresh ephemeral (ECC) | 5047 | When the CORE service starts, each peer creates a fresh ephemeral (ECC) |
5041 | public-private key pair and signs the corresponding | 5048 | public-private key pair and signs the corresponding |
@@ -5076,7 +5083,7 @@ connection using the new ephemeral key | |||
5076 | 5083 | ||
5077 | @node Establishing a connection | 5084 | @node Establishing a connection |
5078 | @subsubsection Establishing a connection | 5085 | @subsubsection Establishing a connection |
5079 | @c %**end of header | 5086 | |
5080 | 5087 | ||
5081 | Peers begin their interaction by sending a @code{EphemeralKeyMessage} to | 5088 | Peers begin their interaction by sending a @code{EphemeralKeyMessage} to |
5082 | the other peer once the TRANSPORT service notifies the CORE service about | 5089 | the other peer once the TRANSPORT service notifies the CORE service about |
@@ -5094,7 +5101,7 @@ connection to @code{KX_STATE_UP}. | |||
5094 | 5101 | ||
5095 | @node Encryption and Decryption | 5102 | @node Encryption and Decryption |
5096 | @subsubsection Encryption and Decryption | 5103 | @subsubsection Encryption and Decryption |
5097 | @c %**end of header | 5104 | |
5098 | 5105 | ||
5099 | All functions related to the key exchange and encryption/decryption of | 5106 | All functions related to the key exchange and encryption/decryption of |
5100 | messages can be found in @file{gnunet-service-core_kx.c} (except for the | 5107 | messages can be found in @file{gnunet-service-core_kx.c} (except for the |
@@ -5122,7 +5129,7 @@ older than 12 hours. | |||
5122 | 5129 | ||
5123 | @node Type maps | 5130 | @node Type maps |
5124 | @subsubsection Type maps | 5131 | @subsubsection Type maps |
5125 | @c %**end of header | 5132 | |
5126 | 5133 | ||
5127 | Once an encrypted connection has been established, peers begin to exchange | 5134 | Once an encrypted connection has been established, peers begin to exchange |
5128 | type maps. Type maps are used to allow the CORE service to determine which | 5135 | type maps. Type maps are used to allow the CORE service to determine which |
@@ -5155,6 +5162,8 @@ receiving a type map by sending back a | |||
5155 | retransmit the type map (with exponential back-off). | 5162 | retransmit the type map (with exponential back-off). |
5156 | 5163 | ||
5157 | @cindex CADET Subsystem | 5164 | @cindex CADET Subsystem |
5165 | @cindex CADET | ||
5166 | @cindex cadet | ||
5158 | @node CADET Subsystem | 5167 | @node CADET Subsystem |
5159 | @section CADET Subsystem | 5168 | @section CADET Subsystem |
5160 | 5169 | ||
@@ -5221,6 +5230,7 @@ Should a message get lost on TRANSPORT/CORE level, if a channel is | |||
5221 | created with as reliable, CADET will retransmit the lost message and | 5230 | created with as reliable, CADET will retransmit the lost message and |
5222 | deliver it in order to the destination application. | 5231 | deliver it in order to the destination application. |
5223 | 5232 | ||
5233 | @pindex GNUNET_CADET_connect | ||
5224 | To communicate with other peers using CADET, it is necessary to first | 5234 | To communicate with other peers using CADET, it is necessary to first |
5225 | connect to the service using @code{GNUNET_CADET_connect}. | 5235 | connect to the service using @code{GNUNET_CADET_connect}. |
5226 | This function takes several parameters in form of callbacks, to allow the | 5236 | This function takes several parameters in form of callbacks, to allow the |
@@ -5232,7 +5242,8 @@ CADET, even do one connection per listening port). | |||
5232 | The function returns a handle which has to be used for any further | 5242 | The function returns a handle which has to be used for any further |
5233 | interaction with the service. | 5243 | interaction with the service. |
5234 | 5244 | ||
5235 | To connect to a remote peer a client has to call the | 5245 | @pindex GNUNET_CADET_channel_create |
5246 | To connect to a remote peer, a client has to call the | ||
5236 | @code{GNUNET_CADET_channel_create} function. The most important parameters | 5247 | @code{GNUNET_CADET_channel_create} function. The most important parameters |
5237 | given are the remote peer's identity (it public key) and a port, which | 5248 | given are the remote peer's identity (it public key) and a port, which |
5238 | specifies which application on the remote peer to connect to, similar to | 5249 | specifies which application on the remote peer to connect to, similar to |
@@ -5242,6 +5253,7 @@ exchanges to assure and authenticated, secure and verified communication. | |||
5242 | Similar to @code{GNUNET_CADET_connect},@code{GNUNET_CADET_create_channel} | 5253 | Similar to @code{GNUNET_CADET_connect},@code{GNUNET_CADET_create_channel} |
5243 | returns a handle to interact with the created channel. | 5254 | returns a handle to interact with the created channel. |
5244 | 5255 | ||
5256 | @pindex GNUNET_CADET_notify_transmit_ready | ||
5245 | For every message the client wants to send to the remote application, | 5257 | For every message the client wants to send to the remote application, |
5246 | @code{GNUNET_CADET_notify_transmit_ready} must be called, indicating the | 5258 | @code{GNUNET_CADET_notify_transmit_ready} must be called, indicating the |
5247 | channel on which the message should be sent and the size of the message | 5259 | channel on which the message should be sent and the size of the message |
@@ -5258,6 +5270,7 @@ case. To be alerted when a channel is online, a client can call | |||
5258 | means that the channel is online. The callback can give 0 bytes to CADET | 5270 | means that the channel is online. The callback can give 0 bytes to CADET |
5259 | if no message is to be sent, this is OK. | 5271 | if no message is to be sent, this is OK. |
5260 | 5272 | ||
5273 | @pindex GNUNET_CADET_notify_transmit_cancel | ||
5261 | If a transmission was requested but before the callback fires it is no | 5274 | If a transmission was requested but before the callback fires it is no |
5262 | longer needed, it can be canceled with | 5275 | longer needed, it can be canceled with |
5263 | @code{GNUNET_CADET_notify_transmit_ready_cancel}, which uses the handle | 5276 | @code{GNUNET_CADET_notify_transmit_ready_cancel}, which uses the handle |
@@ -5266,6 +5279,7 @@ As in the case of CORE, only one message can be requested at a time: a | |||
5266 | client must not call @code{GNUNET_CADET_notify_transmit_ready} again until | 5279 | client must not call @code{GNUNET_CADET_notify_transmit_ready} again until |
5267 | the callback is called or the request is canceled. | 5280 | the callback is called or the request is canceled. |
5268 | 5281 | ||
5282 | @pindex GNUNET_CADET_channel_destroy | ||
5269 | When a channel is no longer needed, a client can call | 5283 | When a channel is no longer needed, a client can call |
5270 | @code{GNUNET_CADET_channel_destroy} to get rid of it. | 5284 | @code{GNUNET_CADET_channel_destroy} to get rid of it. |
5271 | Note that CADET will try to transmit all pending traffic before notifying | 5285 | Note that CADET will try to transmit all pending traffic before notifying |
@@ -5277,6 +5291,7 @@ on any incoming or outgoing channels are given to the client when CADET | |||
5277 | executes the callbacks given to it at the time of | 5291 | executes the callbacks given to it at the time of |
5278 | @code{GNUNET_CADET_connect}. | 5292 | @code{GNUNET_CADET_connect}. |
5279 | 5293 | ||
5294 | @pindex GNUNET_CADET_disconnect | ||
5280 | Finally, when an application no longer wants to use CADET, it should call | 5295 | Finally, when an application no longer wants to use CADET, it should call |
5281 | @code{GNUNET_CADET_disconnect}, but first all channels and pending | 5296 | @code{GNUNET_CADET_disconnect}, but first all channels and pending |
5282 | transmissions must be closed (otherwise CADET will complain). | 5297 | transmissions must be closed (otherwise CADET will complain). |
@@ -5394,7 +5409,7 @@ to all the other peers, who will calculate the estimate from it. | |||
5394 | @node Target value | 5409 | @node Target value |
5395 | @subsubsection Target value | 5410 | @subsubsection Target value |
5396 | 5411 | ||
5397 | @c %**end of header | 5412 | |
5398 | 5413 | ||
5399 | The target value itself is generated by hashing the current time, rounded | 5414 | The target value itself is generated by hashing the current time, rounded |
5400 | down to an agreed value. If the rounding amount is 1h (default) and the | 5415 | down to an agreed value. If the rounding amount is 1h (default) and the |
@@ -5404,7 +5419,7 @@ Every repetition is called a round. | |||
5404 | 5419 | ||
5405 | @node Timing | 5420 | @node Timing |
5406 | @subsubsection Timing | 5421 | @subsubsection Timing |
5407 | @c %**end of header | 5422 | |
5408 | 5423 | ||
5409 | The NSE subsystem has some timing control to avoid everybody broadcasting | 5424 | The NSE subsystem has some timing control to avoid everybody broadcasting |
5410 | its ID all at one. Once each peer has the target random value, it | 5425 | its ID all at one. Once each peer has the target random value, it |
@@ -5421,7 +5436,7 @@ peers closest to the target value start broadcasting their ID the first. | |||
5421 | @node Controlled Flooding | 5436 | @node Controlled Flooding |
5422 | @subsubsection Controlled Flooding | 5437 | @subsubsection Controlled Flooding |
5423 | 5438 | ||
5424 | @c %**end of header | 5439 | |
5425 | 5440 | ||
5426 | When a peer receives a value, first it verifies that it is closer than the | 5441 | When a peer receives a value, first it verifies that it is closer than the |
5427 | closest value it had so far, otherwise it answers the incoming message | 5442 | closest value it had so far, otherwise it answers the incoming message |
@@ -5440,7 +5455,7 @@ to the neighbors. | |||
5440 | @node Calculating the estimate | 5455 | @node Calculating the estimate |
5441 | @subsubsection Calculating the estimate | 5456 | @subsubsection Calculating the estimate |
5442 | 5457 | ||
5443 | @c %**end of header | 5458 | |
5444 | 5459 | ||
5445 | Once the closest ID has been spread across the network each peer gets the | 5460 | Once the closest ID has been spread across the network each peer gets the |
5446 | exact distance between this ID and the target value of the round and | 5461 | exact distance between this ID and the target value of the round and |
@@ -5459,7 +5474,7 @@ means a factor of two in the size estimate. | |||
5459 | @node libgnunetnse | 5474 | @node libgnunetnse |
5460 | @subsection libgnunetnse | 5475 | @subsection libgnunetnse |
5461 | 5476 | ||
5462 | @c %**end of header | 5477 | |
5463 | 5478 | ||
5464 | The NSE subsystem has the simplest API of all services, with only two | 5479 | The NSE subsystem has the simplest API of all services, with only two |
5465 | calls: @code{GNUNET_NSE_connect} and @code{GNUNET_NSE_disconnect}. | 5480 | calls: @code{GNUNET_NSE_connect} and @code{GNUNET_NSE_disconnect}. |
@@ -5485,7 +5500,7 @@ is no longer called with new estimates. | |||
5485 | @node Results | 5500 | @node Results |
5486 | @subsubsection Results | 5501 | @subsubsection Results |
5487 | 5502 | ||
5488 | @c %**end of header | 5503 | |
5489 | 5504 | ||
5490 | The callback provides two values: the average and the | 5505 | The callback provides two values: the average and the |
5491 | @uref{http://en.wikipedia.org/wiki/Standard_deviation, standard deviation} | 5506 | @uref{http://en.wikipedia.org/wiki/Standard_deviation, standard deviation} |
@@ -5523,7 +5538,7 @@ changing rapidly). | |||
5523 | @node libgnunetnse - Examples | 5538 | @node libgnunetnse - Examples |
5524 | @subsubsection libgnunetnse -Examples | 5539 | @subsubsection libgnunetnse -Examples |
5525 | 5540 | ||
5526 | @c %**end of header | 5541 | |
5527 | 5542 | ||
5528 | Let's close with a couple examples. | 5543 | Let's close with a couple examples. |
5529 | 5544 | ||
@@ -5550,7 +5565,7 @@ case a 5 sigma minimum would be 2 million and a 6 sigma minimum, | |||
5550 | @node The NSE Client-Service Protocol | 5565 | @node The NSE Client-Service Protocol |
5551 | @subsection The NSE Client-Service Protocol | 5566 | @subsection The NSE Client-Service Protocol |
5552 | 5567 | ||
5553 | @c %**end of header | 5568 | |
5554 | 5569 | ||
5555 | As with the API, the client-service protocol is very simple, only has 2 | 5570 | As with the API, the client-service protocol is very simple, only has 2 |
5556 | different messages, defined in @code{src/nse/nse.h}: | 5571 | different messages, defined in @code{src/nse/nse.h}: |
@@ -5571,8 +5586,8 @@ simply disconnects from the service, with no message involved. | |||
5571 | @node The NSE Peer-to-Peer Protocol | 5586 | @node The NSE Peer-to-Peer Protocol |
5572 | @subsection The NSE Peer-to-Peer Protocol | 5587 | @subsection The NSE Peer-to-Peer Protocol |
5573 | 5588 | ||
5574 | @c %**end of header | ||
5575 | 5589 | ||
5590 | @pindex GNUNET_MESSAGE_TYPE_NSE_P2P_FLOOD | ||
5576 | The NSE subsystem only has one message in the P2P protocol, the | 5591 | The NSE subsystem only has one message in the P2P protocol, the |
5577 | @code{GNUNET_MESSAGE_TYPE_NSE_P2P_FLOOD} message. | 5592 | @code{GNUNET_MESSAGE_TYPE_NSE_P2P_FLOOD} message. |
5578 | 5593 | ||
@@ -5626,7 +5641,7 @@ traffic spikes and minimize cross-messages. | |||
5626 | @node HOSTLIST Subsystem | 5641 | @node HOSTLIST Subsystem |
5627 | @section HOSTLIST Subsystem | 5642 | @section HOSTLIST Subsystem |
5628 | 5643 | ||
5629 | @c %**end of header | 5644 | |
5630 | 5645 | ||
5631 | Peers in the GNUnet overlay network need address information so that they | 5646 | Peers in the GNUnet overlay network need address information so that they |
5632 | can connect with other peers. GNUnet uses so called HELLO messages to | 5647 | can connect with other peers. GNUnet uses so called HELLO messages to |
@@ -5664,7 +5679,7 @@ manual effort or the use of a HOSTLIST to obtain HELLOs. | |||
5664 | @node HELLOs | 5679 | @node HELLOs |
5665 | @subsection HELLOs | 5680 | @subsection HELLOs |
5666 | 5681 | ||
5667 | @c %**end of header | 5682 | |
5668 | 5683 | ||
5669 | The basic information peers require to connect to other peers are | 5684 | The basic information peers require to connect to other peers are |
5670 | contained in so called HELLO messages you can think of as a business card. | 5685 | contained in so called HELLO messages you can think of as a business card. |
@@ -5676,7 +5691,7 @@ contact other peers. | |||
5676 | @node Overview for the HOSTLIST subsystem | 5691 | @node Overview for the HOSTLIST subsystem |
5677 | @subsection Overview for the HOSTLIST subsystem | 5692 | @subsection Overview for the HOSTLIST subsystem |
5678 | 5693 | ||
5679 | @c %**end of header | 5694 | |
5680 | 5695 | ||
5681 | The HOSTLIST subsystem provides a way to distribute and obtain contact | 5696 | The HOSTLIST subsystem provides a way to distribute and obtain contact |
5682 | information to connect to other peers using a simple HTTP GET request. | 5697 | information to connect to other peers using a simple HTTP GET request. |
@@ -5702,7 +5717,7 @@ service. | |||
5702 | @node Features | 5717 | @node Features |
5703 | @subsubsection Features | 5718 | @subsubsection Features |
5704 | 5719 | ||
5705 | @c %**end of header | 5720 | |
5706 | 5721 | ||
5707 | The HOSTLIST daemon can: | 5722 | The HOSTLIST daemon can: |
5708 | 5723 | ||
@@ -5720,7 +5735,7 @@ peers | |||
5720 | @node HOSTLIST - Limitations | 5735 | @node HOSTLIST - Limitations |
5721 | @subsubsection HOSTLIST - Limitations | 5736 | @subsubsection HOSTLIST - Limitations |
5722 | 5737 | ||
5723 | @c %**end of header | 5738 | |
5724 | 5739 | ||
5725 | The HOSTLIST daemon does not: | 5740 | The HOSTLIST daemon does not: |
5726 | 5741 | ||
@@ -5732,7 +5747,7 @@ The HOSTLIST daemon does not: | |||
5732 | @node Interacting with the HOSTLIST daemon | 5747 | @node Interacting with the HOSTLIST daemon |
5733 | @subsection Interacting with the HOSTLIST daemon | 5748 | @subsection Interacting with the HOSTLIST daemon |
5734 | 5749 | ||
5735 | @c %**end of header | 5750 | |
5736 | 5751 | ||
5737 | The HOSTLIST subsystem is currently implemented as a daemon, so there is | 5752 | The HOSTLIST subsystem is currently implemented as a daemon, so there is |
5738 | no need for the user to interact with it and therefore there is no | 5753 | no need for the user to interact with it and therefore there is no |
@@ -5760,7 +5775,7 @@ download frequency). | |||
5760 | @node Hostlist security address validation | 5775 | @node Hostlist security address validation |
5761 | @subsection Hostlist security address validation | 5776 | @subsection Hostlist security address validation |
5762 | 5777 | ||
5763 | @c %**end of header | 5778 | |
5764 | 5779 | ||
5765 | Since information obtained from other parties cannot be trusted without | 5780 | Since information obtained from other parties cannot be trusted without |
5766 | validation, we have to distinguish between @emph{validated} and | 5781 | validation, we have to distinguish between @emph{validated} and |
@@ -5781,12 +5796,13 @@ to the TRANSPORT server to validate the addresses. | |||
5781 | @node The HOSTLIST daemon | 5796 | @node The HOSTLIST daemon |
5782 | @subsection The HOSTLIST daemon | 5797 | @subsection The HOSTLIST daemon |
5783 | 5798 | ||
5784 | @c %**end of header | 5799 | |
5785 | 5800 | ||
5786 | The hostlist daemon is the main component of the HOSTLIST subsystem. It is | 5801 | The hostlist daemon is the main component of the HOSTLIST subsystem. It is |
5787 | started by the ARM service and (if configured) starts the HOSTLIST client | 5802 | started by the ARM service and (if configured) starts the HOSTLIST client |
5788 | and server components. | 5803 | and server components. |
5789 | 5804 | ||
5805 | @pindex GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT | ||
5790 | If the daemon provides a hostlist itself it can advertise it's own | 5806 | If the daemon provides a hostlist itself it can advertise it's own |
5791 | hostlist to other peers. To do so it sends a | 5807 | hostlist to other peers. To do so it sends a |
5792 | @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} message to other peers | 5808 | @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} message to other peers |
@@ -5811,7 +5827,7 @@ subsystems and disconnecting from CORE. | |||
5811 | @node The HOSTLIST server | 5827 | @node The HOSTLIST server |
5812 | @subsection The HOSTLIST server | 5828 | @subsection The HOSTLIST server |
5813 | 5829 | ||
5814 | @c %**end of header | 5830 | |
5815 | 5831 | ||
5816 | The server provides a way for other peers to obtain HELLOs. Basically it | 5832 | The server provides a way for other peers to obtain HELLOs. Basically it |
5817 | is a small web server other peers can connect to and download a list of | 5833 | is a small web server other peers can connect to and download a list of |
@@ -5827,7 +5843,7 @@ to other peers connecting on CORE level. | |||
5827 | @node The HTTP Server | 5843 | @node The HTTP Server |
5828 | @subsubsection The HTTP Server | 5844 | @subsubsection The HTTP Server |
5829 | 5845 | ||
5830 | @c %**end of header | 5846 | |
5831 | 5847 | ||
5832 | During startup, the server starts a web server listening on the port | 5848 | During startup, the server starts a web server listening on the port |
5833 | specified with the HTTPPORT value (default 8080). In addition it connects | 5849 | specified with the HTTPPORT value (default 8080). In addition it connects |
@@ -5853,7 +5869,7 @@ The connection will be closed immediately if no hostlist is available. | |||
5853 | @node Advertising the URL | 5869 | @node Advertising the URL |
5854 | @subsubsection Advertising the URL | 5870 | @subsubsection Advertising the URL |
5855 | 5871 | ||
5856 | @c %**end of header | 5872 | |
5857 | 5873 | ||
5858 | The server also advertises the URL to download the hostlist to other peers | 5874 | The server also advertises the URL to download the hostlist to other peers |
5859 | if hostlist advertisement is enabled. | 5875 | if hostlist advertisement is enabled. |
@@ -5865,7 +5881,7 @@ peer using the CORE service. | |||
5865 | @node The HOSTLIST client | 5881 | @node The HOSTLIST client |
5866 | @subsection The HOSTLIST client | 5882 | @subsection The HOSTLIST client |
5867 | 5883 | ||
5868 | @c %**end of header | 5884 | |
5869 | 5885 | ||
5870 | The client provides the functionality to download the list of HELLOs from | 5886 | The client provides the functionality to download the list of HELLOs from |
5871 | a set of URLs. | 5887 | a set of URLs. |
@@ -5889,7 +5905,7 @@ The client supports two modes of operation: | |||
5889 | @node Bootstrapping | 5905 | @node Bootstrapping |
5890 | @subsubsection Bootstrapping | 5906 | @subsubsection Bootstrapping |
5891 | 5907 | ||
5892 | @c %**end of header | 5908 | |
5893 | 5909 | ||
5894 | For bootstrapping, it schedules a task to download the hostlist from the | 5910 | For bootstrapping, it schedules a task to download the hostlist from the |
5895 | set of known URLs. | 5911 | set of known URLs. |
@@ -5918,7 +5934,7 @@ quality of this URL is updated. | |||
5918 | @node Learning | 5934 | @node Learning |
5919 | @subsubsection Learning | 5935 | @subsubsection Learning |
5920 | 5936 | ||
5921 | @c %**end of header | 5937 | |
5922 | 5938 | ||
5923 | The client also manages hostlist advertisements from other peers. The | 5939 | The client also manages hostlist advertisements from other peers. The |
5924 | HOSTLIST daemon forwards @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} | 5940 | HOSTLIST daemon forwards @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} |
@@ -5937,7 +5953,7 @@ never discarded. | |||
5937 | @node Usage | 5953 | @node Usage |
5938 | @subsection Usage | 5954 | @subsection Usage |
5939 | 5955 | ||
5940 | @c %**end of header | 5956 | |
5941 | 5957 | ||
5942 | To start HOSTLIST by default, it has to be added to the DEFAULTSERVICES | 5958 | To start HOSTLIST by default, it has to be added to the DEFAULTSERVICES |
5943 | section for the ARM services. This is done in the default configuration. | 5959 | section for the ARM services. This is done in the default configuration. |
@@ -5951,7 +5967,7 @@ Configuring your peer to provide a hostlist | |||
5951 | @node IDENTITY Subsystem | 5967 | @node IDENTITY Subsystem |
5952 | @section IDENTITY Subsystem | 5968 | @section IDENTITY Subsystem |
5953 | 5969 | ||
5954 | @c %**end of header | 5970 | |
5955 | 5971 | ||
5956 | Identities of "users" in GNUnet are called egos. | 5972 | Identities of "users" in GNUnet are called egos. |
5957 | Egos can be used as pseudonyms ("fake names") or be tied to an | 5973 | Egos can be used as pseudonyms ("fake names") or be tied to an |
@@ -6007,7 +6023,7 @@ between anonymous and pseudonymous egos. | |||
6007 | @cindex libgnunetidentity | 6023 | @cindex libgnunetidentity |
6008 | @node libgnunetidentity | 6024 | @node libgnunetidentity |
6009 | @subsection libgnunetidentity | 6025 | @subsection libgnunetidentity |
6010 | @c %**end of header | 6026 | |
6011 | 6027 | ||
6012 | 6028 | ||
6013 | @menu | 6029 | @menu |
@@ -6021,7 +6037,7 @@ between anonymous and pseudonymous egos. | |||
6021 | @node Connecting to the service | 6037 | @node Connecting to the service |
6022 | @subsubsection Connecting to the service | 6038 | @subsubsection Connecting to the service |
6023 | 6039 | ||
6024 | @c %**end of header | 6040 | |
6025 | 6041 | ||
6026 | First, typical clients connect to the identity service using | 6042 | First, typical clients connect to the identity service using |
6027 | @code{GNUNET_IDENTITY_connect}. This function takes a callback as a | 6043 | @code{GNUNET_IDENTITY_connect}. This function takes a callback as a |
@@ -6057,7 +6073,7 @@ ego's handle. | |||
6057 | @node Operations on Egos | 6073 | @node Operations on Egos |
6058 | @subsubsection Operations on Egos | 6074 | @subsubsection Operations on Egos |
6059 | 6075 | ||
6060 | @c %**end of header | 6076 | |
6061 | 6077 | ||
6062 | Given an ego handle, the main operations are to get its associated private | 6078 | Given an ego handle, the main operations are to get its associated private |
6063 | key using @code{GNUNET_IDENTITY_ego_get_private_key} or its associated | 6079 | key using @code{GNUNET_IDENTITY_ego_get_private_key} or its associated |
@@ -6080,7 +6096,7 @@ only the continuation will no longer be called. | |||
6080 | @node The anonymous Ego | 6096 | @node The anonymous Ego |
6081 | @subsubsection The anonymous Ego | 6097 | @subsubsection The anonymous Ego |
6082 | 6098 | ||
6083 | @c %**end of header | 6099 | |
6084 | 6100 | ||
6085 | A special way to obtain an ego handle is to call | 6101 | A special way to obtain an ego handle is to call |
6086 | @code{GNUNET_IDENTITY_ego_get_anonymous}, which returns an ego for the | 6102 | @code{GNUNET_IDENTITY_ego_get_anonymous}, which returns an ego for the |
@@ -6115,7 +6131,7 @@ using @code{GNUNET_IDENTITY_get}. | |||
6115 | @node The IDENTITY Client-Service Protocol | 6131 | @node The IDENTITY Client-Service Protocol |
6116 | @subsection The IDENTITY Client-Service Protocol | 6132 | @subsection The IDENTITY Client-Service Protocol |
6117 | 6133 | ||
6118 | @c %**end of header | 6134 | |
6119 | 6135 | ||
6120 | A client connecting to the identity service first sends a message with | 6136 | A client connecting to the identity service first sends a message with |
6121 | type | 6137 | type |
@@ -6206,7 +6222,7 @@ private key.} | |||
6206 | @node Editing Zone Information | 6222 | @node Editing Zone Information |
6207 | @subsubsection Editing Zone Information | 6223 | @subsubsection Editing Zone Information |
6208 | 6224 | ||
6209 | @c %**end of header | 6225 | |
6210 | 6226 | ||
6211 | NAMESTORE provides functions to lookup records stored under a label in a | 6227 | NAMESTORE provides functions to lookup records stored under a label in a |
6212 | zone and to store records under a label in a zone. | 6228 | zone and to store records under a label in a zone. |
@@ -6246,7 +6262,7 @@ the operation. | |||
6246 | @node Iterating Zone Information | 6262 | @node Iterating Zone Information |
6247 | @subsubsection Iterating Zone Information | 6263 | @subsubsection Iterating Zone Information |
6248 | 6264 | ||
6249 | @c %**end of header | 6265 | |
6250 | 6266 | ||
6251 | A client can iterate over all information in a zone or all zones managed | 6267 | A client can iterate over all information in a zone or all zones managed |
6252 | by NAMESTORE. | 6268 | by NAMESTORE. |
@@ -6266,7 +6282,7 @@ NULL value to indicate. | |||
6266 | @node Monitoring Zone Information | 6282 | @node Monitoring Zone Information |
6267 | @subsubsection Monitoring Zone Information | 6283 | @subsubsection Monitoring Zone Information |
6268 | 6284 | ||
6269 | @c %**end of header | 6285 | |
6270 | 6286 | ||
6271 | Clients can also monitor zones to be notified about changes. Here the | 6287 | Clients can also monitor zones to be notified about changes. Here the |
6272 | clients uses the @code{GNUNET_NAMESTORE_zone_monitor_start} function and | 6288 | clients uses the @code{GNUNET_NAMESTORE_zone_monitor_start} function and |
@@ -6287,7 +6303,7 @@ from the function to start the monitoring. | |||
6287 | @node PEERINFO Subsystem | 6303 | @node PEERINFO Subsystem |
6288 | @section PEERINFO Subsystem | 6304 | @section PEERINFO Subsystem |
6289 | 6305 | ||
6290 | @c %**end of header | 6306 | |
6291 | 6307 | ||
6292 | The PEERINFO subsystem is used to store verified (validated) information | 6308 | The PEERINFO subsystem is used to store verified (validated) information |
6293 | about known peers in a persistent way. It obtains these addresses for | 6309 | about known peers in a persistent way. It obtains these addresses for |
@@ -6320,7 +6336,7 @@ service providing this functionality. | |||
6320 | @node PEERINFO - Features | 6336 | @node PEERINFO - Features |
6321 | @subsection PEERINFO - Features | 6337 | @subsection PEERINFO - Features |
6322 | 6338 | ||
6323 | @c %**end of header | 6339 | |
6324 | 6340 | ||
6325 | @itemize @bullet | 6341 | @itemize @bullet |
6326 | @item Persistent storage | 6342 | @item Persistent storage |
@@ -6340,7 +6356,7 @@ service providing this functionality. | |||
6340 | @node DeveloperPeer Information | 6356 | @node DeveloperPeer Information |
6341 | @subsection DeveloperPeer Information | 6357 | @subsection DeveloperPeer Information |
6342 | 6358 | ||
6343 | @c %**end of header | 6359 | |
6344 | 6360 | ||
6345 | The PEERINFO subsystem stores these information in the form of HELLO | 6361 | The PEERINFO subsystem stores these information in the form of HELLO |
6346 | messages you can think of as business cards. | 6362 | messages you can think of as business cards. |
@@ -6374,7 +6390,7 @@ subsystem using these information to maintain connections to other peers. | |||
6374 | @node Startup | 6390 | @node Startup |
6375 | @subsection Startup | 6391 | @subsection Startup |
6376 | 6392 | ||
6377 | @c %**end of header | 6393 | |
6378 | 6394 | ||
6379 | During startup the PEERINFO services loads persistent HELLOs from disk. | 6395 | During startup the PEERINFO services loads persistent HELLOs from disk. |
6380 | First PEERINFO parses the directory configured in the HOSTS value of the | 6396 | First PEERINFO parses the directory configured in the HOSTS value of the |
@@ -6390,7 +6406,7 @@ The use of these HELLOs can be prevented by setting the | |||
6390 | @node Managing Information | 6406 | @node Managing Information |
6391 | @subsection Managing Information | 6407 | @subsection Managing Information |
6392 | 6408 | ||
6393 | @c %**end of header | 6409 | |
6394 | 6410 | ||
6395 | The PEERINFO services stores information about known PEERS and a single | 6411 | The PEERINFO services stores information about known PEERS and a single |
6396 | HELLO message for every peer. | 6412 | HELLO message for every peer. |
@@ -6412,7 +6428,7 @@ from the disk. | |||
6412 | @node Obtaining Information | 6428 | @node Obtaining Information |
6413 | @subsection Obtaining Information | 6429 | @subsection Obtaining Information |
6414 | 6430 | ||
6415 | @c %**end of header | 6431 | |
6416 | 6432 | ||
6417 | When a client requests information from PEERINFO, PEERINFO performs a | 6433 | When a client requests information from PEERINFO, PEERINFO performs a |
6418 | lookup for the respective peer or all peers if desired and transmits this | 6434 | lookup for the respective peer or all peers if desired and transmits this |
@@ -6429,7 +6445,7 @@ merge for example) or a new peer was added. | |||
6429 | @node The PEERINFO Client-Service Protocol | 6445 | @node The PEERINFO Client-Service Protocol |
6430 | @subsection The PEERINFO Client-Service Protocol | 6446 | @subsection The PEERINFO Client-Service Protocol |
6431 | 6447 | ||
6432 | @c %**end of header | 6448 | |
6433 | 6449 | ||
6434 | To connect and disconnect to and from the PEERINFO Service PEERINFO | 6450 | To connect and disconnect to and from the PEERINFO Service PEERINFO |
6435 | utilizes the util client/server infrastructure, so no special messages | 6451 | utilizes the util client/server infrastructure, so no special messages |
@@ -6461,7 +6477,7 @@ message, it can proceed with the next request if any is pending. | |||
6461 | @node libgnunetpeerinfo | 6477 | @node libgnunetpeerinfo |
6462 | @subsection libgnunetpeerinfo | 6478 | @subsection libgnunetpeerinfo |
6463 | 6479 | ||
6464 | @c %**end of header | 6480 | |
6465 | 6481 | ||
6466 | The PEERINFO API consists mainly of three different functionalities: | 6482 | The PEERINFO API consists mainly of three different functionalities: |
6467 | 6483 | ||
@@ -6480,7 +6496,7 @@ The PEERINFO API consists mainly of three different functionalities: | |||
6480 | @node Connecting to the PEERINFO Service | 6496 | @node Connecting to the PEERINFO Service |
6481 | @subsubsection Connecting to the PEERINFO Service | 6497 | @subsubsection Connecting to the PEERINFO Service |
6482 | 6498 | ||
6483 | @c %**end of header | 6499 | |
6484 | 6500 | ||
6485 | To connect to the PEERINFO service the function | 6501 | To connect to the PEERINFO service the function |
6486 | @code{GNUNET_PEERINFO_connect} is used, taking a configuration handle as | 6502 | @code{GNUNET_PEERINFO_connect} is used, taking a configuration handle as |
@@ -6491,7 +6507,7 @@ handle returned from the connect function has to be called. | |||
6491 | @node Adding Information to the PEERINFO Service | 6507 | @node Adding Information to the PEERINFO Service |
6492 | @subsubsection Adding Information to the PEERINFO Service | 6508 | @subsubsection Adding Information to the PEERINFO Service |
6493 | 6509 | ||
6494 | @c %**end of header | 6510 | |
6495 | 6511 | ||
6496 | @code{GNUNET_PEERINFO_add_peer} adds a new peer to the PEERINFO subsystem | 6512 | @code{GNUNET_PEERINFO_add_peer} adds a new peer to the PEERINFO subsystem |
6497 | storage. This function takes the PEERINFO handle as an argument, the HELLO | 6513 | storage. This function takes the PEERINFO handle as an argument, the HELLO |
@@ -6506,7 +6522,7 @@ can tell PEERINFO to notify if new peer information are available. | |||
6506 | @node Obtaining Information from the PEERINFO Service | 6522 | @node Obtaining Information from the PEERINFO Service |
6507 | @subsubsection Obtaining Information from the PEERINFO Service | 6523 | @subsubsection Obtaining Information from the PEERINFO Service |
6508 | 6524 | ||
6509 | @c %**end of header | 6525 | |
6510 | 6526 | ||
6511 | To iterate over information in PEERINFO you use | 6527 | To iterate over information in PEERINFO you use |
6512 | @code{GNUNET_PEERINFO_iterate}. | 6528 | @code{GNUNET_PEERINFO_iterate}. |
@@ -6531,7 +6547,7 @@ with @code{GNUNET_PEERINFO_notify_cancel}. | |||
6531 | @node PEERSTORE Subsystem | 6547 | @node PEERSTORE Subsystem |
6532 | @section PEERSTORE Subsystem | 6548 | @section PEERSTORE Subsystem |
6533 | 6549 | ||
6534 | @c %**end of header | 6550 | |
6535 | 6551 | ||
6536 | GNUnet's PEERSTORE subsystem offers persistent per-peer storage for other | 6552 | GNUnet's PEERSTORE subsystem offers persistent per-peer storage for other |
6537 | GNUnet subsystems. GNUnet subsystems can use PEERSTORE to persistently | 6553 | GNUnet subsystems. GNUnet subsystems can use PEERSTORE to persistently |
@@ -6555,7 +6571,7 @@ Each data record stored with PEERSTORE contains the following fields: | |||
6555 | @node Functionality | 6571 | @node Functionality |
6556 | @subsection Functionality | 6572 | @subsection Functionality |
6557 | 6573 | ||
6558 | @c %**end of header | 6574 | |
6559 | 6575 | ||
6560 | Subsystems can store any type of value under a (subsystem, peerid, key) | 6576 | Subsystems can store any type of value under a (subsystem, peerid, key) |
6561 | combination. A "replace" flag set during store operations forces the | 6577 | combination. A "replace" flag set during store operations forces the |
@@ -6581,7 +6597,7 @@ request to PEERSTORE. | |||
6581 | @node Architecture | 6597 | @node Architecture |
6582 | @subsection Architecture | 6598 | @subsection Architecture |
6583 | 6599 | ||
6584 | @c %**end of header | 6600 | |
6585 | 6601 | ||
6586 | PEERSTORE implements the following components: | 6602 | PEERSTORE implements the following components: |
6587 | 6603 | ||
@@ -6597,7 +6613,7 @@ only an "sqlite" plugin is implemented. | |||
6597 | @node libgnunetpeerstore | 6613 | @node libgnunetpeerstore |
6598 | @subsection libgnunetpeerstore | 6614 | @subsection libgnunetpeerstore |
6599 | 6615 | ||
6600 | @c %**end of header | 6616 | |
6601 | 6617 | ||
6602 | libgnunetpeerstore is the library containing the PEERSTORE API. Subsystems | 6618 | libgnunetpeerstore is the library containing the PEERSTORE API. Subsystems |
6603 | wishing to communicate with the PEERSTORE service use this API to open a | 6619 | wishing to communicate with the PEERSTORE service use this API to open a |
@@ -6645,7 +6661,7 @@ destroyed as well. | |||
6645 | @node SET Subsystem | 6661 | @node SET Subsystem |
6646 | @section SET Subsystem | 6662 | @section SET Subsystem |
6647 | 6663 | ||
6648 | @c %**end of header | 6664 | |
6649 | 6665 | ||
6650 | The SET service implements efficient set operations between two peers | 6666 | The SET service implements efficient set operations between two peers |
6651 | over a mesh tunnel. | 6667 | over a mesh tunnel. |
@@ -6668,7 +6684,7 @@ The size of an element's data is limited to around 62 KB. | |||
6668 | @node Local Sets | 6684 | @node Local Sets |
6669 | @subsection Local Sets | 6685 | @subsection Local Sets |
6670 | 6686 | ||
6671 | @c %**end of header | 6687 | |
6672 | 6688 | ||
6673 | Sets created by a local client can be modified and reused for multiple | 6689 | Sets created by a local client can be modified and reused for multiple |
6674 | operations. As each set operation requires potentially expensive special | 6690 | operations. As each set operation requires potentially expensive special |
@@ -6682,7 +6698,7 @@ type. | |||
6682 | @node Set Modifications | 6698 | @node Set Modifications |
6683 | @subsection Set Modifications | 6699 | @subsection Set Modifications |
6684 | 6700 | ||
6685 | @c %**end of header | 6701 | |
6686 | 6702 | ||
6687 | Even when set operations are active, one can add to and remove elements | 6703 | Even when set operations are active, one can add to and remove elements |
6688 | from a set. | 6704 | from a set. |
@@ -6695,7 +6711,7 @@ attaching @emph{generation information} to each element and operation. | |||
6695 | @node Set Operations | 6711 | @node Set Operations |
6696 | @subsection Set Operations | 6712 | @subsection Set Operations |
6697 | 6713 | ||
6698 | @c %**end of header | 6714 | |
6699 | 6715 | ||
6700 | Set operations can be started in two ways: Either by accepting an | 6716 | Set operations can be started in two ways: Either by accepting an |
6701 | operation request from a remote peer, or by requesting a set operation | 6717 | operation request from a remote peer, or by requesting a set operation |
@@ -6712,7 +6728,7 @@ request (providing a local set for the operation) or reject it. | |||
6712 | @node Result Elements | 6728 | @node Result Elements |
6713 | @subsection Result Elements | 6729 | @subsection Result Elements |
6714 | 6730 | ||
6715 | @c %**end of header | 6731 | |
6716 | 6732 | ||
6717 | The SET service has three @emph{result modes} that determine how an | 6733 | The SET service has three @emph{result modes} that determine how an |
6718 | operation's result set is delivered to the client: | 6734 | operation's result set is delivered to the client: |
@@ -6737,7 +6753,7 @@ actually interested in the result of the set operation. | |||
6737 | @node libgnunetset | 6753 | @node libgnunetset |
6738 | @subsection libgnunetset | 6754 | @subsection libgnunetset |
6739 | 6755 | ||
6740 | @c %**end of header | 6756 | |
6741 | 6757 | ||
6742 | @menu | 6758 | @menu |
6743 | * Sets:: | 6759 | * Sets:: |
@@ -6750,7 +6766,7 @@ actually interested in the result of the set operation. | |||
6750 | @node Sets | 6766 | @node Sets |
6751 | @subsubsection Sets | 6767 | @subsubsection Sets |
6752 | 6768 | ||
6753 | @c %**end of header | 6769 | |
6754 | 6770 | ||
6755 | New sets are created with @code{GNUNET_SET_create}. Both the local peer's | 6771 | New sets are created with @code{GNUNET_SET_create}. Both the local peer's |
6756 | configuration (as each set has its own client connection) and the | 6772 | configuration (as each set has its own client connection) and the |
@@ -6766,7 +6782,7 @@ Elements are added and removed with @code{GNUNET_SET_add_element} and | |||
6766 | @node Listeners | 6782 | @node Listeners |
6767 | @subsubsection Listeners | 6783 | @subsubsection Listeners |
6768 | 6784 | ||
6769 | @c %**end of header | 6785 | |
6770 | 6786 | ||
6771 | Listeners are created with @code{GNUNET_SET_listen}. Each time time a | 6787 | Listeners are created with @code{GNUNET_SET_listen}. Each time time a |
6772 | remote peer suggests a set operation with an application id and operation | 6788 | remote peer suggests a set operation with an application id and operation |
@@ -6779,7 +6795,7 @@ until the client calls @code{GNUNET_SET_commit} | |||
6779 | @node Operations | 6795 | @node Operations |
6780 | @subsubsection Operations | 6796 | @subsubsection Operations |
6781 | 6797 | ||
6782 | @c %**end of header | 6798 | |
6783 | 6799 | ||
6784 | Operations to be initiated by the local peer are created with | 6800 | Operations to be initiated by the local peer are created with |
6785 | @code{GNUNET_SET_prepare}. Note that the operation will not be started | 6801 | @code{GNUNET_SET_prepare}. Note that the operation will not be started |
@@ -6789,7 +6805,7 @@ until the client calls @code{GNUNET_SET_commit} | |||
6789 | @node Supplying a Set | 6805 | @node Supplying a Set |
6790 | @subsubsection Supplying a Set | 6806 | @subsubsection Supplying a Set |
6791 | 6807 | ||
6792 | @c %**end of header | 6808 | |
6793 | 6809 | ||
6794 | To create symmetry between the two ways of starting a set operation | 6810 | To create symmetry between the two ways of starting a set operation |
6795 | (accepting and initiating it), the operation handles returned by | 6811 | (accepting and initiating it), the operation handles returned by |
@@ -6803,7 +6819,7 @@ operation. | |||
6803 | @node The Result Callback | 6819 | @node The Result Callback |
6804 | @subsubsection The Result Callback | 6820 | @subsubsection The Result Callback |
6805 | 6821 | ||
6806 | @c %**end of header | 6822 | |
6807 | 6823 | ||
6808 | Clients must specify both a result mode and a result callback with | 6824 | Clients must specify both a result mode and a result callback with |
6809 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare}. The result | 6825 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare}. The result |
@@ -6817,7 +6833,7 @@ or if it is in the difference between the original set and the final set. | |||
6817 | @node The SET Client-Service Protocol | 6833 | @node The SET Client-Service Protocol |
6818 | @subsection The SET Client-Service Protocol | 6834 | @subsection The SET Client-Service Protocol |
6819 | 6835 | ||
6820 | @c %**end of header | 6836 | |
6821 | 6837 | ||
6822 | @menu | 6838 | @menu |
6823 | * Creating Sets:: | 6839 | * Creating Sets:: |
@@ -6831,7 +6847,7 @@ or if it is in the difference between the original set and the final set. | |||
6831 | @node Creating Sets | 6847 | @node Creating Sets |
6832 | @subsubsection Creating Sets | 6848 | @subsubsection Creating Sets |
6833 | 6849 | ||
6834 | @c %**end of header | 6850 | |
6835 | 6851 | ||
6836 | For each set of a client, there exists a client connection to the service. | 6852 | For each set of a client, there exists a client connection to the service. |
6837 | Sets are created by sending the @code{GNUNET_SERVICE_SET_CREATE} message | 6853 | Sets are created by sending the @code{GNUNET_SERVICE_SET_CREATE} message |
@@ -6842,7 +6858,7 @@ the client. | |||
6842 | @node Listeners2 | 6858 | @node Listeners2 |
6843 | @subsubsection Listeners2 | 6859 | @subsubsection Listeners2 |
6844 | 6860 | ||
6845 | @c %**end of header | 6861 | |
6846 | 6862 | ||
6847 | Each listener also requires a seperate client connection. By sending the | 6863 | Each listener also requires a seperate client connection. By sending the |
6848 | @code{GNUNET_SERVICE_SET_LISTEN} message, the client notifies the service | 6864 | @code{GNUNET_SERVICE_SET_LISTEN} message, the client notifies the service |
@@ -6856,7 +6872,7 @@ is supplied for the set operation. | |||
6856 | @node Initiating Operations | 6872 | @node Initiating Operations |
6857 | @subsubsection Initiating Operations | 6873 | @subsubsection Initiating Operations |
6858 | 6874 | ||
6859 | @c %**end of header | 6875 | |
6860 | 6876 | ||
6861 | Operations with remote peers are initiated by sending a | 6877 | Operations with remote peers are initiated by sending a |
6862 | @code{GNUNET_SERVICE_SET_EVALUATE} message to the service. The@ client | 6878 | @code{GNUNET_SERVICE_SET_EVALUATE} message to the service. The@ client |
@@ -6865,7 +6881,7 @@ connection that this message is sent by determines the set to use. | |||
6865 | @node Modifying Sets | 6881 | @node Modifying Sets |
6866 | @subsubsection Modifying Sets | 6882 | @subsubsection Modifying Sets |
6867 | 6883 | ||
6868 | @c %**end of header | 6884 | |
6869 | 6885 | ||
6870 | Sets are modified with the @code{GNUNET_SERVICE_SET_ADD} and | 6886 | Sets are modified with the @code{GNUNET_SERVICE_SET_ADD} and |
6871 | @code{GNUNET_SERVICE_SET_REMOVE} messages. | 6887 | @code{GNUNET_SERVICE_SET_REMOVE} messages. |
@@ -6878,7 +6894,7 @@ Sets are modified with the @code{GNUNET_SERVICE_SET_ADD} and | |||
6878 | 6894 | ||
6879 | @node Results and Operation Status | 6895 | @node Results and Operation Status |
6880 | @subsubsection Results and Operation Status | 6896 | @subsubsection Results and Operation Status |
6881 | @c %**end of header | 6897 | |
6882 | 6898 | ||
6883 | The service notifies the client of result elements and success/failure of | 6899 | The service notifies the client of result elements and success/failure of |
6884 | a set operation with the @code{GNUNET_SERVICE_SET_RESULT} message. | 6900 | a set operation with the @code{GNUNET_SERVICE_SET_RESULT} message. |
@@ -6886,7 +6902,7 @@ a set operation with the @code{GNUNET_SERVICE_SET_RESULT} message. | |||
6886 | @node Iterating Sets | 6902 | @node Iterating Sets |
6887 | @subsubsection Iterating Sets | 6903 | @subsubsection Iterating Sets |
6888 | 6904 | ||
6889 | @c %**end of header | 6905 | |
6890 | 6906 | ||
6891 | All elements of a set can be requested by sending | 6907 | All elements of a set can be requested by sending |
6892 | @code{GNUNET_SERVICE_SET_ITER_REQUEST}. The server responds with | 6908 | @code{GNUNET_SERVICE_SET_ITER_REQUEST}. The server responds with |
@@ -6899,7 +6915,7 @@ iteration may be active for a set at any given time. | |||
6899 | @node The SET Intersection Peer-to-Peer Protocol | 6915 | @node The SET Intersection Peer-to-Peer Protocol |
6900 | @subsection The SET Intersection Peer-to-Peer Protocol | 6916 | @subsection The SET Intersection Peer-to-Peer Protocol |
6901 | 6917 | ||
6902 | @c %**end of header | 6918 | |
6903 | 6919 | ||
6904 | The intersection protocol operates over CADET and starts with a | 6920 | The intersection protocol operates over CADET and starts with a |
6905 | GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer | 6921 | GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer |
@@ -6931,7 +6947,7 @@ just the initial handshake. | |||
6931 | @node The Bloom filter exchange | 6947 | @node The Bloom filter exchange |
6932 | @subsubsection The Bloom filter exchange | 6948 | @subsubsection The Bloom filter exchange |
6933 | 6949 | ||
6934 | @c %**end of header | 6950 | |
6935 | 6951 | ||
6936 | In this phase, each peer transmits a Bloom filter over the remaining | 6952 | In this phase, each peer transmits a Bloom filter over the remaining |
6937 | keys of the local set to the other peer using a | 6953 | keys of the local set to the other peer using a |
@@ -6958,7 +6974,7 @@ this time as the sender. | |||
6958 | @node Salt | 6974 | @node Salt |
6959 | @subsubsection Salt | 6975 | @subsubsection Salt |
6960 | 6976 | ||
6961 | @c %**end of header | 6977 | |
6962 | 6978 | ||
6963 | Bloomfilter operations are probabilistic: With some non-zero probability | 6979 | Bloomfilter operations are probabilistic: With some non-zero probability |
6964 | the test may incorrectly say an element is in the set, even though it is | 6980 | the test may incorrectly say an element is in the set, even though it is |
@@ -6978,7 +6994,7 @@ sets of the same size, and where the XOR over all keys computes the same | |||
6978 | @node The SET Union Peer-to-Peer Protocol | 6994 | @node The SET Union Peer-to-Peer Protocol |
6979 | @subsection The SET Union Peer-to-Peer Protocol | 6995 | @subsection The SET Union Peer-to-Peer Protocol |
6980 | 6996 | ||
6981 | @c %**end of header | 6997 | |
6982 | 6998 | ||
6983 | The SET union protocol is based on Eppstein's efficient set reconciliation | 6999 | The SET union protocol is based on Eppstein's efficient set reconciliation |
6984 | without prior context. You should read this paper first if you want to | 7000 | without prior context. You should read this paper first if you want to |
@@ -7021,7 +7037,7 @@ succeeding if they failed due to collisions before. | |||
7021 | @node STATISTICS Subsystem | 7037 | @node STATISTICS Subsystem |
7022 | @section STATISTICS Subsystem | 7038 | @section STATISTICS Subsystem |
7023 | 7039 | ||
7024 | @c %**end of header | 7040 | |
7025 | 7041 | ||
7026 | In GNUnet, the STATISTICS subsystem offers a central place for all | 7042 | In GNUnet, the STATISTICS subsystem offers a central place for all |
7027 | subsystems to publish unsigned 64-bit integer run-time statistics. | 7043 | subsystems to publish unsigned 64-bit integer run-time statistics. |
@@ -7073,7 +7089,7 @@ to STATISTICS during shutdown. | |||
7073 | @node libgnunetstatistics | 7089 | @node libgnunetstatistics |
7074 | @subsection libgnunetstatistics | 7090 | @subsection libgnunetstatistics |
7075 | 7091 | ||
7076 | @c %**end of header | 7092 | |
7077 | 7093 | ||
7078 | @strong{libgnunetstatistics} is the library containing the API for the | 7094 | @strong{libgnunetstatistics} is the library containing the API for the |
7079 | STATISTICS subsystem. Any process requiring to use STATISTICS should use | 7095 | STATISTICS subsystem. Any process requiring to use STATISTICS should use |
@@ -7104,7 +7120,7 @@ functions from the API can be used. | |||
7104 | @node Statistics retrieval | 7120 | @node Statistics retrieval |
7105 | @subsubsection Statistics retrieval | 7121 | @subsubsection Statistics retrieval |
7106 | 7122 | ||
7107 | @c %**end of header | 7123 | |
7108 | 7124 | ||
7109 | Once a connection to the statistics service is obtained, information | 7125 | Once a connection to the statistics service is obtained, information |
7110 | about any other system which uses statistics can be retrieved with the | 7126 | about any other system which uses statistics can be retrieved with the |
@@ -7127,7 +7143,7 @@ when we want to shutdown and cleanup everything. | |||
7127 | @node Setting statistics and updating them | 7143 | @node Setting statistics and updating them |
7128 | @subsubsection Setting statistics and updating them | 7144 | @subsubsection Setting statistics and updating them |
7129 | 7145 | ||
7130 | @c %**end of header | 7146 | |
7131 | 7147 | ||
7132 | So far we have seen how to retrieve statistics, here we will learn how we | 7148 | So far we have seen how to retrieve statistics, here we will learn how we |
7133 | can set statistics and update them so that other subsystems can retrieve | 7149 | can set statistics and update them so that other subsystems can retrieve |
@@ -7157,7 +7173,7 @@ to worry about sending requests too quickly. | |||
7157 | @node Watches | 7173 | @node Watches |
7158 | @subsubsection Watches | 7174 | @subsubsection Watches |
7159 | 7175 | ||
7160 | @c %**end of header | 7176 | |
7161 | 7177 | ||
7162 | As interesting feature of STATISTICS lies in serving notifications | 7178 | As interesting feature of STATISTICS lies in serving notifications |
7163 | whenever a statistic of our interest is modified. | 7179 | whenever a statistic of our interest is modified. |
@@ -7177,7 +7193,7 @@ parameters that are used for registering the watch. | |||
7177 | 7193 | ||
7178 | @node The STATISTICS Client-Service Protocol | 7194 | @node The STATISTICS Client-Service Protocol |
7179 | @subsection The STATISTICS Client-Service Protocol | 7195 | @subsection The STATISTICS Client-Service Protocol |
7180 | @c %**end of header | 7196 | |
7181 | 7197 | ||
7182 | 7198 | ||
7183 | @menu | 7199 | @menu |
@@ -7189,7 +7205,7 @@ parameters that are used for registering the watch. | |||
7189 | @node Statistics retrieval2 | 7205 | @node Statistics retrieval2 |
7190 | @subsubsection Statistics retrieval2 | 7206 | @subsubsection Statistics retrieval2 |
7191 | 7207 | ||
7192 | @c %**end of header | 7208 | |
7193 | 7209 | ||
7194 | To retrieve statistics, the client transmits a message of type | 7210 | To retrieve statistics, the client transmits a message of type |
7195 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_GET} containing the given subsystem | 7211 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_GET} containing the given subsystem |
@@ -7203,7 +7219,7 @@ type @code{GNUNET_MESSAGE_TYPE_STATISTICS_END}. | |||
7203 | @node Setting and updating statistics | 7219 | @node Setting and updating statistics |
7204 | @subsubsection Setting and updating statistics | 7220 | @subsubsection Setting and updating statistics |
7205 | 7221 | ||
7206 | @c %**end of header | 7222 | |
7207 | 7223 | ||
7208 | The subsystem name, parameter name, its value and the persistence flag are | 7224 | The subsystem name, parameter name, its value and the persistence flag are |
7209 | communicated to the service through the message | 7225 | communicated to the service through the message |
@@ -7226,7 +7242,7 @@ the message should be treated as an update value. | |||
7226 | @node Watching for updates | 7242 | @node Watching for updates |
7227 | @subsubsection Watching for updates | 7243 | @subsubsection Watching for updates |
7228 | 7244 | ||
7229 | @c %**end of header | 7245 | |
7230 | 7246 | ||
7231 | The function registers the watch at the service by sending a message of | 7247 | The function registers the watch at the service by sending a message of |
7232 | type @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH}. The service then sends | 7248 | type @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH}. The service then sends |
@@ -7239,7 +7255,7 @@ parameter's value is changed. | |||
7239 | @node Distributed Hash Table (DHT) | 7255 | @node Distributed Hash Table (DHT) |
7240 | @section Distributed Hash Table (DHT) | 7256 | @section Distributed Hash Table (DHT) |
7241 | 7257 | ||
7242 | @c %**end of header | 7258 | |
7243 | 7259 | ||
7244 | GNUnet includes a generic distributed hash table that can be used by | 7260 | GNUnet includes a generic distributed hash table that can be used by |
7245 | developers building P2P applications in the framework. | 7261 | developers building P2P applications in the framework. |
@@ -7285,7 +7301,7 @@ loss of performance or quality of service is expected in this case). | |||
7285 | @node Block library and plugins | 7301 | @node Block library and plugins |
7286 | @subsection Block library and plugins | 7302 | @subsection Block library and plugins |
7287 | 7303 | ||
7288 | @c %**end of header | 7304 | |
7289 | 7305 | ||
7290 | @menu | 7306 | @menu |
7291 | * What is a Block?:: | 7307 | * What is a Block?:: |
@@ -7298,7 +7314,7 @@ loss of performance or quality of service is expected in this case). | |||
7298 | @node What is a Block? | 7314 | @node What is a Block? |
7299 | @subsubsection What is a Block? | 7315 | @subsubsection What is a Block? |
7300 | 7316 | ||
7301 | @c %**end of header | 7317 | |
7302 | 7318 | ||
7303 | Blocks are small (< 63k) pieces of data stored under a key (struct | 7319 | Blocks are small (< 63k) pieces of data stored under a key (struct |
7304 | GNUNET_HashCode). Blocks have a type (enum GNUNET_BlockType) which defines | 7320 | GNUNET_HashCode). Blocks have a type (enum GNUNET_BlockType) which defines |
@@ -7315,7 +7331,7 @@ available for any type of block. | |||
7315 | @node The API of libgnunetblock | 7331 | @node The API of libgnunetblock |
7316 | @subsubsection The API of libgnunetblock | 7332 | @subsubsection The API of libgnunetblock |
7317 | 7333 | ||
7318 | @c %**end of header | 7334 | |
7319 | 7335 | ||
7320 | The block library requires for each (family of) block type(s) a block | 7336 | The block library requires for each (family of) block type(s) a block |
7321 | plugin (implementing @file{gnunet_block_plugin.h}) that provides basic | 7337 | plugin (implementing @file{gnunet_block_plugin.h}) that provides basic |
@@ -7347,7 +7363,7 @@ If a plugin fails to do this, responses may loop in the network. | |||
7347 | 7363 | ||
7348 | @node Queries | 7364 | @node Queries |
7349 | @subsubsection Queries | 7365 | @subsubsection Queries |
7350 | @c %**end of header | 7366 | |
7351 | 7367 | ||
7352 | The query format for any block in GNUnet consists of four main components. | 7368 | The query format for any block in GNUnet consists of four main components. |
7353 | First, the type of the desired block must be specified. Second, the query | 7369 | First, the type of the desired block must be specified. Second, the query |
@@ -7375,7 +7391,7 @@ Depending on the results from the plugin, the DHT will then discard the | |||
7375 | @node Sample Code | 7391 | @node Sample Code |
7376 | @subsubsection Sample Code | 7392 | @subsubsection Sample Code |
7377 | 7393 | ||
7378 | @c %**end of header | 7394 | |
7379 | 7395 | ||
7380 | The source code in @strong{plugin_block_test.c} is a good starting point | 7396 | The source code in @strong{plugin_block_test.c} is a good starting point |
7381 | for new block plugins --- it does the minimal work by implementing a | 7397 | for new block plugins --- it does the minimal work by implementing a |
@@ -7386,7 +7402,7 @@ block plugin. | |||
7386 | @node Conclusion2 | 7402 | @node Conclusion2 |
7387 | @subsubsection Conclusion2 | 7403 | @subsubsection Conclusion2 |
7388 | 7404 | ||
7389 | @c %**end of header | 7405 | |
7390 | 7406 | ||
7391 | In conclusion, GNUnet subsystems that want to use the DHT need to define a | 7407 | In conclusion, GNUnet subsystems that want to use the DHT need to define a |
7392 | block format and write a plugin to match queries and replies. For testing, | 7408 | block format and write a plugin to match queries and replies. For testing, |
@@ -7400,7 +7416,7 @@ of error checking that results from this primitive implementation. | |||
7400 | @node libgnunetdht | 7416 | @node libgnunetdht |
7401 | @subsection libgnunetdht | 7417 | @subsection libgnunetdht |
7402 | 7418 | ||
7403 | @c %**end of header | 7419 | |
7404 | 7420 | ||
7405 | The DHT API itself is pretty simple and offers the usual GET and PUT | 7421 | The DHT API itself is pretty simple and offers the usual GET and PUT |
7406 | functions that work as expected. The specified block type refers to the | 7422 | functions that work as expected. The specified block type refers to the |
@@ -7418,7 +7434,7 @@ data stored in the network. | |||
7418 | @node GET | 7434 | @node GET |
7419 | @subsubsection GET | 7435 | @subsubsection GET |
7420 | 7436 | ||
7421 | @c %**end of header | 7437 | |
7422 | 7438 | ||
7423 | When using GET, the main consideration for developers (other than the | 7439 | When using GET, the main consideration for developers (other than the |
7424 | block library) should be that after issuing a GET, the DHT will | 7440 | block library) should be that after issuing a GET, the DHT will |
@@ -7446,7 +7462,7 @@ bandwidth consumption. | |||
7446 | @node PUT | 7462 | @node PUT |
7447 | @subsubsection PUT | 7463 | @subsubsection PUT |
7448 | 7464 | ||
7449 | @c %**end of header | 7465 | |
7450 | 7466 | ||
7451 | @c inconsistent use of ``must'' above it's written ``MUST'' | 7467 | @c inconsistent use of ``must'' above it's written ``MUST'' |
7452 | In contrast to GET operations, developers @strong{must} manually re-run | 7468 | In contrast to GET operations, developers @strong{must} manually re-run |
@@ -7468,7 +7484,7 @@ DHT PUT operations should be repeated at least every 1-2 hours. | |||
7468 | @node MONITOR | 7484 | @node MONITOR |
7469 | @subsubsection MONITOR | 7485 | @subsubsection MONITOR |
7470 | 7486 | ||
7471 | @c %**end of header | 7487 | |
7472 | 7488 | ||
7473 | The DHT API also allows applications to monitor messages crossing the | 7489 | The DHT API also allows applications to monitor messages crossing the |
7474 | local DHT service. | 7490 | local DHT service. |
@@ -7491,7 +7507,7 @@ number of workers will process the distributed workload. | |||
7491 | @node DHT Routing Options | 7507 | @node DHT Routing Options |
7492 | @subsubsection DHT Routing Options | 7508 | @subsubsection DHT Routing Options |
7493 | 7509 | ||
7494 | @c %**end of header | 7510 | |
7495 | 7511 | ||
7496 | There are two important options for GET and PUT requests: | 7512 | There are two important options for GET and PUT requests: |
7497 | 7513 | ||
@@ -7521,7 +7537,7 @@ in the future offer performance improvements for clique topologies. | |||
7521 | @node The DHT Client-Service Protocol | 7537 | @node The DHT Client-Service Protocol |
7522 | @subsection The DHT Client-Service Protocol | 7538 | @subsection The DHT Client-Service Protocol |
7523 | 7539 | ||
7524 | @c %**end of header | 7540 | |
7525 | 7541 | ||
7526 | @menu | 7542 | @menu |
7527 | * PUTting data into the DHT:: | 7543 | * PUTting data into the DHT:: |
@@ -7532,7 +7548,7 @@ in the future offer performance improvements for clique topologies. | |||
7532 | @node PUTting data into the DHT | 7548 | @node PUTting data into the DHT |
7533 | @subsubsection PUTting data into the DHT | 7549 | @subsubsection PUTting data into the DHT |
7534 | 7550 | ||
7535 | @c %**end of header | 7551 | |
7536 | 7552 | ||
7537 | To store (PUT) data into the DHT, the client sends a | 7553 | To store (PUT) data into the DHT, the client sends a |
7538 | @code{struct GNUNET_DHT_ClientPutMessage} to the service. | 7554 | @code{struct GNUNET_DHT_ClientPutMessage} to the service. |
@@ -7553,7 +7569,7 @@ in the P2P interaction. | |||
7553 | @node GETting data from the DHT | 7569 | @node GETting data from the DHT |
7554 | @subsubsection GETting data from the DHT | 7570 | @subsubsection GETting data from the DHT |
7555 | 7571 | ||
7556 | @c %**end of header | 7572 | |
7557 | 7573 | ||
7558 | To retrieve (GET) data from the DHT, the client sends a | 7574 | To retrieve (GET) data from the DHT, the client sends a |
7559 | @code{struct GNUNET_DHT_ClientGetMessage} to the service. The message | 7575 | @code{struct GNUNET_DHT_ClientGetMessage} to the service. The message |
@@ -7592,7 +7608,7 @@ service --- and to stop them individually. | |||
7592 | @node Monitoring the DHT | 7608 | @node Monitoring the DHT |
7593 | @subsubsection Monitoring the DHT | 7609 | @subsubsection Monitoring the DHT |
7594 | 7610 | ||
7595 | @c %**end of header | 7611 | |
7596 | 7612 | ||
7597 | To begin monitoring, the client sends a | 7613 | To begin monitoring, the client sends a |
7598 | @code{struct GNUNET_DHT_MonitorStartStop} message to the DHT service. | 7614 | @code{struct GNUNET_DHT_MonitorStartStop} message to the DHT service. |
@@ -7607,7 +7623,7 @@ these messages contains all of the information about the event. | |||
7607 | 7623 | ||
7608 | @node The DHT Peer-to-Peer Protocol | 7624 | @node The DHT Peer-to-Peer Protocol |
7609 | @subsection The DHT Peer-to-Peer Protocol | 7625 | @subsection The DHT Peer-to-Peer Protocol |
7610 | @c %**end of header | 7626 | |
7611 | 7627 | ||
7612 | 7628 | ||
7613 | @menu | 7629 | @menu |
@@ -7619,7 +7635,7 @@ these messages contains all of the information about the event. | |||
7619 | @node Routing GETs or PUTs | 7635 | @node Routing GETs or PUTs |
7620 | @subsubsection Routing GETs or PUTs | 7636 | @subsubsection Routing GETs or PUTs |
7621 | 7637 | ||
7622 | @c %**end of header | 7638 | |
7623 | 7639 | ||
7624 | When routing GETs or PUTs, the DHT service selects a suitable subset of | 7640 | When routing GETs or PUTs, the DHT service selects a suitable subset of |
7625 | neighbours for forwarding. The exact number of neighbours can be zero or | 7641 | neighbours for forwarding. The exact number of neighbours can be zero or |
@@ -7634,7 +7650,7 @@ traversed; those peers are also excluded from the selection. | |||
7634 | @node PUTting data into the DHT2 | 7650 | @node PUTting data into the DHT2 |
7635 | @subsubsection PUTting data into the DHT2 | 7651 | @subsubsection PUTting data into the DHT2 |
7636 | 7652 | ||
7637 | @c %**end of header | 7653 | |
7638 | 7654 | ||
7639 | To PUT data into the DHT, the service sends a @code{struct PeerPutMessage} | 7655 | To PUT data into the DHT, the service sends a @code{struct PeerPutMessage} |
7640 | of type @code{GNUNET_MESSAGE_TYPE_DHT_P2P_PUT} to the respective | 7656 | of type @code{GNUNET_MESSAGE_TYPE_DHT_P2P_PUT} to the respective |
@@ -7656,7 +7672,7 @@ its own identity (this is done to reduce bandwidth). | |||
7656 | @node GETting data from the DHT2 | 7672 | @node GETting data from the DHT2 |
7657 | @subsubsection GETting data from the DHT2 | 7673 | @subsubsection GETting data from the DHT2 |
7658 | 7674 | ||
7659 | @c %**end of header | 7675 | |
7660 | 7676 | ||
7661 | A peer can search the DHT by sending @code{struct PeerGetMessage}s of type | 7677 | A peer can search the DHT by sending @code{struct PeerGetMessage}s of type |
7662 | @code{GNUNET_MESSAGE_TYPE_DHT_P2P_GET} to other peers. In addition to the | 7678 | @code{GNUNET_MESSAGE_TYPE_DHT_P2P_GET} to other peers. In addition to the |
@@ -7695,7 +7711,7 @@ The DHT service may also cache forwarded results locally if the | |||
7695 | @node GNU Name System (GNS) | 7711 | @node GNU Name System (GNS) |
7696 | @section GNU Name System (GNS) | 7712 | @section GNU Name System (GNS) |
7697 | 7713 | ||
7698 | @c %**end of header | 7714 | |
7699 | 7715 | ||
7700 | The GNU Name System (GNS) is a decentralized database that enables users | 7716 | The GNU Name System (GNS) is a decentralized database that enables users |
7701 | to securely resolve names to values. | 7717 | to securely resolve names to values. |
@@ -7750,7 +7766,7 @@ record types. | |||
7750 | @node libgnunetgns | 7766 | @node libgnunetgns |
7751 | @subsection libgnunetgns | 7767 | @subsection libgnunetgns |
7752 | 7768 | ||
7753 | @c %**end of header | 7769 | |
7754 | 7770 | ||
7755 | The GNS API itself is extremely simple. Clients first connect to the | 7771 | The GNS API itself is extremely simple. Clients first connect to the |
7756 | GNS service using @code{GNUNET_GNS_connect}. | 7772 | GNS service using @code{GNUNET_GNS_connect}. |
@@ -7768,7 +7784,7 @@ Once finished, clients disconnect using @code{GNUNET_GNS_disconnect}. | |||
7768 | @node Looking up records | 7784 | @node Looking up records |
7769 | @subsubsection Looking up records | 7785 | @subsubsection Looking up records |
7770 | 7786 | ||
7771 | @c %**end of header | 7787 | |
7772 | 7788 | ||
7773 | @code{GNUNET_GNS_lookup} takes a number of arguments: | 7789 | @code{GNUNET_GNS_lookup} takes a number of arguments: |
7774 | 7790 | ||
@@ -7810,7 +7826,7 @@ must no longer be canceled. | |||
7810 | @node Accessing the records | 7826 | @node Accessing the records |
7811 | @subsubsection Accessing the records | 7827 | @subsubsection Accessing the records |
7812 | 7828 | ||
7813 | @c %**end of header | 7829 | |
7814 | 7830 | ||
7815 | The @code{libgnunetgnsrecord} library provides an API to manipulate the | 7831 | The @code{libgnunetgnsrecord} library provides an API to manipulate the |
7816 | GNS record array that is given to proc. In particular, it offers | 7832 | GNS record array that is given to proc. In particular, it offers |
@@ -7824,7 +7840,7 @@ functions for parsing (and serializing) common types of DNS records. | |||
7824 | @node Creating records | 7840 | @node Creating records |
7825 | @subsubsection Creating records | 7841 | @subsubsection Creating records |
7826 | 7842 | ||
7827 | @c %**end of header | 7843 | |
7828 | 7844 | ||
7829 | Creating GNS records is typically done by building the respective record | 7845 | Creating GNS records is typically done by building the respective record |
7830 | information (possibly with the help of @code{libgnunetgnsrecord} and | 7846 | information (possibly with the help of @code{libgnunetgnsrecord} and |
@@ -7835,7 +7851,7 @@ operation. | |||
7835 | @node Future work | 7851 | @node Future work |
7836 | @subsubsection Future work | 7852 | @subsubsection Future work |
7837 | 7853 | ||
7838 | @c %**end of header | 7854 | |
7839 | 7855 | ||
7840 | In the future, we want to expand @code{libgnunetgns} to allow | 7856 | In the future, we want to expand @code{libgnunetgns} to allow |
7841 | applications to observe shortening operations performed during GNS | 7857 | applications to observe shortening operations performed during GNS |
@@ -7845,7 +7861,7 @@ this happens. | |||
7845 | @node libgnunetgnsrecord | 7861 | @node libgnunetgnsrecord |
7846 | @subsection libgnunetgnsrecord | 7862 | @subsection libgnunetgnsrecord |
7847 | 7863 | ||
7848 | @c %**end of header | 7864 | |
7849 | 7865 | ||
7850 | The @code{libgnunetgnsrecord} library is used to manipulate GNS | 7866 | The @code{libgnunetgnsrecord} library is used to manipulate GNS |
7851 | records (in plaintext or in their encrypted format). | 7867 | records (in plaintext or in their encrypted format). |
@@ -7871,7 +7887,7 @@ standard GNS record types. | |||
7871 | @node Value handling | 7887 | @node Value handling |
7872 | @subsubsection Value handling | 7888 | @subsubsection Value handling |
7873 | 7889 | ||
7874 | @c %**end of header | 7890 | |
7875 | 7891 | ||
7876 | @code{GNUNET_GNSRECORD_value_to_string} can be used to convert | 7892 | @code{GNUNET_GNSRECORD_value_to_string} can be used to convert |
7877 | the (binary) representation of a GNS record value to a human readable, | 7893 | the (binary) representation of a GNS record value to a human readable, |
@@ -7886,7 +7902,7 @@ a GNS record value. | |||
7886 | @node Type handling | 7902 | @node Type handling |
7887 | @subsubsection Type handling | 7903 | @subsubsection Type handling |
7888 | 7904 | ||
7889 | @c %**end of header | 7905 | |
7890 | 7906 | ||
7891 | @code{GNUNET_GNSRECORD_typename_to_number} can be used to obtain the | 7907 | @code{GNUNET_GNSRECORD_typename_to_number} can be used to obtain the |
7892 | numeric value associated with a given typename. For example, given the | 7908 | numeric value associated with a given typename. For example, given the |
@@ -7904,7 +7920,7 @@ typename "A". | |||
7904 | @node GNS plugins | 7920 | @node GNS plugins |
7905 | @subsection GNS plugins | 7921 | @subsection GNS plugins |
7906 | 7922 | ||
7907 | @c %**end of header | 7923 | |
7908 | 7924 | ||
7909 | Adding a new GNS record type typically involves writing (or extending) a | 7925 | Adding a new GNS record type typically involves writing (or extending) a |
7910 | GNSRECORD plugin. The plugin needs to implement the | 7926 | GNSRECORD plugin. The plugin needs to implement the |
@@ -7930,7 +7946,7 @@ typenames and numbers documented in the previous subsection. | |||
7930 | 7946 | ||
7931 | @node The GNS Client-Service Protocol | 7947 | @node The GNS Client-Service Protocol |
7932 | @subsection The GNS Client-Service Protocol | 7948 | @subsection The GNS Client-Service Protocol |
7933 | @c %**end of header | 7949 | |
7934 | 7950 | ||
7935 | The GNS client-service protocol consists of two simple messages, the | 7951 | The GNS client-service protocol consists of two simple messages, the |
7936 | @code{LOOKUP} message and the @code{LOOKUP_RESULT}. Each @code{LOOKUP} | 7952 | @code{LOOKUP} message and the @code{LOOKUP_RESULT}. Each @code{LOOKUP} |
@@ -7950,7 +7966,7 @@ They can thus be deserialized using | |||
7950 | @node Hijacking the DNS-Traffic using gnunet-service-dns | 7966 | @node Hijacking the DNS-Traffic using gnunet-service-dns |
7951 | @subsection Hijacking the DNS-Traffic using gnunet-service-dns | 7967 | @subsection Hijacking the DNS-Traffic using gnunet-service-dns |
7952 | 7968 | ||
7953 | @c %**end of header | 7969 | |
7954 | 7970 | ||
7955 | This section documents how the gnunet-service-dns (and the | 7971 | This section documents how the gnunet-service-dns (and the |
7956 | gnunet-helper-dns) intercepts DNS queries from the local system. | 7972 | gnunet-helper-dns) intercepts DNS queries from the local system. |
@@ -7987,7 +8003,7 @@ interface with the original nameserver as source address. | |||
7987 | @node Network Setup Details | 8003 | @node Network Setup Details |
7988 | @subsubsection Network Setup Details | 8004 | @subsubsection Network Setup Details |
7989 | 8005 | ||
7990 | @c %**end of header | 8006 | |
7991 | 8007 | ||
7992 | The DNS interceptor adds the following rules to the Linux kernel: | 8008 | The DNS interceptor adds the following rules to the Linux kernel: |
7993 | @example | 8009 | @example |
@@ -8008,7 +8024,7 @@ arbitrarily). The third line adds a routing policy based on this mark | |||
8008 | @node Serving DNS lookups via GNS on W32 | 8024 | @node Serving DNS lookups via GNS on W32 |
8009 | @subsection Serving DNS lookups via GNS on W32 | 8025 | @subsection Serving DNS lookups via GNS on W32 |
8010 | 8026 | ||
8011 | @c %**end of header | 8027 | |
8012 | 8028 | ||
8013 | This section documents how the libw32nsp (and | 8029 | This section documents how the libw32nsp (and |
8014 | gnunet-gns-helper-service-w32) do DNS resolutions of DNS queries on the | 8030 | gnunet-gns-helper-service-w32) do DNS resolutions of DNS queries on the |
@@ -8078,10 +8094,9 @@ This includes some of well known utilities, like "ping" and "nslookup". | |||
8078 | @node Importing DNS Zones into GNS | 8094 | @node Importing DNS Zones into GNS |
8079 | @subsection Importing DNS Zones into GNS | 8095 | @subsection Importing DNS Zones into GNS |
8080 | 8096 | ||
8081 | @c %**end of header | ||
8082 | |||
8083 | This section discusses the challenges and problems faced when writing the | 8097 | This section discusses the challenges and problems faced when writing the |
8084 | Ascension tool. It also takes a look at possible improvements in the future. | 8098 | Ascension tool. It also takes a look at possible improvements in the |
8099 | future. | ||
8085 | 8100 | ||
8086 | @menu | 8101 | @menu |
8087 | * Conversions between DNS and GNS:: | 8102 | * Conversions between DNS and GNS:: |
@@ -8089,29 +8104,31 @@ Ascension tool. It also takes a look at possible improvements in the future. | |||
8089 | * Performance:: | 8104 | * Performance:: |
8090 | @end menu | 8105 | @end menu |
8091 | 8106 | ||
8107 | @cindex DNS Conversion | ||
8092 | @node Conversions between DNS and GNS | 8108 | @node Conversions between DNS and GNS |
8093 | @subsubsection Conversions between DNS and GNS | 8109 | @subsubsection Conversions between DNS and GNS |
8094 | 8110 | ||
8095 | The differences between the two name systems lies in the details | 8111 | The differences between the two name systems lies in the details |
8096 | and is not always transparent. For instance an SRV record is converted to a | 8112 | and is not always transparent. |
8097 | GNS only BOX record. | 8113 | For instance an SRV record is converted to a GNS only BOX record. |
8098 | 8114 | ||
8099 | This is done by converting to a BOX record from an existing SRV record: | 8115 | This is done by converting to a BOX record from an existing SRV record: |
8100 | 8116 | ||
8101 | @example | 8117 | @example |
8102 | # SRV | 8118 | # SRV |
8103 | # _service._proto.name. TTL class SRV priority weight port target | 8119 | # _service._proto.name. TTL class SRV priority weight port target |
8104 | _sip._tcp.example.com. 14000 IN SRV 0 0 5060 www.example.com. | 8120 | _sip._tcp.example.com. 14000 IN SRV 0 0 5060 www.example.com. |
8105 | # BOX | 8121 | # BOX |
8106 | # TTL BOX flags port protocol recordtype priority weight port target | 8122 | # TTL BOX flags port protocol recordtype priority weight port target |
8107 | 14000 BOX n 5060 6 33 0 0 5060 www.example.com | 8123 | 14000 BOX n 5060 6 33 0 0 5060 www.example.com |
8108 | @end example | 8124 | @end example |
8109 | 8125 | ||
8110 | Other records that have such a transformation is the MX record type, as well as | 8126 | Other records that have such a transformation is the MX record type, |
8111 | the SOA record type. | 8127 | as well as the SOA record type. |
8128 | |||
8129 | Transformation of a SOA record into GNS works as described in the | ||
8130 | following example. Very important to note are the rname and mname keys. | ||
8112 | 8131 | ||
8113 | Transformation of a SOA record into GNS works as described in the following | ||
8114 | example. Very important to note are the rname and mname keys. | ||
8115 | @example | 8132 | @example |
8116 | # BIND syntax for a clean SOA record | 8133 | # BIND syntax for a clean SOA record |
8117 | @ IN SOA master.example.com. hostmaster.example.com. ( | 8134 | @ IN SOA master.example.com. hostmaster.example.com. ( |
@@ -8235,7 +8252,7 @@ that uses the C API would be cleaner and better. | |||
8235 | @node GNS Namecache | 8252 | @node GNS Namecache |
8236 | @section GNS Namecache | 8253 | @section GNS Namecache |
8237 | 8254 | ||
8238 | @c %**end of header | 8255 | |
8239 | 8256 | ||
8240 | The NAMECACHE subsystem is responsible for caching (encrypted) resolution | 8257 | The NAMECACHE subsystem is responsible for caching (encrypted) resolution |
8241 | results of the GNU Name System (GNS). GNS makes zone information available | 8258 | results of the GNU Name System (GNS). GNS makes zone information available |
@@ -8274,7 +8291,7 @@ plugin API. | |||
8274 | @node libgnunetnamecache | 8291 | @node libgnunetnamecache |
8275 | @subsection libgnunetnamecache | 8292 | @subsection libgnunetnamecache |
8276 | 8293 | ||
8277 | @c %**end of header | 8294 | |
8278 | 8295 | ||
8279 | The NAMECACHE API consists of five simple functions. First, there is | 8296 | The NAMECACHE API consists of five simple functions. First, there is |
8280 | @code{GNUNET_NAMECACHE_connect} to connect to the NAMECACHE service. | 8297 | @code{GNUNET_NAMECACHE_connect} to connect to the NAMECACHE service. |
@@ -8297,7 +8314,7 @@ The maximum size of a block that can be stored in the NAMECACHE is | |||
8297 | @node The NAMECACHE Client-Service Protocol | 8314 | @node The NAMECACHE Client-Service Protocol |
8298 | @subsection The NAMECACHE Client-Service Protocol | 8315 | @subsection The NAMECACHE Client-Service Protocol |
8299 | 8316 | ||
8300 | @c %**end of header | 8317 | |
8301 | 8318 | ||
8302 | All messages in the NAMECACHE IPC protocol start with the | 8319 | All messages in the NAMECACHE IPC protocol start with the |
8303 | @code{struct GNUNET_NAMECACHE_Header} which adds a request | 8320 | @code{struct GNUNET_NAMECACHE_Header} which adds a request |
@@ -8315,7 +8332,7 @@ out-of-order. | |||
8315 | @node Lookup | 8332 | @node Lookup |
8316 | @subsubsection Lookup | 8333 | @subsubsection Lookup |
8317 | 8334 | ||
8318 | @c %**end of header | 8335 | |
8319 | 8336 | ||
8320 | The @code{struct LookupBlockMessage} is used to lookup a block stored in | 8337 | The @code{struct LookupBlockMessage} is used to lookup a block stored in |
8321 | the cache. | 8338 | the cache. |
@@ -8329,7 +8346,7 @@ of the block. | |||
8329 | @node Store | 8346 | @node Store |
8330 | @subsubsection Store | 8347 | @subsubsection Store |
8331 | 8348 | ||
8332 | @c %**end of header | 8349 | |
8333 | 8350 | ||
8334 | The @code{struct BlockCacheMessage} is used to cache a block in the | 8351 | The @code{struct BlockCacheMessage} is used to cache a block in the |
8335 | NAMECACHE. | 8352 | NAMECACHE. |
@@ -8341,7 +8358,7 @@ message as well. | |||
8341 | 8358 | ||
8342 | @node The NAMECACHE Plugin API | 8359 | @node The NAMECACHE Plugin API |
8343 | @subsection The NAMECACHE Plugin API | 8360 | @subsection The NAMECACHE Plugin API |
8344 | @c %**end of header | 8361 | |
8345 | 8362 | ||
8346 | The NAMECACHE plugin API consists of two functions, @code{cache_block} to | 8363 | The NAMECACHE plugin API consists of two functions, @code{cache_block} to |
8347 | store a block in the database, and @code{lookup_block} to lookup a block | 8364 | store a block in the database, and @code{lookup_block} to lookup a block |
@@ -8356,7 +8373,7 @@ in the database. | |||
8356 | @node Lookup2 | 8373 | @node Lookup2 |
8357 | @subsubsection Lookup2 | 8374 | @subsubsection Lookup2 |
8358 | 8375 | ||
8359 | @c %**end of header | 8376 | |
8360 | 8377 | ||
8361 | The @code{lookup_block} function is expected to return at most one block | 8378 | The @code{lookup_block} function is expected to return at most one block |
8362 | to the iterator, and return @code{GNUNET_NO} if there were no non-expired | 8379 | to the iterator, and return @code{GNUNET_NO} if there were no non-expired |
@@ -8367,7 +8384,7 @@ supposed to return the result with the largest expiration time. | |||
8367 | @node Store2 | 8384 | @node Store2 |
8368 | @subsubsection Store2 | 8385 | @subsubsection Store2 |
8369 | 8386 | ||
8370 | @c %**end of header | 8387 | |
8371 | 8388 | ||
8372 | The @code{cache_block} function is expected to try to store the block in | 8389 | The @code{cache_block} function is expected to try to store the block in |
8373 | the database, and return @code{GNUNET_SYSERR} if this was not possible | 8390 | the database, and return @code{GNUNET_SYSERR} if this was not possible |
@@ -8384,7 +8401,7 @@ block is more recent during the store operation. | |||
8384 | @cindex REVOCATION Subsystem | 8401 | @cindex REVOCATION Subsystem |
8385 | @node REVOCATION Subsystem | 8402 | @node REVOCATION Subsystem |
8386 | @section REVOCATION Subsystem | 8403 | @section REVOCATION Subsystem |
8387 | @c %**end of header | 8404 | |
8388 | 8405 | ||
8389 | The REVOCATION subsystem is responsible for key revocation of Egos. | 8406 | The REVOCATION subsystem is responsible for key revocation of Egos. |
8390 | If a user learns that theis private key has been compromised or has lost | 8407 | If a user learns that theis private key has been compromised or has lost |
@@ -8404,7 +8421,7 @@ propagate revocation messages. | |||
8404 | @node Dissemination | 8421 | @node Dissemination |
8405 | @subsection Dissemination | 8422 | @subsection Dissemination |
8406 | 8423 | ||
8407 | @c %**end of header | 8424 | |
8408 | 8425 | ||
8409 | When a revocation is performed, the revocation is first of all | 8426 | When a revocation is performed, the revocation is first of all |
8410 | disseminated by flooding the overlay network. | 8427 | disseminated by flooding the overlay network. |
@@ -8428,7 +8445,7 @@ The SET service is used to perform this operation efficiently. | |||
8428 | @node Revocation Message Design Requirements | 8445 | @node Revocation Message Design Requirements |
8429 | @subsection Revocation Message Design Requirements | 8446 | @subsection Revocation Message Design Requirements |
8430 | 8447 | ||
8431 | @c %**end of header | 8448 | |
8432 | 8449 | ||
8433 | However, flooding is also quite costly, creating O(|E|) messages on a | 8450 | However, flooding is also quite costly, creating O(|E|) messages on a |
8434 | network with |E| edges. | 8451 | network with |E| edges. |
@@ -8450,7 +8467,7 @@ revocation message ahead of time and store it in a secure location. | |||
8450 | @node libgnunetrevocation | 8467 | @node libgnunetrevocation |
8451 | @subsection libgnunetrevocation | 8468 | @subsection libgnunetrevocation |
8452 | 8469 | ||
8453 | @c %**end of header | 8470 | |
8454 | 8471 | ||
8455 | The REVOCATION API consists of two parts, to query and to issue | 8472 | The REVOCATION API consists of two parts, to query and to issue |
8456 | revocations. | 8473 | revocations. |
@@ -8465,7 +8482,7 @@ revocations. | |||
8465 | @node Querying for revoked keys | 8482 | @node Querying for revoked keys |
8466 | @subsubsection Querying for revoked keys | 8483 | @subsubsection Querying for revoked keys |
8467 | 8484 | ||
8468 | @c %**end of header | 8485 | |
8469 | 8486 | ||
8470 | @code{GNUNET_REVOCATION_query} is used to check if a given ECDSA public | 8487 | @code{GNUNET_REVOCATION_query} is used to check if a given ECDSA public |
8471 | key has been revoked. | 8488 | key has been revoked. |
@@ -8476,7 +8493,7 @@ the return value. | |||
8476 | @node Preparing revocations | 8493 | @node Preparing revocations |
8477 | @subsubsection Preparing revocations | 8494 | @subsubsection Preparing revocations |
8478 | 8495 | ||
8479 | @c %**end of header | 8496 | |
8480 | 8497 | ||
8481 | It is often desirable to create a revocation record ahead-of-time and | 8498 | It is often desirable to create a revocation record ahead-of-time and |
8482 | store it in an off-line location to be used later in an emergency. | 8499 | store it in an off-line location to be used later in an emergency. |
@@ -8544,7 +8561,7 @@ successfully. | |||
8544 | @node The REVOCATION Peer-to-Peer Protocol | 8561 | @node The REVOCATION Peer-to-Peer Protocol |
8545 | @subsection The REVOCATION Peer-to-Peer Protocol | 8562 | @subsection The REVOCATION Peer-to-Peer Protocol |
8546 | 8563 | ||
8547 | @c %**end of header | 8564 | |
8548 | 8565 | ||
8549 | Revocation uses two disjoint ways to spread revocation information among | 8566 | Revocation uses two disjoint ways to spread revocation information among |
8550 | peers. | 8567 | peers. |
@@ -8579,7 +8596,7 @@ larger hashed peer identity. | |||
8579 | @node File-sharing (FS) Subsystem | 8596 | @node File-sharing (FS) Subsystem |
8580 | @section File-sharing (FS) Subsystem | 8597 | @section File-sharing (FS) Subsystem |
8581 | 8598 | ||
8582 | @c %**end of header | 8599 | |
8583 | 8600 | ||
8584 | This chapter describes the details of how the file-sharing service works. | 8601 | This chapter describes the details of how the file-sharing service works. |
8585 | As with all services, it is split into an API (libgnunetfs), the service | 8602 | As with all services, it is split into an API (libgnunetfs), the service |
@@ -8617,7 +8634,7 @@ NOTE: The documentation in this chapter is quite incomplete. | |||
8617 | @node Encoding for Censorship-Resistant Sharing (ECRS) | 8634 | @node Encoding for Censorship-Resistant Sharing (ECRS) |
8618 | @subsection Encoding for Censorship-Resistant Sharing (ECRS) | 8635 | @subsection Encoding for Censorship-Resistant Sharing (ECRS) |
8619 | 8636 | ||
8620 | @c %**end of header | 8637 | |
8621 | 8638 | ||
8622 | When GNUnet shares files, it uses a content encoding that is called ECRS, | 8639 | When GNUnet shares files, it uses a content encoding that is called ECRS, |
8623 | the Encoding for Censorship-Resistant Sharing. | 8640 | the Encoding for Censorship-Resistant Sharing. |
@@ -8639,7 +8656,7 @@ thus did not warrant space in the research report. | |||
8639 | @node Namespace Advertisements | 8656 | @node Namespace Advertisements |
8640 | @subsubsection Namespace Advertisements | 8657 | @subsubsection Namespace Advertisements |
8641 | 8658 | ||
8642 | @c %**end of header | 8659 | |
8643 | @c %**FIXME: all zeroses -> ? | 8660 | @c %**FIXME: all zeroses -> ? |
8644 | 8661 | ||
8645 | An @code{SBlock} with identifier all zeros is a signed | 8662 | An @code{SBlock} with identifier all zeros is a signed |
@@ -8654,7 +8671,7 @@ can search for @code{SBlock}s in order to find out more about a namespace. | |||
8654 | @node KSBlocks | 8671 | @node KSBlocks |
8655 | @subsubsection KSBlocks | 8672 | @subsubsection KSBlocks |
8656 | 8673 | ||
8657 | @c %**end of header | 8674 | |
8658 | 8675 | ||
8659 | GNUnet implements @code{KSBlocks} which are @code{KBlocks} that, instead | 8676 | GNUnet implements @code{KSBlocks} which are @code{KBlocks} that, instead |
8660 | of encrypting a CHK and metadata, encrypt an @code{SBlock} instead. | 8677 | of encrypting a CHK and metadata, encrypt an @code{SBlock} instead. |
@@ -8680,7 +8697,7 @@ Collections are also advertised using @code{KSBlock}s. | |||
8680 | @node File-sharing persistence directory structure | 8697 | @node File-sharing persistence directory structure |
8681 | @subsection File-sharing persistence directory structure | 8698 | @subsection File-sharing persistence directory structure |
8682 | 8699 | ||
8683 | @c %**end of header | 8700 | |
8684 | 8701 | ||
8685 | This section documents how the file-sharing library implements | 8702 | This section documents how the file-sharing library implements |
8686 | persistence of file-sharing operations and specifically the resulting | 8703 | persistence of file-sharing operations and specifically the resulting |
@@ -8766,7 +8783,7 @@ Note that unindex operations cannot have associated child operations. | |||
8766 | @node REGEX Subsystem | 8783 | @node REGEX Subsystem |
8767 | @section REGEX Subsystem | 8784 | @section REGEX Subsystem |
8768 | 8785 | ||
8769 | @c %**end of header | 8786 | |
8770 | 8787 | ||
8771 | Using the REGEX subsystem, you can discover peers that offer a particular | 8788 | Using the REGEX subsystem, you can discover peers that offer a particular |
8772 | service using regular expressions. | 8789 | service using regular expressions. |
@@ -8789,7 +8806,7 @@ thesis. | |||
8789 | @node How to run the regex profiler | 8806 | @node How to run the regex profiler |
8790 | @subsection How to run the regex profiler | 8807 | @subsection How to run the regex profiler |
8791 | 8808 | ||
8792 | @c %**end of header | 8809 | |
8793 | 8810 | ||
8794 | The gnunet-regex-profiler can be used to profile the usage of mesh/regex | 8811 | The gnunet-regex-profiler can be used to profile the usage of mesh/regex |
8795 | for a given set of regular expressions and strings. | 8812 | for a given set of regular expressions and strings. |
@@ -8922,7 +8939,7 @@ regular expressions. | |||
8922 | @node REST Subsystem | 8939 | @node REST Subsystem |
8923 | @section REST Subsystem | 8940 | @section REST Subsystem |
8924 | 8941 | ||
8925 | @c %**end of header | 8942 | |
8926 | 8943 | ||
8927 | Using the REST subsystem, you can expose REST-based APIs or services. | 8944 | Using the REST subsystem, you can expose REST-based APIs or services. |
8928 | The REST service is designed as a pluggable architecture. | 8945 | The REST service is designed as a pluggable architecture. |