aboutsummaryrefslogtreecommitdiff
path: root/doc/handbook/chapters
diff options
context:
space:
mode:
Diffstat (limited to 'doc/handbook/chapters')
-rw-r--r--doc/handbook/chapters/developer.texi215
-rw-r--r--doc/handbook/chapters/keyconcepts.texi25
-rw-r--r--doc/handbook/chapters/user.texi147
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
9705communicators which use them. 9706communicators which use them.
9706TRANSPORT may fail transmitting backchannel messages, and TRANSPORT will not 9707TRANSPORT may fail transmitting backchannel messages, and TRANSPORT will not
9707attempt to retransmit them. 9708attempt to retransmit them.
9709
9710@cindex MESSENGER Subsystem
9711@cindex MESSENGER
9712@cindex messenger
9713@node MESSENGER Subsystem
9714@section MESSENGER Subsystem
9715
9716The MESSENGER subsystem is responsible for secure end-to-end communication in
9717groups of nodes in the GNUnet overlay network. MESSENGER builds on the CADET
9718subsystem which provides a reliable and secure end-to-end communication between
9719the nodes inside of these groups.
9720
9721Additionally to the CADET security benefits, MESSENGER provides following
9722properties 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
9753Also 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
9782The MESSENGER API (defined in @file{gnunet_messenger_service.h}) allows P2P
9783applications built using GNUnet to communicate with specified kinds of messages
9784in a group. It provides applications the ability to send and receive encrypted
9785messages to any group of peers participating in GNUnet in a decentralized way (
9786without even knowing all peers's identities).
9787
9788MESSENGER delivers messages to other peers in "rooms". A room uses a variable
9789amount of CADET "channels" which will all be used for message distribution. Each
9790channel 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
9792opened before via @code{GNUNET_MESSENGER_open_room}.
9793
9794@image{images/messenger_room.png}
9795
9796To enter a room you have to specify the "door" (peer's identity of a peer which
9797has 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
9799room you automatically distribute a PEER-message sharing your peer's identity in
9800the room.
9801
9802Entering or opening a room can also be combined in any order. In any case you
9803will automatically get a unique member ID and send a JOIN-message notifying
9804others about your entry and your public key from your selected ego.
9805
9806The ego can be selected by name with the initial @code{GNUNET_MESSENGER_connect}
9807besides setting a (identity-)callback for each change/confirmation of the used
9808ego and a (message-)callback which gets called every time a message gets sent or
9809received in the room. Once the identity-callback got called you can check your
9810used ego with @code{GNUNET_MESSENGER_get_key} providing only its public key. The
9811function returns NULL if the anonymous ego is used. If the ego should be
9812replaced with a newly generated one, you can use @code{GNUNET_MESSENGER_update}
9813to ensure proper chaining of used egos.
9814
9815Also 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
9818ego with @code{GNUNET_MESSENGER_update}. Also any change in ego or name will
9819automatically be distributed in the room with a NAME- or KEY-message
9820respectively.
9821
9822To 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
9824receiver, the message gets encrypted automatically and will be sent as PRIVATE-
9825message instead.
9826
9827To request a potentially missed message or to get a specific message after its
9828original call of the message-callback, you can use
9829@code{GNUNET_MESSENGER_get_message}. Additionally once a message was distributed
9830to application level and the message-callback got called, you can get the
9831contact respresenting a message's sender respectively with
9832@code{GNUNET_MESSENGER_get_sender}. This allows getting name and the public key
9833of any sender currently in use with @code{GNUNET_MESSENGER_contact_get_name}
9834and @code{GNUNET_MESSENGER_contact_get_key}. It is also possible to iterate
9835through all current members of a room with
9836@code{GNUNET_MESSENGER_iterate_members} using a callback.
9837
9838To leave a room you can use @code{GNUNET_MESSENGER_close_room} which will also
9839close the rooms connections once all applications on the same peer have left
9840the room. Leaving a room will also send a LEAVE-message closing a member session
9841on all connected peers before any connection will be closed. Leaving a room is
9842however not required for any application to keep your member session open
9843between multiple sessions of the actual application.
9844
9845Finally, 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
9847rooms or leave them.
9848
9849Here 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
9862MERGE-messages will generally be sent automatically to reduce the amount of
9863parallel chained messages. This is necessary to close a member session for
9864example. You can also send MERGE-messages manually if required to merge two
9865chains of messages.
9866
9867@node INVITE-message
9868@subsubsection INVITE-message
9869
9870INVITE-messages can be used to invite other members in a room to a different
9871room, sharing one potential door and the required key to enter the room. This
9872kind of message is typically sent as encrypted PRIVATE-message to selected
9873members because it doesn't make much sense to invite all members from one room
9874to another considering a rooms key doesn't specify its usage.
9875
9876@node TEXT-message
9877@subsubsection TEXT-message
9878
9879TEXT-messages can be used to send simple text-based messages and should be
9880considered as being in readable form without complex decoding. The text has to
9881end with a NULL-terminator character and should be in UTF-8 encoding for most
9882compatibility.
9883
9884@node FILE-message
9885@subsubsection FILE-message
9886
9887FILE-messages can be used to share files inside of a room. They do not contain
9888the actual file being shared but its original hash, filename, URI to download
9889the file and a symmetric key to decrypt the downloaded file.
9890
9891It is recommended to use the FS subsystem and the FILE-messages in combination.
9892
9893@node DELETE-message
9894@subsubsection DELETE-message
9895
9896DELETE-messages can be used to delete messages selected with its hash. You can
9897also select any custom delay relative to the time of sending the DELETE-message.
9898Deletion will only be processed on each peer in a room if the sender is
9899authorized.
9900
9901The only information of a deleted message which being kept will be the chained
9902hashes connecting the message graph for potential traversion. For example the
9903check for completion of a member session requires this information.
9904
9905@node Member sessions
9906@subsection Member sessions
9907
9908A member session is a triple of the room key, the member ID and the public key
9909of the member's ego. Member sessions allow that a member can change their ID or
9910their ego once at a time without loosing the ability to delete old messages or
9911identifying the original sender of a message. On every change of ID or EGO a
9912session will be marked as closed. So every session chain will only contain one
9913open session with the current ID and public key.
9914
9915If a session is marked as closed the MESSENGER service will check from the first
9916message opening a session to its last one closing the session for completion. If
9917a the service can confirm that there is no message still missing which was sent
9918from the closed member session, it will be marked as completed.
9919
9920A completed member session is not able to verify any incoming message to ensure
9921forward 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
157Providing anonymity for users is the central goal for the anonymous 158Providing anonymity for users is the central goal for the anonymous
@@ -231,6 +232,30 @@ GAP --- practical anonymous networking. In Proceedings of
231Designing Privacy Enhancing Technologies, 2003. 232Designing 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
239While the file-sharing tries to achieve anonymity through hiding actions in
240other traffic, the messaging service provides a weaker form of protection
241against identification.
242
243The messaging service allows the use of an anonymous ego for the signing and
244verification process of messages instead of a unique ego. This anonymous ego is
245a publically known key pair which is shared between all peers in GNUnet.
246
247Using this ego only ensures that individual messages alone can't identify its
248sender inside of a messenger room. It should be clarified that the route of
249the traffic for each message can still be tracked to identify the senders peer
250inside of a messenger room if the threat agent controls certain peers hosting
251the room.
252
253Also opening a room in the messenger service will potentially match your peer
254identity with the internal member identity from the messenger service. So
255despite using the anonymous ego you can reveal your peer identity. This means
256to decrease the chance of being identified, it is recommended to enter rooms but
257you 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
2323that peer by specifying the peer's identity, service name and 2324that peer by specifying the peer's identity, service name and
2324protocol (--tcp or --udp) and you will again receive an IP address 2325protocol (--tcp or --udp) and you will again receive an IP address
2325that will terminate at the respective peer's service. 2326that will terminate at the respective peer's service.
2327
2328@node Using the GNUnet Messenger
2329@section Using the GNUnet Messenger
2330
2331The GNUnet Messenger subsystem allows decentralized message-based
2332communication inside of so called rooms. Each room can be hosted by
2333a variable amount of peers. Every member of a room has the possibility
2334to host the room on its own peer. A peer allows any amount of members
2335to join a room. The amount of members in a room is not restricted.
2336
2337Messages in a room will be distributed between all peers hosting the
2338room or being internally (in context of the messenger service) connected
2339to a hosting peer. All received or sent messages will be stored on any
2340peer locally which is hosting the respective room or is internally
2341connected to such a hosting peer.
2342
2343The Messenger service is built on the CADET subsystem to make internal
2344connections between peers using a reliable and encrypted transmission.
2345Additionally the service uses a discrete padding to few different sizes.
2346So kinds of messages and potential content can't be identified by the
2347size of traffic from any attacker being unable to break the encryption
2348of the transmission layer.
2349
2350Another feature is additional end-to-end encryption for selected messages
2351which uses the public key of another member (the receiver) to encrypt
2352the message. Therefore it is ensured that only the selected member can
2353read 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
2366Currently there is only a simplistic CLI application available to use the
2367messenger service. You can use this application with the
2368@command{gnunet-messenger} command.
2369
2370This application was designed for testing purposes and it does not provide
2371full functionality in the current state. It is planned to replace this CLI
2372application in later stages with a fully featured one using a client-side
2373library designed for messenger applications.
2374
2375@node Entering a room
2376@subsection Entering a room
2377
2378You can enter any room by its ROOMKEY and any PEERIDENTITY of a hosting peer.
2379Optionally you can provide any IDENTITY which can represent a local ego by
2380its name.
2381
2382@example
2383$ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY
2384@end example
2385
2386A PEERIDENTITY gets entered in encoded form. You can get your own peer ID by
2387using the @command{gnunet-peerinfo} command:
2388
2389@example
2390$ gnunet-peerinfo -s
2391@end example
2392
2393A ROOMKEY gets entered in readable text form. The service will then hash the
2394entered ROOMKEY and use the result as shared secret for transmission through
2395the CADET submodule. You can also optionally leave out the '-r' paramter and
2396the ROOMKEY to use the zeroed hash instead.
2397
2398If no IDENTITY is provided you will not send any name to others, you will be
2399referred as "anonymous" instead and use the anonymous ego. If you provide any
2400IDENTITY a matching ego will be used to sign your messages. If there is no
2401matching ego you will use the anonymous ego instead. The provided IDENTITY will
2402be distributed as your name for the service in any case.
2403
2404@node Opening a room
2405@subsection Opening a room
2406
2407You can open any room in a similar way to entering it. You just have to leave
2408out the '-d' parameter and the PEERIDENTITY of the hosting peer.
2409
2410@example
2411$ gnunet-messenger [-e IDENTITY] -r ROOMKEY
2412@end example
2413
2414Providing ROOMKEY and IDENTITY is identical to entering a room. Opening a room
2415will also make your peer to a host of this room. So others can enter the room
2416through your peer if they have the required ROOMKEY and your peer ID.
2417
2418If you want to use the zeroed hash as shared secret key for the room you can
2419also 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
2428Once joined a room by entering it or opening it you can write text-based
2429messages which will be distributed between all internally conntected peers. All
2430sent messages will be displayed in the same way as received messages.
2431
2432This relates to the internal handling of sent and received messages being mostly
2433identical on application layer. Every handled message will be represented
2434visually depending on its kind, content and sender. A sender can usually be
2435identified 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
2444As referred in the introduction the service allows sending private messages with
2445additional end-to-end encryption. These messages will be visually represented
2446by messages of the kind 'PRIVATE' in case they can't be decrypted with your used
2447ego. Members who can't decrypt the message can potentially only identify its
2448sender but they can't identify its receiver.
2449
2450@example
2451[17X37K] ~ message: PRIVATE
2452@end example
2453
2454If they can be decrypted they will appear as their secret message instead
2455but marked visually.
2456
2457@example
2458[17X37K] ** 'anonymous' says: "hey"
2459@end example
2460
2461Currently you can only activate sending such encrypted text messages instead of
2462usual text messages by adding the '-p' parameter:
2463
2464@example
2465$ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY -p
2466@end example
2467
2468Notice that you can only send such encrypted messages to members who use an ego
2469which is not publically known as the anonymous ego to ensure transparency. If
2470any user could decrypt these messages they would not be private. So as receiver
2471of such messages the IDENTITY is required and it has to match a local ego.
2472