gnunet_messenger_service.h

Go to the documentation of this file.

/*
   This file is part of GNUnet.
   Copyright (C) 2020--2025 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 <http://www.gnu.org/licenses/>.
 
   SPDX-License-Identifier: AGPL3.0-or-later
 */
#ifndef GNUNET_MESSENGER_SERVICE_H
#define GNUNET_MESSENGER_SERVICE_H
 
#ifdef __cplusplus
extern "C" {
#if 0 /* keep Emacsens' auto-indent happy */
}
#endif
#endif
 
#include "gnunet_util_lib.h"
 
#define GNUNET_MESSENGER_VERSION 0x00000006
 
#define GNUNET_MESSENGER_SERVICE_NAME "messenger"
 
struct GNUNET_MESSENGER_Handle;
 
struct GNUNET_MESSENGER_Room;
 
struct GNUNET_MESSENGER_Contact;
 
GNUNET_NETWORK_STRUCT_BEGIN
 
struct GNUNET_MESSENGER_RoomKeyCode
{
  uint8_t public_bit : 1;
  uint8_t group_bit : 1;
  uint8_t feed_bit : 1;
  uint8_t unused_bits : 5;
  uint8_t bits[sizeof(struct GNUNET_HashCode) - 1];  /* = 63 */
};
 
union GNUNET_MESSENGER_RoomKey
{
  struct GNUNET_HashCode hash;
  struct GNUNET_MESSENGER_RoomKeyCode code;
};
 
struct GNUNET_MESSENGER_RoomEntryRecord
{
  struct GNUNET_PeerIdentity door;
 
  struct GNUNET_HashCode key GNUNET_PACKED;
};
 
struct GNUNET_MESSENGER_RoomDetailsRecord
{
  char name[256];
 
  uint32_t flags;
};
 
struct GNUNET_MESSENGER_EpochIdentifierCode
{
  uint8_t group_bit : 1;
  uint8_t level_bits : 7;
  uint8_t bits[sizeof(struct GNUNET_ShortHashCode) - 1];  /* = 31 */
};
 
union GNUNET_MESSENGER_EpochIdentifier
{
  struct GNUNET_ShortHashCode hash;
  struct GNUNET_MESSENGER_EpochIdentifierCode code;
};
 
struct GNUNET_MESSENGER_RoomEpochKeyRecord
{
  struct GNUNET_HashCode key GNUNET_PACKED;
 
  struct GNUNET_HashCode hash GNUNET_PACKED;
 
  struct GNUNET_ShortHashCode identifier GNUNET_PACKED;
 
  struct GNUNET_CRYPTO_SymmetricSessionKey shared_key;
 
  uint32_t flags;
};
 
#define GNUNET_MESSENGER_EPOCH_NONCE_BYTES \
        sizeof (struct GNUNET_ShortHashCode)
 
struct GNUNET_MESSENGER_EpochNonceData
{
  uint8_t nonce[GNUNET_MESSENGER_EPOCH_NONCE_BYTES];
};
 
union GNUNET_MESSENGER_EpochNonce
{
  struct GNUNET_ShortHashCode hash;
  struct GNUNET_MESSENGER_EpochNonceData data;
};
 
GNUNET_NETWORK_STRUCT_END
 
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_DELETION = 15,
 
  GNUNET_MESSENGER_KIND_CONNECTION = 16,
 
  GNUNET_MESSENGER_KIND_TICKET = 17,
 
  GNUNET_MESSENGER_KIND_TRANSCRIPT = 18,
 
  GNUNET_MESSENGER_KIND_TAG = 19,
 
  GNUNET_MESSENGER_KIND_SUBSCRIBTION = 20,
 
  GNUNET_MESSENGER_KIND_TALK = 21,
 
  GNUNET_MESSENGER_KIND_ANNOUNCEMENT = 22,
 
  GNUNET_MESSENGER_KIND_SECRET = 23,
 
  GNUNET_MESSENGER_KIND_APPEAL = 24,
 
  GNUNET_MESSENGER_KIND_ACCESS = 25,
 
  GNUNET_MESSENGER_KIND_REVOLUTION = 26,
 
  GNUNET_MESSENGER_KIND_GROUP = 27,
 
  GNUNET_MESSENGER_KIND_AUTHORIZATION = 28,
 
  GNUNET_MESSENGER_KIND_UNKNOWN = 0
};
 
