aboutsummaryrefslogtreecommitdiff
path: root/doc/handbook/chapters/developer.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/handbook/chapters/developer.texi')
-rw-r--r--doc/handbook/chapters/developer.texi179
1 files changed, 89 insertions, 90 deletions
diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi
index 1bf7a7b24..7546f7ac7 100644
--- a/doc/handbook/chapters/developer.texi
+++ b/doc/handbook/chapters/developer.texi
@@ -8885,7 +8885,7 @@ block is more recent during the store operation.
8885 8885
8886 8886
8887The REVOCATION subsystem is responsible for key revocation of Egos. 8887The REVOCATION subsystem is responsible for key revocation of Egos.
8888If a user learns that theis private key has been compromised or has lost 8888If a user learns that their private key has been compromised or has lost
8889it, they can use the REVOCATION system to inform all of the other users 8889it, they can use the REVOCATION system to inform all of the other users
8890that their private key is no longer valid. 8890that their private key is no longer valid.
8891The subsystem thus includes ways to query for the validity of keys and to 8891The subsystem thus includes ways to query for the validity of keys and to
@@ -9782,61 +9782,61 @@ attempt to retransmit them.
9782@node MESSENGER Subsystem 9782@node MESSENGER Subsystem
9783@section MESSENGER Subsystem 9783@section MESSENGER Subsystem
9784 9784
9785The MESSENGER subsystem is responsible for secure end-to-end communication in 9785The MESSENGER subsystem is responsible for secure end-to-end communication in
9786groups of nodes in the GNUnet overlay network. MESSENGER builds on the CADET 9786groups of nodes in the GNUnet overlay network. MESSENGER builds on the CADET
9787subsystem which provides a reliable and secure end-to-end communication between 9787subsystem which provides a reliable and secure end-to-end communication between
9788the nodes inside of these groups. 9788the nodes inside of these groups.
9789 9789
9790Additionally to the CADET security benefits, MESSENGER provides following 9790Additionally to the CADET security benefits, MESSENGER provides following
9791properties designed for application level usage: 9791properties designed for application level usage:
9792 9792
9793@itemize @bullet 9793@itemize @bullet
9794@item MESSENGER provides integrity by signing the messages with the users 9794@item MESSENGER provides integrity by signing the messages with the users
9795 provided ego 9795 provided ego
9796@item MESSENGER adds (optional) forward secrecy by replacing the key pair of the 9796@item MESSENGER adds (optional) forward secrecy by replacing the key pair of the
9797 used ego and signing the propagation of the new one with old one (chaining 9797 used ego and signing the propagation of the new one with old one (chaining
9798 egos) 9798 egos)
9799@item MESSENGER provides verification of a original sender by checking against 9799@item MESSENGER provides verification of a original sender by checking against
9800 all used egos from a member which are currently in active use (active use 9800 all used egos from a member which are currently in active use (active use
9801 depends on the state of a member session) 9801 depends on the state of a member session)
9802@item MESSENGER offsers (optional) decentralized message forwarding between all 9802@item MESSENGER offsers (optional) decentralized message forwarding between all
9803 nodes in a group to improve availability and prevent MITM-attacks 9803 nodes in a group to improve availability and prevent MITM-attacks
9804@item MESSENGER handles new connections and disconnections from nodes in the 9804@item MESSENGER handles new connections and disconnections from nodes in the
9805 group by reconnecting them preserving an efficient structure for message 9805 group by reconnecting them preserving an efficient structure for message
9806 distribution (ensuring availability and accountablity) 9806 distribution (ensuring availability and accountablity)
9807@item MESSENGER provides replay protection (messages can be uniquely identified 9807@item MESSENGER provides replay protection (messages can be uniquely identified
9808 via SHA-512, include a timestamp and the hash of the last message) 9808 via SHA-512, include a timestamp and the hash of the last message)
9809@item MESSENGER allows detection for dropped messages by chaining them (messages 9809@item MESSENGER allows detection for dropped messages by chaining them (messages
9810 refer to the last message by their hash) improving accountability 9810 refer to the last message by their hash) improving accountability
9811@item MESSENGER allows requesting messages from other peers explicitly to ensure 9811@item MESSENGER allows requesting messages from other peers explicitly to ensure
9812 availability 9812 availability
9813@item MESSENGER provides confidentiality by padding messages to few different 9813@item MESSENGER provides confidentiality by padding messages to few different
9814 sizes (512 bytes, 4096 bytes, 32768 bytes and maximal message size from 9814 sizes (512 bytes, 4096 bytes, 32768 bytes and maximal message size from
9815 CADET) 9815 CADET)
9816@item MESSENGER adds (optional) confidentiality with ECDHE to exchange and use 9816@item MESSENGER adds (optional) confidentiality with ECDHE to exchange and use
9817 symmetric encryption, encrypting with both AES-256 and Twofish but 9817 symmetric encryption, encrypting with both AES-256 and Twofish but
9818 allowing only selected members to decrypt (using the receivers ego for 9818 allowing only selected members to decrypt (using the receivers ego for
9819 ECDHE) 9819 ECDHE)
9820@end itemize 9820@end itemize
9821 9821
9822Also MESSENGER provides multiple features with privacy in mind: 9822Also MESSENGER provides multiple features with privacy in mind:
9823 9823
9824@itemize @bullet 9824@itemize @bullet
9825@item MESSENGER allows deleting messages from all peers in the group by the 9825@item MESSENGER allows deleting messages from all peers in the group by the
9826 original sender (uses the MESSENGER provided verification) 9826 original sender (uses the MESSENGER provided verification)
9827@item MESSENGER allows using the publicly known anonymous ego instead of any 9827@item MESSENGER allows using the publicly known anonymous ego instead of any
9828 unique identifying ego 9828 unique identifying ego
9829@item MESSENGER allows your node to decide between acting as host of the used 9829@item MESSENGER allows your node to decide between acting as host of the used
9830 messaging room (sharing your peer's identity with all nodes in the group) 9830 messaging room (sharing your peer's identity with all nodes in the group)
9831 or acting as guest (sharing your peer's identity only with the nodes you 9831 or acting as guest (sharing your peer's identity only with the nodes you
9832 explicitly open a connection to) 9832 explicitly open a connection to)
9833@item MESSENGER handles members independently of the peer's identity making 9833@item MESSENGER handles members independently of the peer's identity making
9834 forwarded messages indistinguishable from directly received ones ( 9834 forwarded messages indistinguishable from directly received ones (
9835 complicating the tracking of messages and identifying its origin) 9835 complicating the tracking of messages and identifying its origin)
9836@item MESSENGER allows names of members being not unique (also names are 9836@item MESSENGER allows names of members being not unique (also names are
9837 optional) 9837 optional)
9838@item MESSENGER does not include information about the selected receiver of an 9838@item MESSENGER does not include information about the selected receiver of an
9839 explicitly encrypted message in its header, complicating it for other 9839 explicitly encrypted message in its header, complicating it for other
9840 members to draw conclusions from communication partners 9840 members to draw conclusions from communication partners
9841@end itemize 9841@end itemize
9842 9842
@@ -9848,71 +9848,71 @@ Also MESSENGER provides multiple features with privacy in mind:
9848@node libgnunetmessenger 9848@node libgnunetmessenger
9849@subsection libgnunetmessenger 9849@subsection libgnunetmessenger
9850 9850
9851The MESSENGER API (defined in @file{gnunet_messenger_service.h}) allows P2P 9851The MESSENGER API (defined in @file{gnunet_messenger_service.h}) allows P2P
9852applications built using GNUnet to communicate with specified kinds of messages 9852applications built using GNUnet to communicate with specified kinds of messages
9853in a group. It provides applications the ability to send and receive encrypted 9853in a group. It provides applications the ability to send and receive encrypted
9854messages to any group of peers participating in GNUnet in a decentralized way ( 9854messages to any group of peers participating in GNUnet in a decentralized way (
9855without even knowing all peers's identities). 9855without even knowing all peers's identities).
9856 9856
9857MESSENGER delivers messages to other peers in "rooms". A room uses a variable 9857MESSENGER delivers messages to other peers in "rooms". A room uses a variable
9858amount of CADET "channels" which will all be used for message distribution. Each 9858amount of CADET "channels" which will all be used for message distribution. Each
9859channel can represent an outgoing connection opened by entering a room with 9859channel can represent an outgoing connection opened by entering a room with
9860@code{GNUNET_MESSENGER_enter_room} or an incoming connection if the room was 9860@code{GNUNET_MESSENGER_enter_room} or an incoming connection if the room was
9861opened before via @code{GNUNET_MESSENGER_open_room}. 9861opened before via @code{GNUNET_MESSENGER_open_room}.
9862 9862
9863@image{images/messenger_room,6in,,Room structure} 9863@image{images/messenger_room,6in,,Room structure}
9864 9864
9865To enter a room you have to specify the "door" (peer's identity of a peer which 9865To enter a room you have to specify the "door" (peer's identity of a peer which
9866has opened the room) and the key of the room (which is identical to a CADET 9866has opened the room) and the key of the room (which is identical to a CADET
9867"port"). To open a room you have to specify only the key to use. When opening a 9867"port"). To open a room you have to specify only the key to use. When opening a
9868room you automatically distribute a PEER-message sharing your peer's identity in 9868room you automatically distribute a PEER-message sharing your peer's identity in
9869the room. 9869the room.
9870 9870
9871Entering or opening a room can also be combined in any order. In any case you 9871Entering or opening a room can also be combined in any order. In any case you
9872will automatically get a unique member ID and send a JOIN-message notifying 9872will automatically get a unique member ID and send a JOIN-message notifying
9873others about your entry and your public key from your selected ego. 9873others about your entry and your public key from your selected ego.
9874 9874
9875The ego can be selected by name with the initial @code{GNUNET_MESSENGER_connect} 9875The ego can be selected by name with the initial @code{GNUNET_MESSENGER_connect}
9876besides setting a (identity-)callback for each change/confirmation of the used 9876besides setting a (identity-)callback for each change/confirmation of the used
9877ego and a (message-)callback which gets called every time a message gets sent or 9877ego and a (message-)callback which gets called every time a message gets sent or
9878received in the room. Once the identity-callback got called you can check your 9878received in the room. Once the identity-callback got called you can check your
9879used ego with @code{GNUNET_MESSENGER_get_key} providing only its public key. The 9879used ego with @code{GNUNET_MESSENGER_get_key} providing only its public key. The
9880function returns NULL if the anonymous ego is used. If the ego should be 9880function returns NULL if the anonymous ego is used. If the ego should be
9881replaced with a newly generated one, you can use @code{GNUNET_MESSENGER_update} 9881replaced with a newly generated one, you can use @code{GNUNET_MESSENGER_update}
9882to ensure proper chaining of used egos. 9882to ensure proper chaining of used egos.
9883 9883
9884Also once the identity-callback got called you can check your used name with 9884Also once the identity-callback got called you can check your used name with
9885@code{GNUNET_MESSENGER_get_name} and potentially change or set a name via 9885@code{GNUNET_MESSENGER_get_name} and potentially change or set a name via
9886@code{GNUNET_MESSENGER_set_name}. A name is for example required to create a new 9886@code{GNUNET_MESSENGER_set_name}. A name is for example required to create a new
9887ego with @code{GNUNET_MESSENGER_update}. Also any change in ego or name will 9887ego with @code{GNUNET_MESSENGER_update}. Also any change in ego or name will
9888automatically be distributed in the room with a NAME- or KEY-message 9888automatically be distributed in the room with a NAME- or KEY-message
9889respectively. 9889respectively.
9890 9890
9891To send a message a message inside of a room you can use 9891To send a message a message inside of a room you can use
9892@code{GNUNET_MESSENGER_send_message}. If you specify a selected contact as 9892@code{GNUNET_MESSENGER_send_message}. If you specify a selected contact as
9893receiver, the message gets encrypted automatically and will be sent as PRIVATE- 9893receiver, the message gets encrypted automatically and will be sent as PRIVATE-
9894message instead. 9894message instead.
9895 9895
9896To request a potentially missed message or to get a specific message after its 9896To request a potentially missed message or to get a specific message after its
9897original call of the message-callback, you can use 9897original call of the message-callback, you can use
9898@code{GNUNET_MESSENGER_get_message}. Additionally once a message was distributed 9898@code{GNUNET_MESSENGER_get_message}. Additionally once a message was distributed
9899to application level and the message-callback got called, you can get the 9899to application level and the message-callback got called, you can get the
9900contact respresenting a message's sender respectively with 9900contact respresenting a message's sender respectively with
9901@code{GNUNET_MESSENGER_get_sender}. This allows getting name and the public key 9901@code{GNUNET_MESSENGER_get_sender}. This allows getting name and the public key
9902of any sender currently in use with @code{GNUNET_MESSENGER_contact_get_name} 9902of any sender currently in use with @code{GNUNET_MESSENGER_contact_get_name}
9903and @code{GNUNET_MESSENGER_contact_get_key}. It is also possible to iterate 9903and @code{GNUNET_MESSENGER_contact_get_key}. It is also possible to iterate
9904through all current members of a room with 9904through all current members of a room with
9905@code{GNUNET_MESSENGER_iterate_members} using a callback. 9905@code{GNUNET_MESSENGER_iterate_members} using a callback.
9906 9906
9907To leave a room you can use @code{GNUNET_MESSENGER_close_room} which will also 9907To leave a room you can use @code{GNUNET_MESSENGER_close_room} which will also
9908close the rooms connections once all applications on the same peer have left 9908close the rooms connections once all applications on the same peer have left
9909the room. Leaving a room will also send a LEAVE-message closing a member session 9909the room. Leaving a room will also send a LEAVE-message closing a member session
9910on all connected peers before any connection will be closed. Leaving a room is 9910on all connected peers before any connection will be closed. Leaving a room is
9911however not required for any application to keep your member session open 9911however not required for any application to keep your member session open
9912between multiple sessions of the actual application. 9912between multiple sessions of the actual application.
9913 9913
9914Finally, when an application no longer wants to use CADET, it should call 9914Finally, when an application no longer wants to use CADET, it should call
9915@code{GNUNET_MESSENGER_disconnect}. You don't have to explicitly close the used 9915@code{GNUNET_MESSENGER_disconnect}. You don't have to explicitly close the used
9916rooms or leave them. 9916rooms or leave them.
9917 9917
9918Here is a little summary to the kinds of messages you can send manually: 9918Here is a little summary to the kinds of messages you can send manually:
@@ -9928,33 +9928,33 @@ Here is a little summary to the kinds of messages you can send manually:
9928@node MERGE-message 9928@node MERGE-message
9929@subsubsection MERGE-message 9929@subsubsection MERGE-message
9930 9930
9931MERGE-messages will generally be sent automatically to reduce the amount of 9931MERGE-messages will generally be sent automatically to reduce the amount of
9932parallel chained messages. This is necessary to close a member session for 9932parallel chained messages. This is necessary to close a member session for
9933example. You can also send MERGE-messages manually if required to merge two 9933example. You can also send MERGE-messages manually if required to merge two
9934chains of messages. 9934chains of messages.
9935 9935
9936@node INVITE-message 9936@node INVITE-message
9937@subsubsection INVITE-message 9937@subsubsection INVITE-message
9938 9938
9939INVITE-messages can be used to invite other members in a room to a different 9939INVITE-messages can be used to invite other members in a room to a different
9940room, sharing one potential door and the required key to enter the room. This 9940room, sharing one potential door and the required key to enter the room. This
9941kind of message is typically sent as encrypted PRIVATE-message to selected 9941kind of message is typically sent as encrypted PRIVATE-message to selected
9942members because it doesn't make much sense to invite all members from one room 9942members because it doesn't make much sense to invite all members from one room
9943to another considering a rooms key doesn't specify its usage. 9943to another considering a rooms key doesn't specify its usage.
9944 9944
9945@node TEXT-message 9945@node TEXT-message
9946@subsubsection TEXT-message 9946@subsubsection TEXT-message
9947 9947
9948TEXT-messages can be used to send simple text-based messages and should be 9948TEXT-messages can be used to send simple text-based messages and should be
9949considered as being in readable form without complex decoding. The text has to 9949considered as being in readable form without complex decoding. The text has to
9950end with a NULL-terminator character and should be in UTF-8 encoding for most 9950end with a NULL-terminator character and should be in UTF-8 encoding for most
9951compatibility. 9951compatibility.
9952 9952
9953@node FILE-message 9953@node FILE-message
9954@subsubsection FILE-message 9954@subsubsection FILE-message
9955 9955
9956FILE-messages can be used to share files inside of a room. They do not contain 9956FILE-messages can be used to share files inside of a room. They do not contain
9957the actual file being shared but its original hash, filename, URI to download 9957the actual file being shared but its original hash, filename, URI to download
9958the file and a symmetric key to decrypt the downloaded file. 9958the file and a symmetric key to decrypt the downloaded file.
9959 9959
9960It is recommended to use the FS subsystem and the FILE-messages in combination. 9960It is recommended to use the FS subsystem and the FILE-messages in combination.
@@ -9962,30 +9962,29 @@ It is recommended to use the FS subsystem and the FILE-messages in combination.
9962@node DELETE-message 9962@node DELETE-message
9963@subsubsection DELETE-message 9963@subsubsection DELETE-message
9964 9964
9965DELETE-messages can be used to delete messages selected with its hash. You can 9965DELETE-messages can be used to delete messages selected with its hash. You can
9966also select any custom delay relative to the time of sending the DELETE-message. 9966also select any custom delay relative to the time of sending the DELETE-message.
9967Deletion will only be processed on each peer in a room if the sender is 9967Deletion will only be processed on each peer in a room if the sender is
9968authorized. 9968authorized.
9969 9969
9970The only information of a deleted message which being kept will be the chained 9970The only information of a deleted message which being kept will be the chained
9971hashes connecting the message graph for potential traversion. For example the 9971hashes connecting the message graph for potential traversion. For example the
9972check for completion of a member session requires this information. 9972check for completion of a member session requires this information.
9973 9973
9974@node Member sessions 9974@node Member sessions
9975@subsection Member sessions 9975@subsection Member sessions
9976 9976
9977A member session is a triple of the room key, the member ID and the public key 9977A member session is a triple of the room key, the member ID and the public key
9978of the member's ego. Member sessions allow that a member can change their ID or 9978of the member's ego. Member sessions allow that a member can change their ID or
9979their ego once at a time without losing the ability to delete old messages or 9979their ego once at a time without losing the ability to delete old messages or
9980identifying the original sender of a message. On every change of ID or EGO a 9980identifying the original sender of a message. On every change of ID or EGO a
9981session will be marked as closed. So every session chain will only contain one 9981session will be marked as closed. So every session chain will only contain one
9982open session with the current ID and public key. 9982open session with the current ID and public key.
9983 9983
9984If a session is marked as closed the MESSENGER service will check from the first 9984If a session is marked as closed the MESSENGER service will check from the first
9985message opening a session to its last one closing the session for completion. If 9985message opening a session to its last one closing the session for completion. If
9986a the service can confirm that there is no message still missing which was sent 9986a the service can confirm that there is no message still missing which was sent
9987from the closed member session, it will be marked as completed. 9987from the closed member session, it will be marked as completed.
9988 9988
9989A completed member session is not able to verify any incoming message to ensure 9989A completed member session is not able to verify any incoming message to ensure
9990forward secrecy preventing others from using old stolen egos. 9990forward secrecy preventing others from using old stolen egos.
9991