aboutsummaryrefslogtreecommitdiff
path: root/doc/handbook/chapters/user.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/handbook/chapters/user.texi')
-rw-r--r--doc/handbook/chapters/user.texi147
1 files changed, 147 insertions, 0 deletions
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