diff options
Diffstat (limited to 'doc/documentation/chapters')
-rw-r--r-- | doc/documentation/chapters/developer.texi | 58 |
1 files changed, 32 insertions, 26 deletions
diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi index e82e32b59..4038190a1 100644 --- a/doc/documentation/chapters/developer.texi +++ b/doc/documentation/chapters/developer.texi | |||
@@ -11,7 +11,8 @@ For developers, GNUnet is: | |||
11 | @itemize @bullet | 11 | @itemize @bullet |
12 | @item developed by a community that believes in the GNU philosophy | 12 | @item developed by a community that believes in the GNU philosophy |
13 | @item Free Software (Free as in Freedom), licensed under the | 13 | @item Free Software (Free as in Freedom), licensed under the |
14 | GNU Affero General Public License@footnote{@uref{https://www.gnu.org/licenses/licenses.html#AGPL, https://www.gnu.org/licenses/licenses.html#AGPL}} | 14 | GNU Affero General Public License |
15 | (@uref{https://www.gnu.org/licenses/licenses.html#AGPL}) | ||
15 | @item A set of standards, including coding conventions and | 16 | @item A set of standards, including coding conventions and |
16 | architectural rules | 17 | architectural rules |
17 | @item A set of layered protocols, both specifying the communication | 18 | @item A set of layered protocols, both specifying the communication |
@@ -136,7 +137,7 @@ It can be accessed at | |||
136 | Anyone can report bugs. | 137 | Anyone can report bugs. |
137 | 138 | ||
138 | @item Our site installation of the | 139 | @item Our site installation of the |
139 | CI@footnote{Continuous Integration} system @code{Buildbot} is used | 140 | Continuous Integration (CI) system @code{Buildbot} is used |
140 | to check GNUnet builds automatically on a range of platforms. | 141 | to check GNUnet builds automatically on a range of platforms. |
141 | The web interface of this CI is exposed at | 142 | The web interface of this CI is exposed at |
142 | @uref{https://gnunet.org/buildbot/, https://gnunet.org/buildbot/}. | 143 | @uref{https://gnunet.org/buildbot/, https://gnunet.org/buildbot/}. |
@@ -1230,7 +1231,11 @@ right set of features. We called this specialized set of libcurl | |||
1230 | by GNUnet and some of its dependencies. | 1231 | by GNUnet and some of its dependencies. |
1231 | 1232 | ||
1232 | We download libgnurl and its digital signature from the GNU fileserver, | 1233 | We download libgnurl and its digital signature from the GNU fileserver, |
1233 | assuming @env{TMPDIR} exists@footnote{It might be @file{/tmp}, @env{TMPDIR}, @env{TMP} or any other location. For consistency we assume @env{TMPDIR} points to @file{/tmp} for the remainder of this section.} | 1234 | assuming @env{TMPDIR} exists. |
1235 | |||
1236 | Note: TMPDIR might be @file{/tmp}, @env{TMPDIR}, @env{TMP} or any other | ||
1237 | location. For consistency we assume @env{TMPDIR} points to @file{/tmp} | ||
1238 | for the remainder of this section. | ||
1234 | 1239 | ||
1235 | @example | 1240 | @example |
1236 | cd \$TMPDIR | 1241 | cd \$TMPDIR |
@@ -1898,9 +1903,9 @@ random links are to be given | |||
1898 | @item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a | 1903 | @item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a |
1899 | topology where peer connectivity follows power law - new peers are | 1904 | topology where peer connectivity follows power law - new peers are |
1900 | connected with high probability to well connected peers. | 1905 | connected with high probability to well connected peers. |
1901 | @footnote{See Emergence of Scaling in Random Networks. Science 286, | 1906 | (See Emergence of Scaling in Random Networks. Science 286, |
1902 | 509-512, 1999 | 1907 | 509-512, 1999 |
1903 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/emergence_of_scaling_in_random_networks__barabasi_albert_science_286__1999.pdf, pdf})} | 1908 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/emergence_of_scaling_in_random_networks__barabasi_albert_science_286__1999.pdf, pdf})) |
1904 | 1909 | ||
1905 | @item @code{GNUNET_TESTBED_TOPOLOGY_FROM_FILE}: The topology information | 1910 | @item @code{GNUNET_TESTBED_TOPOLOGY_FROM_FILE}: The topology information |
1906 | is loaded from a file. The path to the file has to be given. | 1911 | is loaded from a file. The path to the file has to be given. |
@@ -2294,7 +2299,8 @@ subsystem. | |||
2294 | @node CORE must be started | 2299 | @node CORE must be started |
2295 | @subsubsection CORE must be started | 2300 | @subsubsection CORE must be started |
2296 | 2301 | ||
2297 | A uncomplicated issue is bug #3993@footnote{@uref{https://gnunet.org/bugs/view.php?id=3993, https://gnunet.org/bugs/view.php?id=3993}}: | 2302 | A uncomplicated issue is bug #3993 |
2303 | (@uref{https://gnunet.org/bugs/view.php?id=3993, https://gnunet.org/bugs/view.php?id=3993}): | ||
2298 | Your configuration MUST somehow ensure that for each peer the | 2304 | Your configuration MUST somehow ensure that for each peer the |
2299 | @code{CORE} service is started when the peer is setup, otherwise | 2305 | @code{CORE} service is started when the peer is setup, otherwise |
2300 | @code{TESTBED} may fail to connect peers when the topology is initialized, | 2306 | @code{TESTBED} may fail to connect peers when the topology is initialized, |
@@ -3941,11 +3947,8 @@ considers Bob's address to be valid, the connection itself is not | |||
3941 | considered 'established'. In particular, Alice may have many addresses | 3947 | considered 'established'. In particular, Alice may have many addresses |
3942 | for Bob that Alice considers valid. | 3948 | for Bob that Alice considers valid. |
3943 | 3949 | ||
3944 | @c TODO: reference Footnotes so that I don't have to duplicate the | ||
3945 | @c footnotes or add them to an index at the end. Is this possible at | ||
3946 | @c all in Texinfo? | ||
3947 | The @code{PONG} message is protected with a nonce/challenge against replay | 3950 | The @code{PONG} message is protected with a nonce/challenge against replay |
3948 | attacks@footnote{@uref{http://en.wikipedia.org/wiki/Replay_attack, replay}} | 3951 | attacks (@uref{http://en.wikipedia.org/wiki/Replay_attack, replay}) |
3949 | and uses an expiration time for the signature (but those are almost | 3952 | and uses an expiration time for the signature (but those are almost |
3950 | implementation details). | 3953 | implementation details). |
3951 | 3954 | ||
@@ -4773,23 +4776,24 @@ then adds fundamental security to the connections: | |||
4773 | 4776 | ||
4774 | @itemize @bullet | 4777 | @itemize @bullet |
4775 | @item confidentiality with so-called perfect forward secrecy; we use | 4778 | @item confidentiality with so-called perfect forward secrecy; we use |
4776 | ECDHE@footnote{@uref{http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman, Elliptic-curve Diffie---Hellman}} | 4779 | ECDHE |
4780 | (@uref{http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman, Elliptic-curve Diffie---Hellman}) | ||
4777 | powered by Curve25519 | 4781 | powered by Curve25519 |
4778 | @footnote{@uref{http://cr.yp.to/ecdh.html, Curve25519}} for the key | 4782 | (@uref{http://cr.yp.to/ecdh.html, Curve25519}) for the key |
4779 | exchange and then use symmetric encryption, encrypting with both AES-256 | 4783 | exchange and then use symmetric encryption, encrypting with both AES-256 |
4780 | @footnote{@uref{http://en.wikipedia.org/wiki/Rijndael, AES-256}} and | 4784 | (@uref{http://en.wikipedia.org/wiki/Rijndael, AES-256}) and |
4781 | Twofish @footnote{@uref{http://en.wikipedia.org/wiki/Twofish, Twofish}} | 4785 | Twofish (@uref{http://en.wikipedia.org/wiki/Twofish, Twofish}) |
4782 | @item @uref{http://en.wikipedia.org/wiki/Authentication, authentication} | 4786 | @item @uref{http://en.wikipedia.org/wiki/Authentication, authentication} |
4783 | is achieved by signing the ephemeral keys using Ed25519 | 4787 | is achieved by signing the ephemeral keys using Ed25519 |
4784 | @footnote{@uref{http://ed25519.cr.yp.to/, Ed25519}}, a deterministic | 4788 | (@uref{http://ed25519.cr.yp.to/, Ed25519}), a deterministic |
4785 | variant of ECDSA | 4789 | variant of ECDSA |
4786 | @footnote{@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}} | 4790 | (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}) |
4787 | @item integrity protection (using SHA-512 | 4791 | @item integrity protection (using SHA-512 |
4788 | @footnote{@uref{http://en.wikipedia.org/wiki/SHA-2, SHA-512}} to do | 4792 | (@uref{http://en.wikipedia.org/wiki/SHA-2, SHA-512}) to do |
4789 | encrypt-then-MAC | 4793 | encrypt-then-MAC |
4790 | @footnote{@uref{http://en.wikipedia.org/wiki/Authenticated_encryption, encrypt-then-MAC}}) | 4794 | (@uref{http://en.wikipedia.org/wiki/Authenticated_encryption, encrypt-then-MAC})) |
4791 | @item Replay | 4795 | @item Replay |
4792 | @footnote{@uref{http://en.wikipedia.org/wiki/Replay_attack, replay}} | 4796 | (@uref{http://en.wikipedia.org/wiki/Replay_attack, replay}) |
4793 | protection (using nonces, timestamps, challenge-response, | 4797 | protection (using nonces, timestamps, challenge-response, |
4794 | message counters and ephemeral keys) | 4798 | message counters and ephemeral keys) |
4795 | @item liveness (keep-alive messages, timeout) | 4799 | @item liveness (keep-alive messages, timeout) |
@@ -5037,7 +5041,8 @@ public-private key pair and signs the corresponding | |||
5037 | @code{EphemeralKeyMessage} with its long-term key (which we usually call | 5041 | @code{EphemeralKeyMessage} with its long-term key (which we usually call |
5038 | the peer's identity; the hash of the public long term key is what results | 5042 | the peer's identity; the hash of the public long term key is what results |
5039 | in a @code{struct GNUNET_PeerIdentity} in all GNUnet APIs. The ephemeral | 5043 | in a @code{struct GNUNET_PeerIdentity} in all GNUnet APIs. The ephemeral |
5040 | key is ONLY used for an ECDHE@footnote{@uref{http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman, Elliptic-curve Diffie---Hellman}} | 5044 | key is ONLY used for an ECDHE |
5045 | (@uref{http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman, Elliptic-curve Diffie---Hellman}) | ||
5041 | exchange by the CORE service to establish symmetric session keys. A peer | 5046 | exchange by the CORE service to establish symmetric session keys. A peer |
5042 | will use the same @code{EphemeralKeyMessage} for all peers for | 5047 | will use the same @code{EphemeralKeyMessage} for all peers for |
5043 | @code{REKEY_FREQUENCY}, which is usually 12 hours. After that time, it | 5048 | @code{REKEY_FREQUENCY}, which is usually 12 hours. After that time, it |
@@ -5094,10 +5099,11 @@ All functions related to the key exchange and encryption/decryption of | |||
5094 | messages can be found in @file{gnunet-service-core_kx.c} (except for the | 5099 | messages can be found in @file{gnunet-service-core_kx.c} (except for the |
5095 | cryptographic primitives, which are in @file{util/crypto*.c}). | 5100 | cryptographic primitives, which are in @file{util/crypto*.c}). |
5096 | Given the key material from ECDHE, a Key derivation function | 5101 | Given the key material from ECDHE, a Key derivation function |
5097 | @footnote{@uref{https://en.wikipedia.org/wiki/Key_derivation_function, Key derivation function}} | 5102 | (@uref{https://en.wikipedia.org/wiki/Key_derivation_function, Key derivation function}) |
5098 | is used to derive two pairs of encryption and decryption keys for AES-256 | 5103 | is used to derive two pairs of encryption and decryption keys for AES-256 |
5099 | and TwoFish, as well as initialization vectors and authentication keys | 5104 | and TwoFish, as well as initialization vectors and authentication keys |
5100 | (for HMAC@footnote{@uref{https://en.wikipedia.org/wiki/HMAC, HMAC}}). | 5105 | (for HMAC |
5106 | (@uref{https://en.wikipedia.org/wiki/HMAC, HMAC})). | ||
5101 | The HMAC is computed over the encrypted payload. | 5107 | The HMAC is computed over the encrypted payload. |
5102 | Encrypted messages include an iv_seed and the HMAC in the header. | 5108 | Encrypted messages include an iv_seed and the HMAC in the header. |
5103 | 5109 | ||
@@ -5523,15 +5529,15 @@ Let's close with a couple examples. | |||
5523 | @table @asis | 5529 | @table @asis |
5524 | 5530 | ||
5525 | @item Average: 10, std dev: 1 Here the estimate would be | 5531 | @item Average: 10, std dev: 1 Here the estimate would be |
5526 | 2^10 = 1024 peers. @footnote{The range in which we can be 95% sure is: | 5532 | 2^10 = 1024 peers. (The range in which we can be 95% sure is: |
5527 | [2^8, 2^12] = [256, 4096]. We can be very (>99.7%) sure that the network | 5533 | [2^8, 2^12] = [256, 4096]. We can be very (>99.7%) sure that the network |
5528 | is not a hundred peers and absolutely sure that it is not a million peers, | 5534 | is not a hundred peers and absolutely sure that it is not a million peers, |
5529 | but somewhere around a thousand.} | 5535 | but somewhere around a thousand.) |
5530 | 5536 | ||
5531 | @item Average 22, std dev: 0.2 Here the estimate would be | 5537 | @item Average 22, std dev: 0.2 Here the estimate would be |
5532 | 2^22 = 4 Million peers. @footnote{The range in which we can be 99.7% sure | 5538 | 2^22 = 4 Million peers. (The range in which we can be 99.7% sure |
5533 | is: [2^21.4, 2^22.6] = [2.8M, 6.3M]. We can be sure that the network size | 5539 | is: [2^21.4, 2^22.6] = [2.8M, 6.3M]. We can be sure that the network size |
5534 | is around four million, with absolutely way of it being 1 million.} | 5540 | is around four million, with absolutely way of it being 1 million.) |
5535 | 5541 | ||
5536 | @end table | 5542 | @end table |
5537 | 5543 | ||