#define GNUNET_MESSENGER_KIND_MAX (GNUNET_MESSENGER_KIND_TALK)
 
const char*
GNUNET_MESSENGER_name_of_kind (enum GNUNET_MESSENGER_MessageKind kind);
 
void
GNUNET_MESSENGER_create_room_key (union GNUNET_MESSENGER_RoomKey *key,
                                  const char *input,
                                  enum GNUNET_GenericReturnValue is_public,
                                  enum GNUNET_GenericReturnValue is_group,
                                  enum GNUNET_GenericReturnValue is_feed);
 
struct GNUNET_MESSENGER_MessageHeader
{
  struct GNUNET_CRYPTO_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
{
  uint32_t messenger_version;
};
 
struct GNUNET_MESSENGER_MessageJoin
{
  struct GNUNET_HashCode epoch;
 
  struct GNUNET_CRYPTO_PublicKey key;
};
 
struct GNUNET_MESSENGER_MessageLeave
{
  struct GNUNET_HashCode epoch;
};
 
struct GNUNET_MESSENGER_MessageName
{
  char *name;
};
 
struct GNUNET_MESSENGER_MessageKey
{
  struct GNUNET_CRYPTO_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 epochs[2];
 
  struct GNUNET_HashCode previous;
};
 
struct GNUNET_MESSENGER_MessageRequest
{
  struct GNUNET_HashCode hash;
};
 
struct GNUNET_MESSENGER_MessageInvite
{
  struct GNUNET_PeerIdentity door;
 
  union GNUNET_MESSENGER_RoomKey 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
{
  uint16_t length;
 
  char *data;
};
 
struct GNUNET_MESSENGER_MessageDeletion
{
  struct GNUNET_HashCode hash;
 
  struct GNUNET_TIME_RelativeNBO delay;
};
 
struct GNUNET_MESSENGER_MessageConnection
{
  uint32_t amount;
 
  uint32_t flags;
};
 
struct GNUNET_MESSENGER_MessageTicket
{
  char *identifier;
};
 
struct GNUNET_MESSENGER_MessageTranscript
{
  struct GNUNET_HashCode hash;
 
  struct GNUNET_CRYPTO_PublicKey key;
 
  uint16_t length;
 
  char *data;
};
 
struct GNUNET_MESSENGER_MessageTag
{
  struct GNUNET_HashCode hash;
 
  char *tag;
};
 
struct GNUNET_MESSENGER_MessageSubscribtion
{
  struct GNUNET_ShortHashCode discourse;
 
  struct GNUNET_TIME_RelativeNBO time;
 
  uint32_t flags;
};
 
struct GNUNET_MESSENGER_MessageTalk
{
  struct GNUNET_ShortHashCode discourse;
 
  uint16_t length;
 
  char *data;
};
 
struct GNUNET_MESSENGER_MessageAnnouncement
{
  union GNUNET_MESSENGER_EpochIdentifier identifier;
 
  struct GNUNET_CRYPTO_EcdhePublicKey key;
 
  union GNUNET_MESSENGER_EpochNonce nonce;
 
  struct GNUNET_TIME_RelativeNBO timeout;
 
  struct GNUNET_HashCode hmac;
};
 
#define GNUNET_MESSENGER_SECRET_IV_BYTES \
        sizeof (struct GNUNET_CRYPTO_SymmetricInitializationVector)
 
struct GNUNET_MESSENGER_MessageSecret
{
  union GNUNET_MESSENGER_EpochIdentifier identifier;
 
  uint8_t iv[GNUNET_MESSENGER_SECRET_IV_BYTES];
 
  struct GNUNET_HashCode hmac;
 
  uint16_t length;
 
  char *data;
};
 
struct GNUNET_MESSENGER_MessageAppeal
{
  struct GNUNET_HashCode event;
 
  struct GNUNET_CRYPTO_EcdhePublicKey key;
 
