messenger.rst (10183B)
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 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 and URI to download the file. 132 133 It is recommended to use the FS subsystem and the FILE-messages in 134 combination. 135 136 .. _DELETE_002dmessage: 137 138 DELETE-message 139 -------------- 140 141 DELETE-messages can be send via the separate function 142 ``GNUNET_MESSENGER_delete_message`` which will handle linked deletions 143 of messages automatically. Messages can be linked in cases the content 144 of one message requires another message to co-exist. 145 146 DELETE-messages can be used to delete messages selected with its hash. 147 You can also select any custom delay relative to the time of sending the 148 DELETE-message. Deletion will only be processed on each peer in a room 149 if the sender is authorized. 150 151 The only information of a deleted message which being kept will be the 152 chained hashes connecting the message graph for potential traversion. 153 For example the check for completion of a member session requires this 154 information. 155 156 .. _TICKET_002dmessage: 157 158 TICKET-message 159 -------------- 160 161 TICKET-messages can be send privately to other members in the room. The 162 member will be able to consume the received ticket via 163 ``GNUNET_RECLAIM_ticket_consume`` to gain access to selected attributes 164 and their stored values. 165 166 TICKET-messages require the usage of the RECLAIM service of GNUnet to 167 issue, revoke and consume tickets. Revoking tickets is independant of 168 deletions inside the MESSENGER API. 169 170 .. _TAG_002dmessage: 171 172 TAG-message 173 ----------- 174 175 TAG-messages can be used to tag or reject other messages in a 176 communicative way. Depending on the level of publication the message 177 fulfills different terms of functionality. For example if sent in a 178 private way using your own public key as audience, it might be used to 179 tag messages in a sharable way between different devices. 180 181 Public tagging or private tagging shared with only one contact might 182 reflect the communication of an own assignment or decision. For example 183 it can be used to reject an invitation from another contact. 184 185 Rejection can be expressed via a TAG-message that does not contain a 186 tag or in other words the tag is an empty string. This is a special case 187 for applications because it might translate into the rejection of 188 contacts or blocking of them. 189 190 Tagging or blocking of contacts depends on the message which is the 191 target of a TAG-message. If the tagged message is the latest 192 JOIN-message of another contact, the tag will be interpreted as tagging 193 of the regarding contact. The same way a rejection of such a 194 JOIN-message will be interpreted as block of the contact. 195 196 Unblocking or untagging can be done via deletion of the selected 197 TAG-message. 198 199 .. _SUBSCRIBE_002dmessage: 200 201 SUBSCRIBE-message 202 ----------------- 203 204 SUBSCRIBE-messages can be used to subscribe to a selected discourse in 205 a room. With the ``GNUNET_MESSENGER_FLAG_SUBSCRIPTION_KEEP_ALIVE`` flag 206 this subscription will be extended automatically by the client API of 207 the MESSENGER service. 208 209 A subscription can be ended manually via SUBSCRIBE-message with the flag 210 ``GNUNET_MESSENGER_FLAG_SUBSCRIPTION_UNSUBSCRIBE`` or it will end 211 automatically when closing the room or disconnecting the client, letting 212 the subscription run out. 213 214 Such an active subscription is necessary to receive TALK-messages from 215 a discourse. SUBSCRIBE-messages will not be stored locally. 216 217 .. _TALK_002dmessage: 218 219 TALK-message 220 ------------ 221 222 TALK-messages can be send while subscribed to a selected discourse. The 223 messages can contain any sort of binary data. Applications need to work 224 out format compatibility on their own. It is possible to link formats 225 to the discourse id used to identify a given discourse inside a room. 226 227 Only members that have an active subscription to the given discourse 228 will receive the TALK-messages. These messages will not be stored 229 locally. 230 231 .. _Member-sessions: 232 233 Member sessions 234 ^^^^^^^^^^^^^^^ 235 236 A member session is a triple of the room key, the member ID and the 237 public key of the member's key pair. Member sessions allow that a member 238 can change their ID or their private key once at a time without losing 239 the ability to delete old messages or identifying the original sender 240 of a message. On every change of ID or private key a session will be 241 marked as closed. So every session chain will only contain one open 242 session with the current ID and public key. 243 244 If a session is marked as closed the MESSENGER service will check from 245 the first message opening a session to its last one closing the session 246 for completion. If a the service can confirm that there is no message 247 still missing which was sent from the closed member session, it will be 248 marked as completed. 249 250 A completed member session is not able to verify any incoming message to 251 ensure forward secrecy preventing others from using old stolen private 252 keys. 253 254 .. |messenger_room| image:: /images/messenger_room.png