commit 179506891edd9d43ee67e0dfdc3ce3e2c8ceb3bb
parent e5b42badb7450aee5367e70294a0f8b1595945eb
Author: TheJackiMonster <thejackimonster@gmail.com>
Date: Fri, 17 Nov 2023 17:30:12 +0100
update messenger API regarding recent changes
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
Diffstat:
2 files changed, 45 insertions(+), 39 deletions(-)
diff --git a/developers/apis/messenger.rst b/developers/apis/messenger.rst
@@ -29,25 +29,32 @@ PEER-message sharing your peer's identity in the room.
Entering or opening a room can also be combined in any order. In any
case you will automatically get a unique member ID and send a
-JOIN-message notifying others about your entry and your public key from
-your selected ego.
+JOIN-message notifying others about your entry and your public key
+derived from your selected private key.
-The ego can be selected by name with the initial
-``GNUNET_MESSENGER_connect`` besides setting a (identity-)callback for
-each change/confirmation of the used ego and a (message-)callback which
+The private key can be selected in combination with a name using
+``GNUNET_MESSENGER_connect`` besides setting a (message-)callback which
gets called every time a message gets sent or received in the room. Once
-the identity-callback got called you can check your used ego with
+the handle is initialized you can check your used key pair with
``GNUNET_MESSENGER_get_key`` providing only its public key. The function
-returns NULL if the anonymous ego is used. If the ego should be replaced
-with a newly generated one, you can use ``GNUNET_MESSENGER_update`` to
-ensure proper chaining of used egos.
+returns NULL if the anonymous key pair is used. If the key pair should
+be replaced with a different one, you can use
+``GNUNET_MESSENGER_set_key`` to ensure proper chaining of used private
+keys.
-Also once the identity-callback got called you can check your used name
+This will automatically cause the handle to send a KEY-message which
+introduces the change of key pair to all other members in the rooms you
+have entered or opened. Your sessions will therefore stay valid while
+your old key pair gets replaced, signing the exchange.
+
+Also once the handle is initialized you can check your current name
with ``GNUNET_MESSENGER_get_name`` and potentially change or set a name
-via ``GNUNET_MESSENGER_set_name``. A name is for example required to
-create a new ego with ``GNUNET_MESSENGER_update``. Also any change in
-ego or name will automatically be distributed in the room with a NAME-
-or KEY-message respectively.
+via ``GNUNET_MESSENGER_set_name``. Any change in name will automatically
+be distributed in all entered or opened rooms with a NAME-message.
+
+In case you have adjusted your name separately in a specific room of
+choice by sending a NAME-message manually, that room will not be
+affected by the change of your handle's name.
To send a message a message inside of a room you can use
``GNUNET_MESSENGER_send_message``. If you specify a selected contact as
@@ -80,15 +87,11 @@ the used rooms or leave them.
Here is a little summary to the kinds of messages you can send manually:
-.. _MERGE_002dmessage:
-
-MERGE-message
-^^^^^^^^^^^^^
+.. _NAME_002dmessage:
-MERGE-messages will generally be sent automatically to reduce the amount
-of parallel chained messages. This is necessary to close a member
-session for example. You can also send MERGE-messages manually if
-required to merge two chains of messages.
+NAME-messages can be used to change the name (or nick) of your identity
+inside a room. The selected name can differ from the identifier used to
+select your private key for signing and decrypting messages.
.. _INVITE_002dmessage:
@@ -146,12 +149,12 @@ Member sessions
---------------
A member session is a triple of the room key, the member ID and the
-public key of the member's ego. Member sessions allow that a member can
-change their ID or their ego once at a time without losing the ability
-to delete old messages or identifying the original sender of a message.
-On every change of ID or EGO a session will be marked as closed. So
-every session chain will only contain one open session with the current
-ID and public key.
+public key of the member's key pair. Member sessions allow that a member
+can change their ID or their private key once at a time without losing
+the ability to delete old messages or identifying the original sender
+of a message. On every change of ID or private key a session will be
+marked as closed. So every session chain will only contain one open
+session with the current ID and public key.
If a session is marked as closed the MESSENGER service will check from
the first message opening a session to its last one closing the session
@@ -160,6 +163,7 @@ still missing which was sent from the closed member session, it will be
marked as completed.
A completed member session is not able to verify any incoming message to
-ensure forward secrecy preventing others from using old stolen egos.
+ensure forward secrecy preventing others from using old stolen private
+keys.
.. |messenger_room| image:: /images/messenger_room.png
diff --git a/users/messenger.rst b/users/messenger.rst
@@ -48,7 +48,8 @@ Entering a room
You can enter any room by its ROOMKEY and any PEERIDENTITY of a hosting
peer. Optionally you can provide any IDENTITY which can represent a
-local ego by its name.
+local ego by its name. This will automatically select that ego's private
+key to sign your messages with.
::
@@ -67,11 +68,11 @@ through the CADET submodule. You can also optionally leave out the '-r'
parameter and the ROOMKEY to use the zeroed hash instead.
If no IDENTITY is provided you will not send any name to others, you
-will be referred as \"anonymous\" instead and use the anonymous ego. If
-you provide any IDENTITY a matching ego will be used to sign your
-messages. If there is no matching ego you will use the anonymous ego
-instead. The provided IDENTITY will be distributed as your name for the
-service in any case.
+will be referred as \"anonymous\" instead and use the anonymous ego (a
+shared key pair known to all peers). If you provide any IDENTITY a
+matching ego will be used to sign your messages. If there is no matching
+ego you will use the anonymous ego instead. The provided IDENTITY will
+be distributed as your name for the service in any case.
.. _Opening-a-room:
@@ -124,9 +125,10 @@ Private messaging
As referred in the introduction the service allows sending private
messages with additional end-to-end encryption. These messages will be
visually represented by messages of the kind 'PRIVATE' in case they
-can't be decrypted with your used ego. Members who can't decrypt the
-message can potentially only identify its sender but they can't identify
-its receiver.
+can't be decrypted with your used private key. Members who can't decrypt
+the message can potentially only identify its sender but they can't
+identify its receiver. This prevents other members from collecting more
+metadata than necessary about you.
.. code-block:: text
@@ -147,7 +149,7 @@ instead of usual text messages by adding the '-p' parameter:
$ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY -p
Notice that you can only send such encrypted messages to members who use
-an ego which is not publicly known as the anonymous ego to ensure
+a private key which is not publicly known via the anonymous ego to ensure
transparency. If any user could decrypt these messages they would not be
private. So as receiver of such messages the IDENTITY is required and it
has to match a local ego.
