diff options
Diffstat (limited to 'doc/handbook/chapters')
-rw-r--r-- | doc/handbook/chapters/developer.texi | 215 | ||||
-rw-r--r-- | doc/handbook/chapters/keyconcepts.texi | 25 | ||||
-rw-r--r-- | doc/handbook/chapters/user.texi | 147 |
3 files changed, 387 insertions, 0 deletions
diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi index 8bc8c8005..abd128e3b 100644 --- a/doc/handbook/chapters/developer.texi +++ b/doc/handbook/chapters/developer.texi | |||
@@ -83,6 +83,7 @@ new chapters, sections or insightful comments. | |||
83 | * REST Subsystem:: | 83 | * REST Subsystem:: |
84 | * RPS Subsystem:: | 84 | * RPS Subsystem:: |
85 | * TRANSPORT-NG Subsystem:: | 85 | * TRANSPORT-NG Subsystem:: |
86 | * MESSENGER Subsystem:: | ||
86 | @end menu | 87 | @end menu |
87 | 88 | ||
88 | @node Developer Introduction | 89 | @node Developer Introduction |
@@ -9705,3 +9706,217 @@ other peers. The semantics of the backchannel message are up to the | |||
9705 | communicators which use them. | 9706 | communicators which use them. |
9706 | TRANSPORT may fail transmitting backchannel messages, and TRANSPORT will not | 9707 | TRANSPORT may fail transmitting backchannel messages, and TRANSPORT will not |
9707 | attempt to retransmit them. | 9708 | attempt to retransmit them. |
9709 | |||
9710 | @cindex MESSENGER Subsystem | ||
9711 | @cindex MESSENGER | ||
9712 | @cindex messenger | ||
9713 | @node MESSENGER Subsystem | ||
9714 | @section MESSENGER Subsystem | ||
9715 | |||
9716 | The MESSENGER subsystem is responsible for secure end-to-end communication in | ||
9717 | groups of nodes in the GNUnet overlay network. MESSENGER builds on the CADET | ||
9718 | subsystem which provides a reliable and secure end-to-end communication between | ||
9719 | the nodes inside of these groups. | ||
9720 | |||
9721 | Additionally to the CADET security benefits, MESSENGER provides following | ||
9722 | properties designed for application level usage: | ||
9723 | |||
9724 | @itemize @bullet | ||
9725 | @item MESSENGER provides integrity by signing the messages with the users | ||
9726 | provided ego | ||
9727 | @item MESSENGER adds (optional) forward secrecy by replacing the key pair of the | ||
9728 | used ego and signing the propagation of the new one with old one (chaining | ||
9729 | egos) | ||
9730 | @item MESSENGER provides verification of a original sender by checking against | ||
9731 | all used egos from a member which are currently in active use (active use | ||
9732 | depends on the state of a member session) | ||
9733 | @item MESSENGER offsers (optional) decentralized message forwarding between all | ||
9734 | nodes in a group to improve availability and prevent MITM-attacks | ||
9735 | @item MESSENGER handles new connections and disconnections from nodes in the | ||
9736 | group by reconnecting them preserving an efficient structure for message | ||
9737 | distribution (ensuring availability and accountablity) | ||
9738 | @item MESSENGER provides replay protection (messages can be uniquely identified | ||
9739 | via SHA-512, include a timestamp and the hash of the last message) | ||
9740 | @item MESSENGER allows detection for dropped messages by chaining them (messages | ||
9741 | refer to the last message by their hash) improving accountability | ||
9742 | @item MESSENGER allows requesting messages from other peers explicitly to ensure | ||
9743 | availibility | ||
9744 | @item MESSENGER provides confidentiality by padding messages to few different | ||
9745 | sizes (512 bytes, 4096 bytes, 32768 bytes and maximal message size from | ||
9746 | CADET) | ||
9747 | @item MESSENGER adds (optional) confidentiality with ECDHE to exchange and use | ||
9748 | symmetric encryption, encrypting with both AES-256 and Twofish but | ||
9749 | allowing only selected members to decrypt (using the receivers ego for | ||
9750 | ECDHE) | ||
9751 | @end itemize | ||
9752 | |||
9753 | Also MESSENGER provides multiple features with privacy in mind: | ||
9754 | |||
9755 | @itemize @bullet | ||
9756 | @item MESSENGER allows deleting messages from all peers in the group by the | ||
9757 | original sender (uses the MESSENGER provided verification) | ||
9758 | @item MESSENGER allows using the publically known anonymous ego instead of any | ||
9759 | unique identifying ego | ||
9760 | @item MESSENGER allows your node to decide between acting as host of the used | ||
9761 | messaging room (sharing your peer's identity with all nodes in the group) | ||
9762 | or acting as guest (sharing your peer's identity only with the nodes you | ||
9763 | explicitly open a connection to) | ||
9764 | @item MESSENGER handles members independantly of the peer's identity making | ||
9765 | forwarded messages indistinguishable from directly received ones ( | ||
9766 | complicating the tracking of messages and identifying its origin) | ||
9767 | @item MESSENGER allows names of members being not unique (also names are | ||
9768 | optional) | ||
9769 | @item MESSENGER does not include information about the selected receiver of an | ||
9770 | explicitly encrypted message in its header, complicating it for other | ||
9771 | members to draw conclusions from communication partners | ||
9772 | @end itemize | ||
9773 | |||
9774 | @menu | ||
9775 | * libgnunetmessenger:: | ||
9776 | * Member sessions:: | ||
9777 | @end menu | ||
9778 | |||
9779 | @node libgnunetmessenger | ||
9780 | @subsection libgnunetmessenger | ||
9781 | |||
9782 | The MESSENGER API (defined in @file{gnunet_messenger_service.h}) allows P2P | ||
9783 | applications built using GNUnet to communicate with specified kinds of messages | ||
9784 | in a group. It provides applications the ability to send and receive encrypted | ||
9785 | messages to any group of peers participating in GNUnet in a decentralized way ( | ||
9786 | without even knowing all peers's identities). | ||
9787 | |||
9788 | MESSENGER delivers messages to other peers in "rooms". A room uses a variable | ||
9789 | amount of CADET "channels" which will all be used for message distribution. Each | ||
9790 | channel can represent an outgoing connection opened by entering a room with | ||
9791 | @code{GNUNET_MESSENGER_enter_room} or an incoming connection if the room was | ||
9792 | opened before via @code{GNUNET_MESSENGER_open_room}. | ||
9793 | |||
9794 | @image{images/messenger_room.png} | ||
9795 | |||
9796 | To enter a room you have to specify the "door" (peer's identity of a peer which | ||
9797 | has opened the room) and the key of the room (which is identical to a CADET | ||
9798 | "port"). To open a room you have to specify only the key to use. When opening a | ||
9799 | room you automatically distribute a PEER-message sharing your peer's identity in | ||
9800 | the room. | ||
9801 | |||
9802 | Entering or opening a room can also be combined in any order. In any case you | ||
9803 | will automatically get a unique member ID and send a JOIN-message notifying | ||
9804 | others about your entry and your public key from your selected ego. | ||
9805 | |||
9806 | The ego can be selected by name with the initial @code{GNUNET_MESSENGER_connect} | ||
9807 | besides setting a (identity-)callback for each change/confirmation of the used | ||
9808 | ego and a (message-)callback which gets called every time a message gets sent or | ||
9809 | received in the room. Once the identity-callback got called you can check your | ||
9810 | used ego with @code{GNUNET_MESSENGER_get_key} providing only its public key. The | ||
9811 | function returns NULL if the anonymous ego is used. If the ego should be | ||
9812 | replaced with a newly generated one, you can use @code{GNUNET_MESSENGER_update} | ||
9813 | to ensure proper chaining of used egos. | ||
9814 | |||
9815 | Also once the identity-callback got called you can check your used name with | ||
9816 | @code{GNUNET_MESSENGER_get_name} and potentially change or set a name via | ||
9817 | @code{GNUNET_MESSENGER_set_name}. A name is for example required to create a new | ||
9818 | ego with @code{GNUNET_MESSENGER_update}. Also any change in ego or name will | ||
9819 | automatically be distributed in the room with a NAME- or KEY-message | ||
9820 | respectively. | ||
9821 | |||
9822 | To send a message a message inside of a room you can use | ||
9823 | @code{GNUNET_MESSENGER_send_message}. If you specify a selected contact as | ||
9824 | receiver, the message gets encrypted automatically and will be sent as PRIVATE- | ||
9825 | message instead. | ||
9826 | |||
9827 | To request a potentially missed message or to get a specific message after its | ||
9828 | original call of the message-callback, you can use | ||
9829 | @code{GNUNET_MESSENGER_get_message}. Additionally once a message was distributed | ||
9830 | to application level and the message-callback got called, you can get the | ||
9831 | contact respresenting a message's sender respectively with | ||
9832 | @code{GNUNET_MESSENGER_get_sender}. This allows getting name and the public key | ||
9833 | of any sender currently in use with @code{GNUNET_MESSENGER_contact_get_name} | ||
9834 | and @code{GNUNET_MESSENGER_contact_get_key}. It is also possible to iterate | ||
9835 | through all current members of a room with | ||
9836 | @code{GNUNET_MESSENGER_iterate_members} using a callback. | ||
9837 | |||
9838 | To leave a room you can use @code{GNUNET_MESSENGER_close_room} which will also | ||
9839 | close the rooms connections once all applications on the same peer have left | ||
9840 | the room. Leaving a room will also send a LEAVE-message closing a member session | ||
9841 | on all connected peers before any connection will be closed. Leaving a room is | ||
9842 | however not required for any application to keep your member session open | ||
9843 | between multiple sessions of the actual application. | ||
9844 | |||
9845 | Finally, when an application no longer wants to use CADET, it should call | ||
9846 | @code{GNUNET_MESSENGER_disconnect}. You don't have to explicitly close the used | ||
9847 | rooms or leave them. | ||
9848 | |||
9849 | Here is a little summary to the kinds of messages you can send manually: | ||
9850 | |||
9851 | @menu | ||
9852 | * MERGE-message:: | ||
9853 | * INVITE-message:: | ||
9854 | * TEXT-message:: | ||
9855 | * FILE-message:: | ||
9856 | * DELETE-message:: | ||
9857 | @end menu | ||
9858 | |||
9859 | @node MERGE-message | ||
9860 | @subsubsection MERGE-message | ||
9861 | |||
9862 | MERGE-messages will generally be sent automatically to reduce the amount of | ||
9863 | parallel chained messages. This is necessary to close a member session for | ||
9864 | example. You can also send MERGE-messages manually if required to merge two | ||
9865 | chains of messages. | ||
9866 | |||
9867 | @node INVITE-message | ||
9868 | @subsubsection INVITE-message | ||
9869 | |||
9870 | INVITE-messages can be used to invite other members in a room to a different | ||
9871 | room, sharing one potential door and the required key to enter the room. This | ||
9872 | kind of message is typically sent as encrypted PRIVATE-message to selected | ||
9873 | members because it doesn't make much sense to invite all members from one room | ||
9874 | to another considering a rooms key doesn't specify its usage. | ||
9875 | |||
9876 | @node TEXT-message | ||
9877 | @subsubsection TEXT-message | ||
9878 | |||
9879 | TEXT-messages can be used to send simple text-based messages and should be | ||
9880 | considered as being in readable form without complex decoding. The text has to | ||
9881 | end with a NULL-terminator character and should be in UTF-8 encoding for most | ||
9882 | compatibility. | ||
9883 | |||
9884 | @node FILE-message | ||
9885 | @subsubsection FILE-message | ||
9886 | |||
9887 | FILE-messages can be used to share files inside of a room. They do not contain | ||
9888 | the actual file being shared but its original hash, filename, URI to download | ||
9889 | the file and a symmetric key to decrypt the downloaded file. | ||
9890 | |||
9891 | It is recommended to use the FS subsystem and the FILE-messages in combination. | ||
9892 | |||
9893 | @node DELETE-message | ||
9894 | @subsubsection DELETE-message | ||
9895 | |||
9896 | DELETE-messages can be used to delete messages selected with its hash. You can | ||
9897 | also select any custom delay relative to the time of sending the DELETE-message. | ||
9898 | Deletion will only be processed on each peer in a room if the sender is | ||
9899 | authorized. | ||
9900 | |||
9901 | The only information of a deleted message which being kept will be the chained | ||
9902 | hashes connecting the message graph for potential traversion. For example the | ||
9903 | check for completion of a member session requires this information. | ||
9904 | |||
9905 | @node Member sessions | ||
9906 | @subsection Member sessions | ||
9907 | |||
9908 | A member session is a triple of the room key, the member ID and the public key | ||
9909 | of the member's ego. Member sessions allow that a member can change their ID or | ||
9910 | their ego once at a time without loosing the ability to delete old messages or | ||
9911 | identifying the original sender of a message. On every change of ID or EGO a | ||
9912 | session will be marked as closed. So every session chain will only contain one | ||
9913 | open session with the current ID and public key. | ||
9914 | |||
9915 | If a session is marked as closed the MESSENGER service will check from the first | ||
9916 | message opening a session to its last one closing the session for completion. If | ||
9917 | a the service can confirm that there is no message still missing which was sent | ||
9918 | from the closed member session, it will be marked as completed. | ||
9919 | |||
9920 | A completed member session is not able to verify any incoming message to ensure | ||
9921 | forward secrecy preventing others from using old stolen egos. | ||
9922 | |||
diff --git a/doc/handbook/chapters/keyconcepts.texi b/doc/handbook/chapters/keyconcepts.texi index eb95dbf78..f429997bf 100644 --- a/doc/handbook/chapters/keyconcepts.texi +++ b/doc/handbook/chapters/keyconcepts.texi | |||
@@ -152,6 +152,7 @@ and @pxref{Deniability}. | |||
152 | 152 | ||
153 | @menu | 153 | @menu |
154 | * How file-sharing achieves Anonymity:: | 154 | * How file-sharing achieves Anonymity:: |
155 | * How messaging provides Anonymity:: | ||
155 | @end menu | 156 | @end menu |
156 | 157 | ||
157 | Providing anonymity for users is the central goal for the anonymous | 158 | Providing anonymity for users is the central goal for the anonymous |
@@ -231,6 +232,30 @@ GAP --- practical anonymous networking. In Proceedings of | |||
231 | Designing Privacy Enhancing Technologies, 2003. | 232 | Designing Privacy Enhancing Technologies, 2003. |
232 | (@uref{https://git.gnunet.org/bibliography.git/plain/docs/aff.pdf, https://git.gnunet.org/bibliography.git/plain/docs/aff.pdf}) | 233 | (@uref{https://git.gnunet.org/bibliography.git/plain/docs/aff.pdf, https://git.gnunet.org/bibliography.git/plain/docs/aff.pdf}) |
233 | 234 | ||
235 | @cindex How messaging provides Anonymity | ||
236 | @node How messaging provides Anonymity | ||
237 | @subsection How messaging provides Anonymity | ||
238 | |||
239 | While the file-sharing tries to achieve anonymity through hiding actions in | ||
240 | other traffic, the messaging service provides a weaker form of protection | ||
241 | against identification. | ||
242 | |||
243 | The messaging service allows the use of an anonymous ego for the signing and | ||
244 | verification process of messages instead of a unique ego. This anonymous ego is | ||
245 | a publically known key pair which is shared between all peers in GNUnet. | ||
246 | |||
247 | Using this ego only ensures that individual messages alone can't identify its | ||
248 | sender inside of a messenger room. It should be clarified that the route of | ||
249 | the traffic for each message can still be tracked to identify the senders peer | ||
250 | inside of a messenger room if the threat agent controls certain peers hosting | ||
251 | the room. | ||
252 | |||
253 | Also opening a room in the messenger service will potentially match your peer | ||
254 | identity with the internal member identity from the messenger service. So | ||
255 | despite using the anonymous ego you can reveal your peer identity. This means | ||
256 | to decrease the chance of being identified, it is recommended to enter rooms but | ||
257 | you should not open them for others. | ||
258 | |||
234 | @cindex Deniability | 259 | @cindex Deniability |
235 | @node Deniability | 260 | @node Deniability |
236 | @section Deniability | 261 | @section Deniability |
diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi index 5d5d2fe14..a25dd8bd3 100644 --- a/doc/handbook/chapters/user.texi +++ b/doc/handbook/chapters/user.texi | |||
@@ -28,6 +28,7 @@ always welcome. | |||
28 | * The GNU Name System:: | 28 | * The GNU Name System:: |
29 | * reclaimID Identity Provider:: | 29 | * reclaimID Identity Provider:: |
30 | * Using the Virtual Public Network:: | 30 | * Using the Virtual Public Network:: |
31 | * Using the GNUnet Messenger:: | ||
31 | @end menu | 32 | @end menu |
32 | 33 | ||
33 | @node Start and stop GNUnet | 34 | @node Start and stop GNUnet |
@@ -2323,3 +2324,149 @@ service offered by that peer, you can create an IP tunnel to | |||
2323 | that peer by specifying the peer's identity, service name and | 2324 | that peer by specifying the peer's identity, service name and |
2324 | protocol (--tcp or --udp) and you will again receive an IP address | 2325 | protocol (--tcp or --udp) and you will again receive an IP address |
2325 | that will terminate at the respective peer's service. | 2326 | that will terminate at the respective peer's service. |
2327 | |||
2328 | @node Using the GNUnet Messenger | ||
2329 | @section Using the GNUnet Messenger | ||
2330 | |||
2331 | The GNUnet Messenger subsystem allows decentralized message-based | ||
2332 | communication inside of so called rooms. Each room can be hosted by | ||
2333 | a variable amount of peers. Every member of a room has the possibility | ||
2334 | to host the room on its own peer. A peer allows any amount of members | ||
2335 | to join a room. The amount of members in a room is not restricted. | ||
2336 | |||
2337 | Messages in a room will be distributed between all peers hosting the | ||
2338 | room or being internally (in context of the messenger service) connected | ||
2339 | to a hosting peer. All received or sent messages will be stored on any | ||
2340 | peer locally which is hosting the respective room or is internally | ||
2341 | connected to such a hosting peer. | ||
2342 | |||
2343 | The Messenger service is built on the CADET subsystem to make internal | ||
2344 | connections between peers using a reliable and encrypted transmission. | ||
2345 | Additionally the service uses a discrete padding to few different sizes. | ||
2346 | So kinds of messages and potential content can't be identified by the | ||
2347 | size of traffic from any attacker being unable to break the encryption | ||
2348 | of the transmission layer. | ||
2349 | |||
2350 | Another feature is additional end-to-end encryption for selected messages | ||
2351 | which uses the public key of another member (the receiver) to encrypt | ||
2352 | the message. Therefore it is ensured that only the selected member can | ||
2353 | read its content. This will also use additional padding. | ||
2354 | |||
2355 | @menu | ||
2356 | * Current state:: | ||
2357 | * Entering a room:: | ||
2358 | * Opening a room:: | ||
2359 | * Messaging in a room:: | ||
2360 | * Private messaging:: | ||
2361 | @end menu | ||
2362 | |||
2363 | @node Current state | ||
2364 | @subsection Current state | ||
2365 | |||
2366 | Currently there is only a simplistic CLI application available to use the | ||
2367 | messenger service. You can use this application with the | ||
2368 | @command{gnunet-messenger} command. | ||
2369 | |||
2370 | This application was designed for testing purposes and it does not provide | ||
2371 | full functionality in the current state. It is planned to replace this CLI | ||
2372 | application in later stages with a fully featured one using a client-side | ||
2373 | library designed for messenger applications. | ||
2374 | |||
2375 | @node Entering a room | ||
2376 | @subsection Entering a room | ||
2377 | |||
2378 | You can enter any room by its ROOMKEY and any PEERIDENTITY of a hosting peer. | ||
2379 | Optionally you can provide any IDENTITY which can represent a local ego by | ||
2380 | its name. | ||
2381 | |||
2382 | @example | ||
2383 | $ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY | ||
2384 | @end example | ||
2385 | |||
2386 | A PEERIDENTITY gets entered in encoded form. You can get your own peer ID by | ||
2387 | using the @command{gnunet-peerinfo} command: | ||
2388 | |||
2389 | @example | ||
2390 | $ gnunet-peerinfo -s | ||
2391 | @end example | ||
2392 | |||
2393 | A ROOMKEY gets entered in readable text form. The service will then hash the | ||
2394 | entered ROOMKEY and use the result as shared secret for transmission through | ||
2395 | the CADET submodule. You can also optionally leave out the '-r' paramter and | ||
2396 | the ROOMKEY to use the zeroed hash instead. | ||
2397 | |||
2398 | If no IDENTITY is provided you will not send any name to others, you will be | ||
2399 | referred as "anonymous" instead and use the anonymous ego. If you provide any | ||
2400 | IDENTITY a matching ego will be used to sign your messages. If there is no | ||
2401 | matching ego you will use the anonymous ego instead. The provided IDENTITY will | ||
2402 | be distributed as your name for the service in any case. | ||
2403 | |||
2404 | @node Opening a room | ||
2405 | @subsection Opening a room | ||
2406 | |||
2407 | You can open any room in a similar way to entering it. You just have to leave | ||
2408 | out the '-d' parameter and the PEERIDENTITY of the hosting peer. | ||
2409 | |||
2410 | @example | ||
2411 | $ gnunet-messenger [-e IDENTITY] -r ROOMKEY | ||
2412 | @end example | ||
2413 | |||
2414 | Providing ROOMKEY and IDENTITY is identical to entering a room. Opening a room | ||
2415 | will also make your peer to a host of this room. So others can enter the room | ||
2416 | through your peer if they have the required ROOMKEY and your peer ID. | ||
2417 | |||
2418 | If you want to use the zeroed hash as shared secret key for the room you can | ||
2419 | also leave it out as well: | ||
2420 | |||
2421 | @example | ||
2422 | $ gnunet-messenger | ||
2423 | @end example | ||
2424 | |||
2425 | @node Messaging in a room | ||
2426 | @subsection Messaging in a room | ||
2427 | |||
2428 | Once joined a room by entering it or opening it you can write text-based | ||
2429 | messages which will be distributed between all internally conntected peers. All | ||
2430 | sent messages will be displayed in the same way as received messages. | ||
2431 | |||
2432 | This relates to the internal handling of sent and received messages being mostly | ||
2433 | identical on application layer. Every handled message will be represented | ||
2434 | visually depending on its kind, content and sender. A sender can usually be | ||
2435 | identified by the encoded member ID or their name. | ||
2436 | |||
2437 | @example | ||
2438 | [17X37K] * 'anonymous' says: "hey" | ||
2439 | @end example | ||
2440 | |||
2441 | @node Private messaging | ||
2442 | @subsection Private messaging | ||
2443 | |||
2444 | As referred in the introduction the service allows sending private messages with | ||
2445 | additional end-to-end encryption. These messages will be visually represented | ||
2446 | by messages of the kind 'PRIVATE' in case they can't be decrypted with your used | ||
2447 | ego. Members who can't decrypt the message can potentially only identify its | ||
2448 | sender but they can't identify its receiver. | ||
2449 | |||
2450 | @example | ||
2451 | [17X37K] ~ message: PRIVATE | ||
2452 | @end example | ||
2453 | |||
2454 | If they can be decrypted they will appear as their secret message instead | ||
2455 | but marked visually. | ||
2456 | |||
2457 | @example | ||
2458 | [17X37K] ** 'anonymous' says: "hey" | ||
2459 | @end example | ||
2460 | |||
2461 | Currently you can only activate sending such encrypted text messages instead of | ||
2462 | usual text messages by adding the '-p' parameter: | ||
2463 | |||
2464 | @example | ||
2465 | $ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY -p | ||
2466 | @end example | ||
2467 | |||
2468 | Notice that you can only send such encrypted messages to members who use an ego | ||
2469 | which is not publically known as the anonymous ego to ensure transparency. If | ||
2470 | any user could decrypt these messages they would not be private. So as receiver | ||
2471 | of such messages the IDENTITY is required and it has to match a local ego. | ||
2472 | |||