messenger.rst (10257B)
1 .. index:: 2 double: subsystem; MESSENGER 3 4 .. _MESSENGER-Subsystem-Dev: 5 6 MESSENGER 7 ========= 8 9 The MESSENGER API (defined in ``gnunet_messenger_service.h``) allows P2P 10 applications built using GNUnet to communicate with specified kinds of 11 messages in a group. It provides applications the ability to send and 12 receive encrypted messages to any group of peers participating in GNUnet 13 in a decentralized way ( without even knowing all peers's identities). 14 15 MESSENGER delivers messages to other peers in \"rooms\". A room uses a 16 variable amount of CADET \"channels\" which will all be used for message 17 distribution. Each channel can represent an outgoing connection opened 18 by entering a room with ``GNUNET_MESSENGER_enter_room`` or an incoming 19 connection if the room was opened before via 20 ``GNUNET_MESSENGER_open_room``. 21 22 |messenger_room| 23 24 To enter a room you have to specify the \"door\" (peer's identity of a 25 peer which has opened the room) and the key of the room (which is 26 identical to a CADET \"port\"). To open a room you have to specify only 27 the key to use. When opening a room you automatically distribute a 28 PEER-message sharing your peer's identity in the room. 29 30 Entering or opening a room can also be combined in any order. In any 31 case you will automatically get a unique member ID and send a 32 JOIN-message notifying others about your entry and your public key 33 derived from your selected private key. 34 35 The private key can be selected in combination with a name using 36 ``GNUNET_MESSENGER_connect`` besides setting a (message-)callback which 37 gets called every time a message gets sent or received in the room. Once 38 the handle is initialized you can check your used key pair with 39 ``GNUNET_MESSENGER_get_key`` providing only its public key. The function 40 returns NULL if the anonymous key pair is used. If the key pair should 41 be replaced with a different one, you can use 42 ``GNUNET_MESSENGER_set_key`` to ensure proper chaining of used private 43 keys. 44 45 This will automatically cause the handle to send a KEY-message which 46 introduces the change of key pair to all other members in the rooms you 47 have entered or opened. Your sessions will therefore stay valid while 48 your old key pair gets replaced, signing the exchange. 49 50 Also once the handle is initialized you can check your current name 51 with ``GNUNET_MESSENGER_get_name`` and potentially change or set a name 52 via ``GNUNET_MESSENGER_set_name``. Any change in name will automatically 53 be distributed in all entered or opened rooms with a NAME-message. 54 55 In case you have adjusted your name separately in a specific room of 56 choice by sending a NAME-message manually, that room will not be 57 affected by the change of your handle's name. 58 59 To send a message a message inside of a room you can use 60 ``GNUNET_MESSENGER_send_message``. If you specify a selected contact as 61 receiver, the message gets encrypted automatically and will be sent as 62 PRIVATE- message instead. 63 64 To request a potentially missed message or to get a specific message 65 after its original call of the message-callback, you can use 66 ``GNUNET_MESSENGER_get_message``. Additionally once a message was 67 distributed to application level and the message-callback got called, 68 you can get the contact respresenting a message's sender respectively 69 with ``GNUNET_MESSENGER_get_sender``. This allows getting name and the 70 public key of any sender currently in use with 71 ``GNUNET_MESSENGER_contact_get_name`` and 72 ``GNUNET_MESSENGER_contact_get_key``. It is also possible to iterate 73 through all current members of a room with 74 ``GNUNET_MESSENGER_iterate_members`` using a callback. 75 76 To leave a room you can use ``GNUNET_MESSENGER_close_room`` which will 77 also close the rooms connections once all applications on the same peer 78 have left the room. Leaving a room will also send a LEAVE-message 79 closing a member session on all connected peers before any connection 80 will be closed. Leaving a room is however not required for any 81 application to keep your member session open between multiple sessions 82 of the actual application. 83 84 Finally, when an application no longer wants to use CADET, it should 85 call ``GNUNET_MESSENGER_disconnect``. You don't have to explicitly close 86 the used rooms or leave them. 87 88 Messages 89 ^^^^^^^^ 90 91 Here is a little summary to the kinds of messages you can send manually: 92 93 .. _NAME_002dmessage: 94 95 NAME-message 96 ------------ 97 98 NAME-messages can be used to change the name (or nick) of your identity 99 inside a room. The selected name can differ from the identifier used to 100 select your private key for signing and decrypting messages. 101 102 .. _INVITE_002dmessage: 103 104 INVITE-message 105 -------------- 106 107 INVITE-messages can be used to invite other members in a room to a 108 different room, sharing one potential door and the required key to enter 109 the room. This kind of message is typically sent as encrypted 110 PRIVATE-message to selected members because it doesn't make much sense 111 to invite all members from one room to another considering a rooms key 112 doesn't specify its usage. 113 114 .. _TEXT_002dmessage: 115 116 TEXT-message 117 ------------ 118 119 TEXT-messages can be used to send simple text-based messages and should 120 be considered as being in readable form without complex decoding. The 121 text has to end with a NULL-terminator character and should be in UTF-8 122 encoding for most compatibility. 123 124 .. _FILE_002dmessage: 125 126 FILE-message 127 ------------ 128 129 FILE-messages can be used to share files inside of a room. They do not 130 contain the actual file being shared but its original hash, filename, 131 URI to download the file and a symmetric key to decrypt the downloaded 132 file. 133 134 It is recommended to use the FS subsystem and the FILE-messages in 135 combination. 136 137 .. _DELETE_002dmessage: 138 139 DELETE-message 140 -------------- 141 142 DELETE-messages can be send via the separate function 143 ``GNUNET_MESSENGER_delete_message`` which will handle linked deletions 144 of messages automatically. Messages can be linked in cases the content 145 of one message requires another message to co-exist. 146 147 DELETE-messages can be used to delete messages selected with its hash. 148 You can also select any custom delay relative to the time of sending the 149 DELETE-message. Deletion will only be processed on each peer in a room 150 if the sender is authorized. 151 152 The only information of a deleted message which being kept will be the 153 chained hashes connecting the message graph for potential traversion. 154 For example the check for completion of a member session requires this 155 information. 156 157 .. _TICKET_002dmessage: 158 159 TICKET-message 160 -------------- 161 162 TICKET-messages can be send privately to other members in the room. The 163 member will be able to consume the received ticket via 164 ``GNUNET_RECLAIM_ticket_consume`` to gain access to selected attributes 165 and their stored values. 166 167 TICKET-messages require the usage of the RECLAIM service of GNUnet to 168 issue, revoke and consume tickets. Revoking tickets is independant of 169 deletions inside the MESSENGER API. 170 171 .. _TAG_002dmessage: 172 173 TAG-message 174 ----------- 175 176 TAG-messages can be used to tag or reject other messages in a 177 communicative way. Depending on the level of publication the message 178 fulfills different terms of functionality. For example if sent in a 179 private way using your own public key as audience, it might be used to 180 tag messages in a sharable way between different devices. 181 182 Public tagging or private tagging shared with only one contact might 183 reflect the communication of an own assignment or decision. For example 184 it can be used to reject an invitation from another contact. 185 186 Rejection can be expressed via a TAG-message that does not contain a 187 tag or in other words the tag is an empty string. This is a special case 188 for applications because it might translate into the rejection of 189 contacts or blocking of them. 190 191 Tagging or blocking of contacts depends on the message which is the 192 target of a TAG-message. If the tagged message is the latest 193 JOIN-message of another contact, the tag will be interpreted as tagging 194 of the regarding contact. The same way a rejection of such a 195 JOIN-message will be interpreted as block of the contact. 196 197 Unblocking or untagging can be done via deletion of the selected 198 TAG-message. 199 200 .. _SUBSCRIBE_002dmessage: 201 202 SUBSCRIBE-message 203 ----------------- 204 205 SUBSCRIBE-messages can be used to subscribe to a selected discourse in 206 a room. With the ``GNUNET_MESSENGER_FLAG_SUBSCRIPTION_KEEP_ALIVE`` flag 207 this subscription will be extended automatically by the client API of 208 the MESSENGER service. 209 210 A subscription can be ended manually via SUBSCRIBE-message with the flag 211 ``GNUNET_MESSENGER_FLAG_SUBSCRIPTION_UNSUBSCRIBE`` or it will end 212 automatically when closing the room or disconnecting the client, letting 213 the subscription run out. 214 215 Such an active subscription is necessary to receive TALK-messages from 216 a discourse. SUBSCRIBE-messages will not be stored locally. 217 218 .. _TALK_002dmessage: 219 220 TALK-message 221 ------------ 222 223 TALK-messages can be send while subscribed to a selected discourse. The 224 messages can contain any sort of binary data. Applications need to work 225 out format compatibility on their own. It is possible to link formats 226 to the discourse id used to identify a given discourse inside a room. 227 228 Only members that have an active subscription to the given discourse 229 will receive the TALK-messages. These messages will not be stored 230 locally. 231 232 .. _Member-sessions: 233 234 Member sessions 235 ^^^^^^^^^^^^^^^ 236 237 A member session is a triple of the room key, the member ID and the 238 public key of the member's key pair. Member sessions allow that a member 239 can change their ID or their private key once at a time without losing 240 the ability to delete old messages or identifying the original sender 241 of a message. On every change of ID or private key a session will be 242 marked as closed. So every session chain will only contain one open 243 session with the current ID and public key. 244 245 If a session is marked as closed the MESSENGER service will check from 246 the first message opening a session to its last one closing the session 247 for completion. If a the service can confirm that there is no message 248 still missing which was sent from the closed member session, it will be 249 marked as completed. 250 251 A completed member session is not able to verify any incoming message to 252 ensure forward secrecy preventing others from using old stolen private 253 keys. 254 255 .. |messenger_room| image:: /images/messenger_room.png