  struct GNUNET_TIME_RelativeNBO timeout;
};
 
#define GNUNET_MESSENGER_ACCESS_KEY_BYTES \
        sizeof (struct GNUNET_CRYPTO_SymmetricSessionKey) + \
        GNUNET_CRYPTO_HPKE_SEAL_ONESHOT_OVERHEAD_BYTES
 
struct GNUNET_MESSENGER_MessageAccess
{
  struct GNUNET_HashCode event;
 
  uint8_t key[GNUNET_MESSENGER_ACCESS_KEY_BYTES];
 
  struct GNUNET_HashCode hmac;
};
 
struct GNUNET_MESSENGER_MessageRevolution
{
  union GNUNET_MESSENGER_EpochIdentifier identifier;
 
  union GNUNET_MESSENGER_EpochNonce nonce;
 
  struct GNUNET_HashCode hmac;
};
 
struct GNUNET_MESSENGER_MessageGroup
{
  union GNUNET_MESSENGER_EpochIdentifier identifier;
 
  struct GNUNET_HashCode initiator;
 
  struct GNUNET_HashCode partner;
 
  struct GNUNET_TIME_RelativeNBO timeout;
};
 
#define GNUNET_MESSENGER_AUTHORIZATION_KEY_BYTES \
        sizeof (struct GNUNET_CRYPTO_SymmetricSessionKey)
 
struct GNUNET_MESSENGER_MessageAuthorization
{
  union GNUNET_MESSENGER_EpochIdentifier identifier;
 
  struct GNUNET_HashCode event;
 
  uint8_t key[GNUNET_MESSENGER_AUTHORIZATION_KEY_BYTES];
 
  struct GNUNET_HashCode hmac;
};
 
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 privacy;
    struct GNUNET_MESSENGER_MessageDeletion deletion;
    struct GNUNET_MESSENGER_MessageConnection connection;
    struct GNUNET_MESSENGER_MessageTicket ticket;
    struct GNUNET_MESSENGER_MessageTranscript transcript;
    struct GNUNET_MESSENGER_MessageTag tag;
    struct GNUNET_MESSENGER_MessageSubscribtion subscribtion;
    struct GNUNET_MESSENGER_MessageTalk talk;
    struct GNUNET_MESSENGER_MessageAnnouncement announcement;
    struct GNUNET_MESSENGER_MessageSecret secret;
    struct GNUNET_MESSENGER_MessageAppeal appeal;
    struct GNUNET_MESSENGER_MessageAccess access;
    struct GNUNET_MESSENGER_MessageRevolution revolution;
    struct GNUNET_MESSENGER_MessageGroup group;
    struct GNUNET_MESSENGER_MessageAuthorization authorization;
  };
};
 
struct GNUNET_MESSENGER_Message
{
  struct GNUNET_MESSENGER_MessageHeader header;
 
  struct GNUNET_MESSENGER_MessageBody body;
};
 
enum GNUNET_MESSENGER_MessageFlags
{
  GNUNET_MESSENGER_FLAG_NONE = 0,
 
  GNUNET_MESSENGER_FLAG_SENT = 1,
 
  GNUNET_MESSENGER_FLAG_PRIVATE = 2,
 
  GNUNET_MESSENGER_FLAG_PEER = 4,
 
  GNUNET_MESSENGER_FLAG_RECENT = 8,
 
  GNUNET_MESSENGER_FLAG_UPDATE = 16,
 
  GNUNET_MESSENGER_FLAG_DELETE = 32,
 
  GNUNET_MESSENGER_FLAG_SECRET = 64,
 
  GNUNET_MESSENGER_FLAG_MEMBER = 128,
};
 
enum GNUNET_MESSENGER_ConnectionFlags
{
  GNUNET_MESSENGER_FLAG_CONNECTION_NONE = 0,
  GNUNET_MESSENGER_FLAG_CONNECTION_AUTO = 1,
};
 
enum GNUNET_MESSENGER_SubscriptionFlags
{
  GNUNET_MESSENGER_FLAG_SUBSCRIPTION_NONE = 0,
 
  GNUNET_MESSENGER_FLAG_SUBSCRIPTION_UNSUBSCRIBE = 1,
 
  GNUNET_MESSENGER_FLAG_SUBSCRIPTION_KEEP_ALIVE = 2,
};
 
enum GNUNET_MESSENGER_EpochFlags
{
  GNUNET_MESSENGER_FLAG_EPOCH_NONE = 0,
 
