diff options
Diffstat (limited to 'doc/handbook/chapters/developer.texi')
-rw-r--r-- | doc/handbook/chapters/developer.texi | 215 |
1 files changed, 215 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 | |||
9705 | communicators which use them. | 9706 | communicators which use them. |
9706 | TRANSPORT may fail transmitting backchannel messages, and TRANSPORT will not | 9707 | TRANSPORT may fail transmitting backchannel messages, and TRANSPORT will not |
9707 | attempt to retransmit them. | 9708 | attempt to retransmit them. |
9709 | |||
9710 | @cindex MESSENGER Subsystem | ||
9711 | @cindex MESSENGER | ||
9712 | @cindex messenger | ||
9713 | @node MESSENGER Subsystem | ||
9714 | @section MESSENGER Subsystem | ||
9715 | |||
9716 | The MESSENGER subsystem is responsible for secure end-to-end communication in | ||
9717 | groups of nodes in the GNUnet overlay network. MESSENGER builds on the CADET | ||
9718 | subsystem which provides a reliable and secure end-to-end communication between | ||
9719 | the nodes inside of these groups. | ||
9720 | |||
9721 | Additionally to the CADET security benefits, MESSENGER provides following | ||
9722 | properties 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 | |||
9753 | Also 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 | |||
9782 | The MESSENGER API (defined in @file{gnunet_messenger_service.h}) allows P2P | ||
9783 | applications built using GNUnet to communicate with specified kinds of messages | ||
9784 | in a group. It provides applications the ability to send and receive encrypted | ||
9785 | messages to any group of peers participating in GNUnet in a decentralized way ( | ||
9786 | without even knowing all peers's identities). | ||
9787 | |||
9788 | MESSENGER delivers messages to other peers in "rooms". A room uses a variable | ||
9789 | amount of CADET "channels" which will all be used for message distribution. Each | ||
9790 | channel 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 | ||
9792 | opened before via @code{GNUNET_MESSENGER_open_room}. | ||
9793 | |||
9794 | @image{images/messenger_room.png} | ||
9795 | |||
9796 | To enter a room you have to specify the "door" (peer's identity of a peer which | ||
9797 | has 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 | ||
9799 | room you automatically distribute a PEER-message sharing your peer's identity in | ||
9800 | the room. | ||
9801 | |||
9802 | Entering or opening a room can also be combined in any order. In any case you | ||
9803 | will automatically get a unique member ID and send a JOIN-message notifying | ||
9804 | others about your entry and your public key from your selected ego. | ||
9805 | |||
9806 | The ego can be selected by name with the initial @code{GNUNET_MESSENGER_connect} | ||
9807 | besides setting a (identity-)callback for each change/confirmation of the used | ||
9808 | ego and a (message-)callback which gets called every time a message gets sent or | ||
9809 | received in the room. Once the identity-callback got called you can check your | ||
9810 | used ego with @code{GNUNET_MESSENGER_get_key} providing only its public key. The | ||
9811 | function returns NULL if the anonymous ego is used. If the ego should be | ||
9812 | replaced with a newly generated one, you can use @code{GNUNET_MESSENGER_update} | ||
9813 | to ensure proper chaining of used egos. | ||
9814 | |||
9815 | Also 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 | ||
9818 | ego with @code{GNUNET_MESSENGER_update}. Also any change in ego or name will | ||
9819 | automatically be distributed in the room with a NAME- or KEY-message | ||
9820 | respectively. | ||
9821 | |||
9822 | To 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 | ||
9824 | receiver, the message gets encrypted automatically and will be sent as PRIVATE- | ||
9825 | message instead. | ||
9826 | |||
9827 | To request a potentially missed message or to get a specific message after its | ||
9828 | original call of the message-callback, you can use | ||
9829 | @code{GNUNET_MESSENGER_get_message}. Additionally once a message was distributed | ||
9830 | to application level and the message-callback got called, you can get the | ||
9831 | contact respresenting a message's sender respectively with | ||
9832 | @code{GNUNET_MESSENGER_get_sender}. This allows getting name and the public key | ||
9833 | of any sender currently in use with @code{GNUNET_MESSENGER_contact_get_name} | ||
9834 | and @code{GNUNET_MESSENGER_contact_get_key}. It is also possible to iterate | ||
9835 | through all current members of a room with | ||
9836 | @code{GNUNET_MESSENGER_iterate_members} using a callback. | ||
9837 | |||
9838 | To leave a room you can use @code{GNUNET_MESSENGER_close_room} which will also | ||
9839 | close the rooms connections once all applications on the same peer have left | ||
9840 | the room. Leaving a room will also send a LEAVE-message closing a member session | ||
9841 | on all connected peers before any connection will be closed. Leaving a room is | ||
9842 | however not required for any application to keep your member session open | ||
9843 | between multiple sessions of the actual application. | ||
9844 | |||
9845 | Finally, 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 | ||
9847 | rooms or leave them. | ||
9848 | |||
9849 | Here 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 | |||
9862 | MERGE-messages will generally be sent automatically to reduce the amount of | ||
9863 | parallel chained messages. This is necessary to close a member session for | ||
9864 | example. You can also send MERGE-messages manually if required to merge two | ||
9865 | chains of messages. | ||
9866 | |||
9867 | @node INVITE-message | ||
9868 | @subsubsection INVITE-message | ||
9869 | |||
9870 | INVITE-messages can be used to invite other members in a room to a different | ||
9871 | room, sharing one potential door and the required key to enter the room. This | ||
9872 | kind of message is typically sent as encrypted PRIVATE-message to selected | ||
9873 | members because it doesn't make much sense to invite all members from one room | ||
9874 | to another considering a rooms key doesn't specify its usage. | ||
9875 | |||
9876 | @node TEXT-message | ||
9877 | @subsubsection TEXT-message | ||
9878 | |||
9879 | TEXT-messages can be used to send simple text-based messages and should be | ||
9880 | considered as being in readable form without complex decoding. The text has to | ||
9881 | end with a NULL-terminator character and should be in UTF-8 encoding for most | ||
9882 | compatibility. | ||
9883 | |||
9884 | @node FILE-message | ||
9885 | @subsubsection FILE-message | ||
9886 | |||
9887 | FILE-messages can be used to share files inside of a room. They do not contain | ||
9888 | the actual file being shared but its original hash, filename, URI to download | ||
9889 | the file and a symmetric key to decrypt the downloaded file. | ||
9890 | |||
9891 | It is recommended to use the FS subsystem and the FILE-messages in combination. | ||
9892 | |||
9893 | @node DELETE-message | ||
9894 | @subsubsection DELETE-message | ||
9895 | |||
9896 | DELETE-messages can be used to delete messages selected with its hash. You can | ||
9897 | also select any custom delay relative to the time of sending the DELETE-message. | ||
9898 | Deletion will only be processed on each peer in a room if the sender is | ||
9899 | authorized. | ||
9900 | |||
9901 | The only information of a deleted message which being kept will be the chained | ||
9902 | hashes connecting the message graph for potential traversion. For example the | ||
9903 | check for completion of a member session requires this information. | ||
9904 | |||
9905 | @node Member sessions | ||
9906 | @subsection Member sessions | ||
9907 | |||
9908 | A member session is a triple of the room key, the member ID and the public key | ||
9909 | of the member's ego. Member sessions allow that a member can change their ID or | ||
9910 | their ego once at a time without loosing the ability to delete old messages or | ||
9911 | identifying the original sender of a message. On every change of ID or EGO a | ||
9912 | session will be marked as closed. So every session chain will only contain one | ||
9913 | open session with the current ID and public key. | ||
9914 | |||
9915 | If a session is marked as closed the MESSENGER service will check from the first | ||
9916 | message opening a session to its last one closing the session for completion. If | ||
9917 | a the service can confirm that there is no message still missing which was sent | ||
9918 | from the closed member session, it will be marked as completed. | ||
9919 | |||
9920 | A completed member session is not able to verify any incoming message to ensure | ||
9921 | forward secrecy preventing others from using old stolen egos. | ||
9922 | |||