gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

messenger.rst (5785B)


      1 .. _Using-the-GNUnet-Messenger:
      2 
      3 Messenger
      4 ---------
      5 
      6 .. note::
      7 
      8    The messenger is under development; expect bugs and incompatible changes.
      9    See :doc:`/status`.
     10 
     11 The GNUnet Messenger subsystem allows decentralized message-based
     12 communication inside of so called rooms. Each room can be hosted by a
     13 variable amount of peers. Every member of a room has the possibility to
     14 host the room on its own peer. A peer allows any amount of members to
     15 join a room. The amount of members in a room is not restricted.
     16 
     17 Messages in a room will be distributed between all peers hosting the
     18 room or being internally (in context of the messenger service) connected
     19 to a hosting peer. All received or sent messages will be stored on any
     20 peer locally which is hosting the respective room or is internally
     21 connected to such a hosting peer.
     22 
     23 The Messenger service is built on the CADET subsystem to make internal
     24 connections between peers using a reliable and encrypted transmission.
     25 Additionally the service uses a discrete padding to few different sizes.
     26 So kinds of messages and potential content can't be identified by the
     27 size of traffic from any attacker being unable to break the encryption
     28 of the transmission layer.
     29 
     30 Another feature is additional end-to-end encryption for selected
     31 messages which uses the public key of another member (the receiver) to
     32 encrypt the message. Therefore it is ensured that only the selected
     33 member can read its content. This will also use additional padding.
     34 
     35 .. _Current-state:
     36 
     37 Current state
     38 ~~~~~~~~~~~~~
     39 
     40 For everyday use, there are two separate applications built on the
     41 client-side library ``libgnunetchat``: the graphical `messenger-gtk
     42 <https://git.gnunet.org/messenger-gtk.git/>`__ and the terminal-based
     43 `messenger-cli <https://git.gnunet.org/messenger-cli.git/>`__.  The two
     44 are compatible with each other.
     45 
     46 GNUnet itself only includes a simplistic CLI application, which you can
     47 use with the ``gnunet-messenger`` command.  It was designed for testing
     48 purposes and does not provide full functionality.  The rest of this chapter
     49 describes it.
     50 
     51 .. _Entering-a-room:
     52 
     53 Entering a room
     54 ~~~~~~~~~~~~~~~
     55 
     56 You can enter any room by its ROOMKEY and any PEERIDENTITY of a hosting
     57 peer. Optionally you can provide any IDENTITY which can represent a
     58 local ego by its name. This will automatically select that ego's private
     59 key to sign your messages with.
     60 
     61 ::
     62 
     63    $ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY
     64 
     65 A PEERIDENTITY gets entered in encoded form. You can get your own peer
     66 ID by using the ``gnunet-core`` command:
     67 
     68 ::
     69 
     70    $ gnunet-core -i
     71 
     72 A ROOMKEY gets entered in readable text form. The service will then hash
     73 the entered ROOMKEY and use the result as shared secret for transmission
     74 through the CADET submodule. You can also optionally leave out the '-r'
     75 parameter and the ROOMKEY to use the zeroed hash instead.
     76 
     77 If no IDENTITY is provided you will not send any name to others, you
     78 will be referred as \"anonymous\" instead and use the anonymous ego (a
     79 shared key pair known to all peers). If you provide any IDENTITY a
     80 matching ego will be used to sign your messages. If there is no matching
     81 ego you will use the anonymous ego instead. The provided IDENTITY will
     82 be distributed as your name for the service in any case.
     83 
     84 .. _Opening-a-room:
     85 
     86 Opening a room
     87 ~~~~~~~~~~~~~~
     88 
     89 You can open any room in a similar way to entering it. You just have to
     90 leave out the '-d' parameter and the PEERIDENTITY of the hosting peer.
     91 
     92 ::
     93 
     94    $ gnunet-messenger [-e IDENTITY] -r ROOMKEY
     95 
     96 Providing ROOMKEY and IDENTITY is identical to entering a room. Opening
     97 a room will also make your peer to a host of this room. So others can
     98 enter the room through your peer if they have the required ROOMKEY and
     99 your peer ID.
    100 
    101 If you want to use the zeroed hash as shared secret key for the room you
    102 can also leave it out as well:
    103 
    104 ::
    105 
    106    $ gnunet-messenger
    107 
    108 .. _Messaging-in-a-room:
    109 
    110 Messaging in a room
    111 ~~~~~~~~~~~~~~~~~~~
    112 
    113 Once joined a room by entering it or opening it you can write text-based
    114 messages which will be distributed between all internally conntected
    115 peers. All sent messages will be displayed in the same way as received
    116 messages.
    117 
    118 This relates to the internal handling of sent and received messages
    119 being mostly identical on application layer. Every handled message will
    120 be represented visually depending on its kind, content and sender. A
    121 sender can usually be identified by the encoded member ID or their name.
    122 
    123 .. code-block:: text
    124 
    125    [17X37K] * 'anonymous' says: "hey"
    126 
    127 .. _Private-messaging:
    128 
    129 Private messaging
    130 ~~~~~~~~~~~~~~~~~
    131 
    132 As referred in the introduction the service allows sending private
    133 messages with additional end-to-end encryption. These messages will be
    134 visually represented by messages of the kind 'PRIVATE' in case they
    135 can't be decrypted with your accessible stored keys. Members who can't
    136 decrypt the message can potentially only identify its sender but they
    137 can't identify its receiver. This prevents other members from collecting
    138 more metadata than necessary about you.
    139 
    140 .. code-block:: text
    141 
    142    [17X37K] ~ message: PRIVATE
    143 
    144 If they can be decrypted they will appear as their secret message
    145 instead but marked visually.
    146 
    147 .. code-block:: text
    148 
    149    [17X37K] ** 'anonymous' says: "hey"
    150 
    151 Currently you can only activate sending such encrypted text messages
    152 instead of usual text messages by adding the '-p' parameter:
    153 
    154 .. code-block:: shell
    155 
    156    $ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY -p
    157 
    158 Notice that you can only send such encrypted messages to members who use
    159 a private key which is not publicly known via the anonymous ego to ensure
    160 transparency. If any user could decrypt these messages they would not be
    161 private. So as receiver of such messages the IDENTITY is required and it
    162 has to match a local ego.