From ca912f85dae6b61dd80ab02d0e3f0b20a556da7c Mon Sep 17 00:00:00 2001 From: TheJackiMonster Date: Thu, 12 Nov 2020 20:58:07 +0100 Subject: -remerge branch 'jacki/messenger' This reverts commit e11d1e59e4ae5f7d89c33df3ae9ca8f1ece990cf. --- src/include/gnunet_messenger_service.h | 436 +++++++++++++++++++++++++++++++++ 1 file changed, 436 insertions(+) create mode 100644 src/include/gnunet_messenger_service.h (limited to 'src/include/gnunet_messenger_service.h') diff --git a/src/include/gnunet_messenger_service.h b/src/include/gnunet_messenger_service.h new file mode 100644 index 000000000..8f5315c30 --- /dev/null +++ b/src/include/gnunet_messenger_service.h @@ -0,0 +1,436 @@ +/* + This file is part of GNUnet. + Copyright (C) 2020 GNUnet e.V. + + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + + SPDX-License-Identifier: AGPL3.0-or-later + */ +/** + * @author Tobias Frisch + * + * @file + * MESSENGER service; manages decentralized chat groups + * + * @defgroup messenger MESSENGER service + * Instant messaging based on the CADET subsystem + * + * @{ + */ + +#ifndef GNUNET_MESSENGER_SERVICE_H +#define GNUNET_MESSENGER_SERVICE_H + +#ifdef __cplusplus +extern "C" { +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +#include "platform.h" +#include "gnunet_configuration_lib.h" +#include "gnunet_crypto_lib.h" +#include "gnunet_identity_service.h" +#include "gnunet_mq_lib.h" +#include "gnunet_protocols.h" +#include "gnunet_scheduler_lib.h" +#include "gnunet_time_lib.h" + +#define GNUNET_MESSENGER_SERVICE_NAME "messenger" + +/** + * Opaque handle to the messenger + */ +struct GNUNET_MESSENGER_Handle; + +/** + * Opaque handle to a room + */ +struct GNUNET_MESSENGER_Room; + +/** + * Opaque handle to a contact + */ +struct GNUNET_MESSENGER_Contact; + +/** + * Enum for the different supported kinds of messages + */ +enum GNUNET_MESSENGER_MessageKind +{ + GNUNET_MESSENGER_KIND_INFO = 1, + + GNUNET_MESSENGER_KIND_JOIN = 2, + GNUNET_MESSENGER_KIND_LEAVE = 3, + + GNUNET_MESSENGER_KIND_NAME = 4, + GNUNET_MESSENGER_KIND_KEY = 5, + GNUNET_MESSENGER_KIND_PEER = 6, + GNUNET_MESSENGER_KIND_ID = 7, + + GNUNET_MESSENGER_KIND_MISS = 8, + GNUNET_MESSENGER_KIND_MERGE = 9, + GNUNET_MESSENGER_KIND_REQUEST = 10, + + GNUNET_MESSENGER_KIND_INVITE = 11, + GNUNET_MESSENGER_KIND_TEXT = 12, + GNUNET_MESSENGER_KIND_FILE = 13, + + GNUNET_MESSENGER_KIND_PRIVATE = 14, + + GNUNET_MESSENGER_KIND_UNKNOWN = 0 +}__attribute__((__packed__)); + +/** + * Get the name of a message kind. + * + * @param kind Kind of a message + * @return Name of that kind + */ +const char* +GNUNET_MESSENGER_name_of_kind (enum GNUNET_MESSENGER_MessageKind kind); + +struct GNUNET_MESSENGER_MessageHeader +{ + struct GNUNET_IDENTITY_Signature signature; + + struct GNUNET_TIME_AbsoluteNBO timestamp; + + struct GNUNET_ShortHashCode sender_id; + struct GNUNET_HashCode previous; + + enum GNUNET_MESSENGER_MessageKind kind; +}; + +struct GNUNET_MESSENGER_MessageInfo +{ + struct GNUNET_IDENTITY_PublicKey host_key; + struct GNUNET_ShortHashCode unique_id; +}; + +struct GNUNET_MESSENGER_MessageJoin +{ + struct GNUNET_IDENTITY_PublicKey key; +}; + +struct GNUNET_MESSENGER_MessageLeave +{ +}; + +struct GNUNET_MESSENGER_MessageName +{ + char *name; +}; + +struct GNUNET_MESSENGER_MessageKey +{ + struct GNUNET_IDENTITY_PublicKey key; +}; + +struct GNUNET_MESSENGER_MessagePeer +{ + struct GNUNET_PeerIdentity peer; +}; + +struct GNUNET_MESSENGER_MessageId +{ + struct GNUNET_ShortHashCode id; +}; + +struct GNUNET_MESSENGER_MessageMiss +{ + struct GNUNET_PeerIdentity peer; +}; + +struct GNUNET_MESSENGER_MessageMerge +{ + struct GNUNET_HashCode previous; +}; + +struct GNUNET_MESSENGER_MessageRequest +{ + struct GNUNET_HashCode hash; +}; + +struct GNUNET_MESSENGER_MessageInvite +{ + struct GNUNET_PeerIdentity door; + struct GNUNET_HashCode key; +}; + +struct GNUNET_MESSENGER_MessageText +{ + char *text; +}; + +struct GNUNET_MESSENGER_MessageFile +{ + struct GNUNET_CRYPTO_SymmetricSessionKey key; + struct GNUNET_HashCode hash; + char name[NAME_MAX]; + char *uri; +}; + +struct GNUNET_MESSENGER_MessagePrivate +{ + struct GNUNET_CRYPTO_EcdhePublicKey key; + + uint16_t length; + char *data; +}; + +struct GNUNET_MESSENGER_MessageBody +{ + union + { + struct GNUNET_MESSENGER_MessageInfo info; + + struct GNUNET_MESSENGER_MessageJoin join; + struct GNUNET_MESSENGER_MessageLeave leave; + + struct GNUNET_MESSENGER_MessageName name; + struct GNUNET_MESSENGER_MessageKey key; + struct GNUNET_MESSENGER_MessagePeer peer; + struct GNUNET_MESSENGER_MessageId id; + + struct GNUNET_MESSENGER_MessageMiss miss; + struct GNUNET_MESSENGER_MessageMerge merge; + struct GNUNET_MESSENGER_MessageRequest request; + + struct GNUNET_MESSENGER_MessageInvite invite; + struct GNUNET_MESSENGER_MessageText text; + struct GNUNET_MESSENGER_MessageFile file; + + struct GNUNET_MESSENGER_MessagePrivate private; + }; +}; + +/** + * Struct to a message + */ +struct GNUNET_MESSENGER_Message +{ + struct GNUNET_MESSENGER_MessageHeader header; + struct GNUNET_MESSENGER_MessageBody body; +}; + +/** + * Method called whenever the EGO of a handle changes or if the first connection fails + * to load a valid EGO and the anonymous keypair will be used instead. + * + * @param cls Closure from GNUNET_MESSENGER_connect + * @param handle Messenger handle + */ +typedef void +(*GNUNET_MESSENGER_IdentityCallback) (void *cls, struct GNUNET_MESSENGER_Handle *handle); + +/** + * Method called whenever a message is sent or received from a room. + * + * @param cls Closure from GNUNET_MESSENGER_connect + * @param room Room handle + * @param message Newly received or sent message + * @param hash Hash identifying the message + */ +typedef void +(*GNUNET_MESSENGER_MessageCallback) (void *cls, const struct GNUNET_MESSENGER_Room *room, + const struct GNUNET_MESSENGER_Message *message, const struct GNUNET_HashCode *hash); + +/** + * Set up a handle for the messenger related functions and connects to all necessary services. It will look up the ego + * key identified by its name and use it for signing all messages from the handle. + * + * @param cfg Configuration to use + * @param name Name to look up an ego or NULL to stay anonymous + * @param identity_callback Function called when the EGO of the handle changes + * @param identity_cls Closure for the identity_callback handler + * @param msg_callback Function called when a new message is sent or received + * @param msg_cls Closure for the msg_callback handler + * @return Messenger handle to use, NULL on error + */ +struct GNUNET_MESSENGER_Handle* +GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *name, + GNUNET_MESSENGER_IdentityCallback identity_callback, void *identity_cls, + GNUNET_MESSENGER_MessageCallback msg_callback, void *msg_cls); + +/** + * Update a handle of the messenger to use a different ego key and replace the old one with a newly generated one. All + * participated rooms get informed about the key renewal. The handle requires a set name for this function to work and + * it needs to be unused by other egos. + * + * Keep in mind that this will fully delete the old ego key (if any is used) even if any other service wants to use it + * as default. + * + * @param handle Messenger handle to use + * @return GNUNET_OK on success, GNUNET_SYSERR on failure + */ +int +GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); + +/** + * Disconnect all of the messengers used services and clears up its used memory. + * + * @param handle Messenger handle to use + */ +void +GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); + +/** + * Get the name (if specified, otherwise NULL) used by the messenger. + * + * @param handle Messenger handle to use + * @return Name used by the messenger or NULL + */ +const char* +GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); + +/** + * Set the name for the messenger. This will rename the currently used ego and move all stored files related to the current + * name to its new directory. If anything fails during this process the function returns GNUNET_NO and the name for + * the messenger won't change as specified. + * + * @param handle Messenger handle to use + * @param name Name for the messenger to change to + * @return GNUNET_YES on success, GNUNET_NO on failure and GNUNET_SYSERR if handle is NULL + */ +int +GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, const char *name); + +/** + * Get the public key used by the messenger. + * + * @param handle Messenger handle to use + * @return Used ego's public key + */ +const struct GNUNET_IDENTITY_PublicKey* +GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); + +/** + * Open a room to send and receive messages. The room will use the specified key as port for the underlying cadet + * service. Opening a room results in opening the port for incoming connections as possible door. + * + * Notice that there can only be one room related to a specific key. So trying to open two rooms with the same + * key will result in opening the room once but returning the handle both times because the room stays open. + * + * You can also open a room after entering it through a door using GNUNET_MESSENGER_entry_room(...). This + * will notify all entered doors to list you as new door. + * + * ( All doors form a ring structured network to shorten the latency sending and receiving messages. ) + * + * @param handle Messenger handle to use + * @param key Hash identifying the port + * @return Room handle, NULL on error + */ +struct GNUNET_MESSENGER_Room* +GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_HashCode *key); + +/** + * Enter a room to send and receive messages through a door opened using GNUNET_MESSENGER_open_room(...). + * + * Notice that there can only be one room related to a specific key. So trying to enter two rooms with the same + * key will result in entering the room once but returning the handle both times because the room stays entered. + * You can however enter a room through multiple doors in parallel which results in connecting both ends. But + * entering the room through the same door won't have any effect after the first time. + * + * You can also enter a room through a door after opening it using GNUNET_MESSENGER_open_room(...). But the + * door may not be your own peer identity. + * + * ( All doors form a ring structured network to shorten the latency sending and receiving messages. ) + * + * @param handle Messenger handle to use + * @param door Peer identity of an open door + * @param key Hash identifying the port + * @return Room handle, NULL on error + */ +struct GNUNET_MESSENGER_Room* +GNUNET_MESSENGER_entry_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_PeerIdentity *door, + const struct GNUNET_HashCode *key); + +/** + * Close a room which was entered, opened or both in various order and variety. Closing a room will destroy all connections + * from your peer to another and the other way around. + * + * ( After a member closes a door, all members entered through that specific door have to use another one + * or open the room on their own. ) + * + * @param room Room handle + */ +void +GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); + +/** + * Get the contact of a member in a room identified by their id. + * + * Notice that contacts are independent of rooms but will be removed if all rooms containing these contacts get closed. + * + * @param room Room handle + * @param id Hash identifying a member + * @return Contact handle, NULL if id is not in use + */ +struct GNUNET_MESSENGER_Contact* +GNUNET_MESSENGER_get_member (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_ShortHashCode *id); + +/** + * Get the name used by the contact. + * + * @param contact Contact handle + * @return Name of contact or NULL + */ +const char* +GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); + +/** + * Get the public key used by the contact. + * + * @param contact Contact handle + * @return Public key of the ego used by contact + */ +const struct GNUNET_IDENTITY_PublicKey* +GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); + +/** + * Send a message into a room. If you opened the room all entered members will receive the + * message. If you entered the room through a door all so entered doors will receive the + * message as well. All members receiving the message will also propagate this message recursively + * as long as the message is unknown to them. + * + * Notice that all messages sent and received are also stored and can be propagated to new members entering the room. + * + * @param room Room handle + * @param message New message to send + */ +void +GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct GNUNET_MESSENGER_Message *message); + +/** + * Get the message in a room identified by its hash. + * + * @param room Room handle + * @param hash Hash identifying a message + * @return Message struct or NULL if no message with that hash is known + */ +const struct GNUNET_MESSENGER_Message* +GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +#endif //GNUNET_MESSENGER_SERVICE_H + +/** @} *//* end of group */ -- cgit v1.2.3 From 99e61479aec983fca8c835fdeb24c9c840513f63 Mon Sep 17 00:00:00 2001 From: TheJackiMonster Date: Thu, 12 Nov 2020 21:47:52 +0100 Subject: -added more docs for messenger Signed-off-by: TheJackiMonster --- src/include/gnunet_messenger_service.h | 197 ++++++++++++++++++++++++++++++++- 1 file changed, 191 insertions(+), 6 deletions(-) (limited to 'src/include/gnunet_messenger_service.h') diff --git a/src/include/gnunet_messenger_service.h b/src/include/gnunet_messenger_service.h index 8f5315c30..96d308a01 100644 --- a/src/include/gnunet_messenger_service.h +++ b/src/include/gnunet_messenger_service.h @@ -70,28 +70,81 @@ struct GNUNET_MESSENGER_Contact; */ enum GNUNET_MESSENGER_MessageKind { + /** + * The info kind. The message contains a #GNUNET_MESSENGER_MessageInfo body. + */ GNUNET_MESSENGER_KIND_INFO = 1, + /** + * The join kind. The message contains a #GNUNET_MESSENGER_MessageJoin body. + */ GNUNET_MESSENGER_KIND_JOIN = 2, + + /** + * The leave kind. The message contains a #GNUNET_MESSENGER_MessageLeave body. + */ GNUNET_MESSENGER_KIND_LEAVE = 3, + /** + * The name kind. The message contains a #GNUNET_MESSENGER_MessageName body. + */ GNUNET_MESSENGER_KIND_NAME = 4, + + /** + * The key kind. The message contains a #GNUNET_MESSENGER_MessageKey body. + */ GNUNET_MESSENGER_KIND_KEY = 5, + + /** + * The peer kind. The message contains a #GNUNET_MESSENGER_MessagePeer body. + */ GNUNET_MESSENGER_KIND_PEER = 6, + + /** + * The id kind. The message contains a #GNUNET_MESSENGER_MessageId body. + */ GNUNET_MESSENGER_KIND_ID = 7, + /** + * The miss kind. The message contains a #GNUNET_MESSENGER_MessageMiss body. + */ GNUNET_MESSENGER_KIND_MISS = 8, + + /** + * The merge kind. The message contains a #GNUNET_MESSENGER_MessageMerge body. + */ GNUNET_MESSENGER_KIND_MERGE = 9, + + /** + * The request kind. The message contains a #GNUNET_MESSENGER_MessageRequest body. + */ GNUNET_MESSENGER_KIND_REQUEST = 10, + /** + * The invite kind. The message contains a #GNUNET_MESSENGER_MessageInvite body. + */ GNUNET_MESSENGER_KIND_INVITE = 11, + + /** + * The text kind. The message contains a #GNUNET_MESSENGER_MessageText body. + */ GNUNET_MESSENGER_KIND_TEXT = 12, + + /** + * The file kind. The message contains a #GNUNET_MESSENGER_MessageFile body. + */ GNUNET_MESSENGER_KIND_FILE = 13, + /** + * The private kind. The message contains a #GNUNET_MESSENGER_MessagePrivate body. + */ GNUNET_MESSENGER_KIND_PRIVATE = 14, + /** + * The unknown kind. The message contains an unknown body. + */ GNUNET_MESSENGER_KIND_UNKNOWN = 0 -}__attribute__((__packed__)); +}; /** * Get the name of a message kind. @@ -102,117 +155,242 @@ enum GNUNET_MESSENGER_MessageKind const char* GNUNET_MESSENGER_name_of_kind (enum GNUNET_MESSENGER_MessageKind kind); +/** + * The header of a #GNUNET_MESSENGER_Message. + */ struct GNUNET_MESSENGER_MessageHeader { + /** + * The signature of the senders private key. + */ struct GNUNET_IDENTITY_Signature signature; + /** + * The timestamp of the message. + */ struct GNUNET_TIME_AbsoluteNBO timestamp; + /** + * The senders id inside of the room the message was sent in. + */ struct GNUNET_ShortHashCode sender_id; + + /** + * The hash of the previous message from the senders perspective. + */ struct GNUNET_HashCode previous; + /** + * The kind of the message. + */ enum GNUNET_MESSENGER_MessageKind kind; }; +/** + * An info message body. + */ struct GNUNET_MESSENGER_MessageInfo { + /** + * The senders key to verify its signatures. + */ struct GNUNET_IDENTITY_PublicKey host_key; + + /** + * The new unique id for the receiver in a room. + */ struct GNUNET_ShortHashCode unique_id; }; +/** + * A join message body. + */ struct GNUNET_MESSENGER_MessageJoin { + /** + * The senders public key to verify its signatures. + */ struct GNUNET_IDENTITY_PublicKey key; }; +/** + * A leave message body. + */ struct GNUNET_MESSENGER_MessageLeave { }; +/** + * A name message body. + */ struct GNUNET_MESSENGER_MessageName { + /** + * The new name which replaces the current senders name. + */ char *name; }; +/** + * A key message body. + */ struct GNUNET_MESSENGER_MessageKey { + /** + * The new public key which replaces the current senders public key. + */ struct GNUNET_IDENTITY_PublicKey key; }; +/** + * A peer message body. + */ struct GNUNET_MESSENGER_MessagePeer { + /** + * The peer identity of the sender opening a room. + */ struct GNUNET_PeerIdentity peer; }; +/** + * An id message body. + */ struct GNUNET_MESSENGER_MessageId { + /** + * The new id which will replace the senders id in a room. + */ struct GNUNET_ShortHashCode id; }; +/** + * A miss message body. + */ struct GNUNET_MESSENGER_MessageMiss { + /** + * The peer identity of a disconnected door to a room. + */ struct GNUNET_PeerIdentity peer; }; +/** + * A merge message body. + */ struct GNUNET_MESSENGER_MessageMerge { + /** + * The hash of a second previous message. + */ struct GNUNET_HashCode previous; }; +/** + * A request message body. + */ struct GNUNET_MESSENGER_MessageRequest { + /** + * The hash of the requested message. + */ struct GNUNET_HashCode hash; }; +/** + * An invite message body. + */ struct GNUNET_MESSENGER_MessageInvite { + /** + * The peer identity of an open door to a room. + */ struct GNUNET_PeerIdentity door; + + /** + * The hash identifying the port of the room. + */ struct GNUNET_HashCode key; }; +/** + * A text message body. + */ struct GNUNET_MESSENGER_MessageText { + /** + * The containing text. + */ char *text; }; +/** + * A file message body. + */ struct GNUNET_MESSENGER_MessageFile { + /** + * The symmetric key to decrypt the file. + */ struct GNUNET_CRYPTO_SymmetricSessionKey key; + + /** + * The hash of the original file. + */ struct GNUNET_HashCode hash; + + /** + * The name of the original file. + */ char name[NAME_MAX]; + + /** + * The uri of the encrypted file. + */ char *uri; }; +/** + * A private message body. + */ struct GNUNET_MESSENGER_MessagePrivate { + /** + * The ECDH key to decrypt the message. + */ struct GNUNET_CRYPTO_EcdhePublicKey key; + /** + * The length of the encrypted message. + */ uint16_t length; + + /** + * The data of the encrypted message. + */ char *data; }; +/** + * The unified body of a #GNUNET_MESSENGER_Message. + */ struct GNUNET_MESSENGER_MessageBody { union { struct GNUNET_MESSENGER_MessageInfo info; - struct GNUNET_MESSENGER_MessageJoin join; struct GNUNET_MESSENGER_MessageLeave leave; - struct GNUNET_MESSENGER_MessageName name; struct GNUNET_MESSENGER_MessageKey key; struct GNUNET_MESSENGER_MessagePeer peer; struct GNUNET_MESSENGER_MessageId id; - struct GNUNET_MESSENGER_MessageMiss miss; struct GNUNET_MESSENGER_MessageMerge merge; struct GNUNET_MESSENGER_MessageRequest request; - struct GNUNET_MESSENGER_MessageInvite invite; struct GNUNET_MESSENGER_MessageText text; struct GNUNET_MESSENGER_MessageFile file; - struct GNUNET_MESSENGER_MessagePrivate private; }; }; @@ -222,7 +400,14 @@ struct GNUNET_MESSENGER_MessageBody */ struct GNUNET_MESSENGER_Message { + /** + * Header. + */ struct GNUNET_MESSENGER_MessageHeader header; + + /** + * Body + */ struct GNUNET_MESSENGER_MessageBody body; }; -- cgit v1.2.3