  GNUNET_MESSENGER_FLAG_EPOCH_VALID = 1,
};
 
typedef void
(*GNUNET_MESSENGER_MessageCallback) (void *cls,
                                     struct GNUNET_MESSENGER_Room *room,
                                     const struct
                                     GNUNET_MESSENGER_Contact *sender,
                                     const struct
                                     GNUNET_MESSENGER_Contact *recipient,
                                     const struct
                                     GNUNET_MESSENGER_Message *message,
                                     const struct GNUNET_HashCode *hash,
                                     enum GNUNET_MESSENGER_MessageFlags flags);
 
typedef enum GNUNET_GenericReturnValue
(*GNUNET_MESSENGER_MemberCallback) (void *cls,
                                    struct GNUNET_MESSENGER_Room *room,
                                    const struct
                                    GNUNET_MESSENGER_Contact *contact);
 
struct GNUNET_MESSENGER_Handle*
GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
                          const char *name,
                          const struct GNUNET_CRYPTO_PrivateKey *key,
                          GNUNET_MESSENGER_MessageCallback msg_callback,
                          void *msg_cls);
 
void
GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle);
 
const char*
GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle);
 
enum GNUNET_GenericReturnValue
GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle,
                           const char *name);
 
const struct GNUNET_CRYPTO_PublicKey*
GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle);
 
enum GNUNET_GenericReturnValue
GNUNET_MESSENGER_set_key (struct GNUNET_MESSENGER_Handle *handle,
                          const struct GNUNET_CRYPTO_PrivateKey *key);
 
struct GNUNET_MESSENGER_Room*
GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle,
                            const union GNUNET_MESSENGER_RoomKey *key);
 
struct GNUNET_MESSENGER_Room*
GNUNET_MESSENGER_enter_room (struct GNUNET_MESSENGER_Handle *handle,
                             const struct GNUNET_PeerIdentity *door,
                             const union GNUNET_MESSENGER_RoomKey *key);
 
void
GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room);
 
int
GNUNET_MESSENGER_find_rooms (const struct GNUNET_MESSENGER_Handle *handle,
                             const struct GNUNET_MESSENGER_Contact *contact,
                             GNUNET_MESSENGER_MemberCallback callback,
                             void *cls);
 
const struct GNUNET_HashCode*
GNUNET_MESSENGER_room_get_key (const struct GNUNET_MESSENGER_Room *room);
 
const struct GNUNET_MESSENGER_Contact*
GNUNET_MESSENGER_get_sender (const struct GNUNET_MESSENGER_Room *room,
                             const struct GNUNET_HashCode *hash);
 
const struct GNUNET_MESSENGER_Contact*
GNUNET_MESSENGER_get_recipient (const struct GNUNET_MESSENGER_Room *room,
                                const struct GNUNET_HashCode *hash);
 
const char*
GNUNET_MESSENGER_contact_get_name (const struct
                                   GNUNET_MESSENGER_Contact *contact);
 
const struct GNUNET_CRYPTO_PublicKey*
GNUNET_MESSENGER_contact_get_key (const struct
                                  GNUNET_MESSENGER_Contact *contact);
 
size_t
GNUNET_MESSENGER_contact_get_id (const struct
                                 GNUNET_MESSENGER_Contact *contact);
 
void
GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room,
                               const struct GNUNET_MESSENGER_Message *message,
                               const struct GNUNET_MESSENGER_Contact *contact);
 
void
GNUNET_MESSENGER_delete_message (struct GNUNET_MESSENGER_Room *room,
                                 const struct GNUNET_HashCode *hash,
                                 const struct GNUNET_TIME_Relative delay);
 
const struct GNUNET_MESSENGER_Message*
GNUNET_MESSENGER_get_message (struct GNUNET_MESSENGER_Room *room,
                              const struct GNUNET_HashCode *hash);
 
int
GNUNET_MESSENGER_iterate_members (struct GNUNET_MESSENGER_Room *room,
                                  GNUNET_MESSENGER_MemberCallback callback,
                                  void *cls);
 
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
#ifdef __cplusplus
}
#endif
 
#endif // GNUNET_MESSENGER_SERVICE_H
/* end of group */