/*
This file is part of GNUnet.
- (C) 2001 - 2011 Christian Grothoff (and other contributing authors)
+ Copyright (C) 2007 - 2017 GNUnet e.V.
- GNUnet is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published
- by the Free Software Foundation; either version 3, or (at your
- option) any later version.
+ 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
- General Public License for more details.
+ 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/>.
- You should have received a copy of the GNU General Public License
- along with GNUnet; see the file COPYING. If not, write to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ SPDX-License-Identifier: AGPL3.0-or-later
*/
/**
- * @author Bartlomiej Polot
* @file cadet/cadet_protocol.h
+ * @brief P2P messages used by CADET
+ * @author Bartlomiej Polot
+ * @author Christian Grothoff
*/
#ifndef CADET_PROTOCOL_H_
#define CADET_PROTOCOL_H_
+/**
+ * At best, enable when debugging #5328!
+ */
+#define DEBUG_KX 0
+#if DEBUG_KX
+#warning NEVER run this in production! KX debugging is on!
+#endif
+
#include "platform.h"
#include "gnunet_util_lib.h"
#include "cadet.h"
GNUNET_NETWORK_STRUCT_BEGIN
+
+/******************************************************************************/
+/***************************** CONNECTION **********************************/
+/******************************************************************************/
+
+
/**
* Message for cadet connection creation.
*/
-struct GNUNET_CADET_ConnectionCreate
+struct GNUNET_CADET_ConnectionCreateMessage
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE
- *
- * Size: sizeof (struct GNUNET_CADET_ConnectionCreate) +
- * path_length * sizeof (struct GNUNET_PeerIdentity)
- */
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE
+ *
+ * Size: sizeof (struct GNUNET_CADET_ConnectionCreateMessage) +
+ * path_length * sizeof (struct GNUNET_PeerIdentity)
+ */
struct GNUNET_MessageHeader header;
- /**
- * ID of the connection
- */
- struct GNUNET_CADET_Hash cid;
+ /**
+ * Connection options in network byte order.
+ * #GNUNET_CADET_OPTION_DEFAULT for buffered;
+ * #GNUNET_CADET_OPTION_NOBUFFER for unbuffered.
+ * Other flags are ignored and should not be set at this level.
+ */
+ uint32_t options GNUNET_PACKED;
- /**
- * path_length structs defining the *whole* path from the origin [0] to the
- * final destination [path_length-1].
- */
+ /**
+ * ID of the connection
+ */
+ struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
+
+ /**
+ * path_length structs defining the *whole* path from the origin [0] to the
+ * final destination [path_length-1].
+ */
/* struct GNUNET_PeerIdentity peers[path_length]; */
};
+
/**
* Message for ack'ing a connection
*/
-struct GNUNET_CADET_ConnectionACK
+struct GNUNET_CADET_ConnectionCreateAckMessage
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_CONNECTION_ACK
- */
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE_ACK
+ */
struct GNUNET_MessageHeader header;
- /**
- * ID of the connection.
- */
- struct GNUNET_CADET_Hash cid;
+ /**
+ * For alignment.
+ */
+ uint32_t reserved GNUNET_PACKED;
+
+ /**
+ * ID of the connection.
+ */
+ struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
};
/**
- * Message for encapsulation of a Key eXchange message in a connection.
+ * Message for notifying a disconnection in a path
*/
-struct GNUNET_CADET_KX
+struct GNUNET_CADET_ConnectionBrokenMessage
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_KX.
- */
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_BROKEN.
+ */
struct GNUNET_MessageHeader header;
- /**
- * ID of the connection.
- */
- struct GNUNET_CADET_Hash cid;
+ /**
+ * For alignment.
+ */
+ uint32_t reserved GNUNET_PACKED;
+
+ /**
+ * ID of the connection.
+ */
+ struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
- /* Specific KX message follows. */
+ /**
+ * ID of the endpoint
+ */
+ struct GNUNET_PeerIdentity peer1;
+
+ /**
+ * ID of the endpoint
+ */
+ struct GNUNET_PeerIdentity peer2;
};
/**
- * Message transmitted with the signed ephemeral key of a peer. The
- * session key is then derived from the two ephemeral keys (ECDHE).
- *
- * As far as possible, same as CORE's EphemeralKeyMessage.
+ * Message to destroy a connection.
*/
-struct GNUNET_CADET_KX_Ephemeral
+struct GNUNET_CADET_ConnectionDestroyMessage
{
-
/**
- * Message type is GNUNET_MESSAGE_TYPE_CADET_KX_EPHEMERAL.
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_DESTROY
*/
struct GNUNET_MessageHeader header;
/**
- * Status of the sender (should be in "enum PeerStateMachine"), nbo.
+ * For alignment.
*/
- int32_t sender_status GNUNET_PACKED;
+ uint32_t reserved GNUNET_PACKED;
/**
- * An ECC signature of the 'origin' asserting the validity of
- * the given ephemeral key.
+ * ID of the connection.
*/
- struct GNUNET_CRYPTO_EddsaSignature signature;
+ struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
+};
- /**
- * Information about what is being signed.
- */
- struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
- /**
- * At what time was this key created (beginning of validity).
- */
- struct GNUNET_TIME_AbsoluteNBO creation_time;
+/******************************************************************************/
+/******************************* TUNNEL ***********************************/
+/******************************************************************************/
+/**
+ * Unique identifier (counter) for an encrypted message in a channel.
+ * Used to match #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_HOP_BY_HOP_ENCRYPTED_ACK
+ * and #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED_POLL messages
+ * against the respective #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED
+ * messages.
+ */
+struct CadetEncryptedMessageIdentifier
+{
/**
- * When does the given ephemeral key expire (end of validity).
+ * This number is incremented by one per message. It may wrap around.
+ * In network byte order.
*/
- struct GNUNET_TIME_AbsoluteNBO expiration_time;
+ uint32_t pid GNUNET_PACKED;
+};
+
+
+/**
+ * Flags to be used in GNUNET_CADET_KX.
+ */
+enum GNUNET_CADET_KX_Flags {
/**
- * Ephemeral public ECC key (always for NIST P-521) encoded in a format suitable
- * for network transmission as created using 'gcry_sexp_sprint'.
+ * Should the peer reply with its KX details?
*/
- struct GNUNET_CRYPTO_EcdhePublicKey ephemeral_key;
+ GNUNET_CADET_KX_FLAG_NONE = 0,
/**
- * Public key of the signing peer (persistent version, not the ephemeral public key).
+ * The peer should reply with its KX details?
*/
- struct GNUNET_PeerIdentity origin_identity;
+ GNUNET_CADET_KX_FLAG_FORCE_REPLY = 1
};
/**
- * We're sending an (encrypted) PING to the other peer to check if he
- * can decrypt. The other peer should respond with a PONG with the
- * same content, except this time encrypted with the receiver's key.
+ * Message for a Key eXchange for a tunnel.
*/
-struct GNUNET_CADET_KX_Ping
+struct GNUNET_CADET_TunnelKeyExchangeMessage
{
/**
- * Message type is GNUNET_MESSAGE_TYPE_CADET_KX_PING.
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_KX or
+ * #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_KX_AUTH as part
+ * of `struct GNUNET_CADET_TunnelKeyExchangeAuthMessage`.
*/
struct GNUNET_MessageHeader header;
/**
- * Seed for the IV
+ * Flags for the key exchange in NBO, based on
+ * `enum GNUNET_CADET_KX_Flags`.
*/
- uint32_t iv GNUNET_PACKED;
+ uint32_t flags GNUNET_PACKED;
/**
- * Intended target of the PING, used primarily to check
- * that decryption actually worked.
+ * ID of the connection.
*/
- struct GNUNET_PeerIdentity target;
+ struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
/**
- * Random number chosen to make reply harder.
+ * Sender's ephemeral public ECC key encoded in a
+ * format suitable for network transmission, as created
+ * using 'gcry_sexp_sprint'.
*/
- uint32_t nonce GNUNET_PACKED;
-};
-
+ struct GNUNET_CRYPTO_EcdhePublicKey ephemeral_key;
-/**
- * Response to a PING. Includes data from the original PING.
- */
-struct GNUNET_CADET_KX_Pong
-{
+#if DEBUG_KX
/**
- * Message type is GNUNET_MESSAGE_TYPE_CADET_KX_PONG.
+ * Sender's ephemeral public ECC key encoded in a
+ * format suitable for network transmission, as created
+ * using 'gcry_sexp_sprint'.
*/
- struct GNUNET_MessageHeader header;
+ struct GNUNET_CRYPTO_EcdhePrivateKey ephemeral_key_XXX; // for debugging KX-crypto!
/**
- * Seed for the IV
+ * Sender's ephemeral public ECC key encoded in a
+ * format suitable for network transmission, as created
+ * using 'gcry_sexp_sprint'.
*/
- uint32_t iv GNUNET_PACKED;
+ struct GNUNET_CRYPTO_EddsaPrivateKey private_key_XXX; // for debugging KX-crypto!
+#endif
/**
- * Same nonce as in the reve.
+ * Sender's next ephemeral public ECC key encoded in a
+ * format suitable for network transmission, as created
+ * using 'gcry_sexp_sprint'.
*/
- uint32_t nonce GNUNET_PACKED;
+ struct GNUNET_CRYPTO_EcdhePublicKey ratchet_key;
+
};
/**
- * Tunnel(ed) message.
+ * Message for a Key eXchange for a tunnel, with authentication.
+ * Used as a response to the initial KX as well as for rekeying.
*/
-struct GNUNET_CADET_Encrypted
+struct GNUNET_CADET_TunnelKeyExchangeAuthMessage
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_ENCRYPTED
- */
- struct GNUNET_MessageHeader header;
/**
- * ID of the connection.
+ * Message header with key material.
*/
- struct GNUNET_CADET_Hash cid;
+ struct GNUNET_CADET_TunnelKeyExchangeMessage kx;
+#if DEBUG_KX
/**
- * ID of the packet (hop by hop).
+ * Received ephemeral public ECC key encoded in a
+ * format suitable for network transmission, as created
+ * using 'gcry_sexp_sprint'.
*/
- uint32_t pid GNUNET_PACKED;
+ struct GNUNET_CRYPTO_EcdhePublicKey r_ephemeral_key_XXX; // for debugging KX-crypto!
+#endif
/**
- * Number of hops to live.
+ * KDF-proof that sender could compute the 3-DH, used in lieu of a
+ * signature or payload data.
*/
- uint32_t ttl GNUNET_PACKED;
+ struct GNUNET_HashCode auth;
+
+};
+
+
+/**
+ * Encrypted axolotl header with numbers that identify which
+ * keys in which ratchet are to be used to decrypt the body.
+ */
+struct GNUNET_CADET_AxHeader
+{
/**
- * Initialization Vector for payload encryption.
+ * Number of messages sent with the current ratchet key.
*/
- uint32_t iv GNUNET_PACKED;
+ uint32_t Ns GNUNET_PACKED;
/**
- * MAC of the encrypted message, used to verify message integrity.
- * Everything after this value will be encrypted and authenticated.
+ * Number of messages sent with the previous ratchet key.
*/
- struct GNUNET_CADET_Hash hmac;
+ uint32_t PNs GNUNET_PACKED;
/**
- * Encrypted content follows.
+ * Current ratchet key.
*/
+ struct GNUNET_CRYPTO_EcdhePublicKey DHRs;
+
};
/**
- * Message to create a Channel.
+ * Axolotl-encrypted tunnel message with application payload.
*/
-struct GNUNET_CADET_ChannelCreate
+struct GNUNET_CADET_TunnelEncryptedMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_CADET_CHANNEL_CREATE
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED
*/
struct GNUNET_MessageHeader header;
/**
- * ID of the channel
+ * Reserved, for alignment.
*/
- CADET_ChannelNumber chid GNUNET_PACKED;
+ uint32_t reserved GNUNET_PACKED;
/**
- * Destination port.
+ * ID of the connection.
*/
- uint32_t port GNUNET_PACKED;
+ struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
/**
- * Channel options.
+ * MAC of the encrypted message, used to verify message integrity.
+ * Everything after this value will be encrypted with the header key
+ * and authenticated.
*/
- uint32_t opt GNUNET_PACKED;
-};
-
+ struct GNUNET_ShortHashCode hmac;
-/**
- * Message to manage a Channel (ACK, NACK, Destroy).
- */
-struct GNUNET_CADET_ChannelManage
-{
/**
- * Type: GNUNET_MESSAGE_TYPE_CADET_CHANNEL_{ACK|NACK|DESTROY}
+ * Axolotl-header that specifies which keys to use in which ratchet
+ * to decrypt the body that follows.
*/
- struct GNUNET_MessageHeader header;
+ struct GNUNET_CADET_AxHeader ax_header;
/**
- * ID of the channel
+ * Encrypted content follows.
*/
- CADET_ChannelNumber chid GNUNET_PACKED;
};
+/******************************************************************************/
+/******************************* CHANNEL ***********************************/
+/******************************************************************************/
+
+
/**
- * Message for cadet data traffic.
+ * Message to create a Channel.
*/
-struct GNUNET_CADET_Data
+struct GNUNET_CADET_ChannelOpenMessage
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_UNICAST,
- * GNUNET_MESSAGE_TYPE_CADET_TO_ORIGIN
- */
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN
+ */
struct GNUNET_MessageHeader header;
- /**
- * Unique ID of the payload message
- */
- uint32_t mid GNUNET_PACKED;
+ /**
+ * Channel options.
+ */
+ uint32_t opt GNUNET_PACKED;
- /**
- * ID of the channel
- */
- CADET_ChannelNumber chid GNUNET_PACKED;
+ /**
+ * Hash of destination port and listener.
+ */
+ struct GNUNET_HashCode h_port;
- /**
- * Payload follows
- */
+ /**
+ * ID of the channel within the tunnel.
+ */
+ struct GNUNET_CADET_ChannelTunnelNumber ctn;
};
/**
- * Message to acknowledge end-to-end data.
+ * Message to acknowledge opening a channel of type
+ * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK.
*/
-struct GNUNET_CADET_DataACK
+struct GNUNET_CADET_ChannelOpenAckMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_CADET_DATA_ACK
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK
*/
struct GNUNET_MessageHeader header;
/**
- * ID of the channel
+ * For alignment.
*/
- CADET_ChannelNumber chid GNUNET_PACKED;
+ uint32_t reserved GNUNET_PACKED;
/**
- * Bitfield of already-received newer messages
- * pid + 1 @ LSB
- * pid + 64 @ MSB
+ * ID of the channel
*/
- uint64_t futures GNUNET_PACKED;
+ struct GNUNET_CADET_ChannelTunnelNumber ctn;
/**
- * Last message ID received.
+ * Port number of the channel, used to prove to the
+ * initiator that the receiver knows the port.
*/
- uint32_t mid GNUNET_PACKED;
+ struct GNUNET_HashCode port;
};
/**
- * Message to acknowledge cadet encrypted traffic.
+ * Message to destroy a channel of type
+ * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_DESTROY.
*/
-struct GNUNET_CADET_ACK
+struct GNUNET_CADET_ChannelDestroyMessage
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_ACK
- */
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_DESTROY
+ */
struct GNUNET_MessageHeader header;
- /**
- * Maximum packet ID authorized.
- */
- uint32_t ack GNUNET_PACKED;
+ /**
+ * For alignment.
+ */
+ uint32_t reserved GNUNET_PACKED;
- /**
- * ID of the connection.
- */
- struct GNUNET_CADET_Hash cid;
+ /**
+ * ID of the channel
+ */
+ struct GNUNET_CADET_ChannelTunnelNumber ctn;
};
/**
- * Message to query a peer about its Flow Control status regarding a tunnel.
+ * Number used to uniquely identify messages in a CADET Channel.
*/
-struct GNUNET_CADET_Poll
+struct ChannelMessageIdentifier
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_POLL
- */
- struct GNUNET_MessageHeader header;
-
- /**
- * Last packet sent.
- */
- uint32_t pid GNUNET_PACKED;
-
- /**
- * ID of the connection.
- */
- struct GNUNET_CADET_Hash cid;
-
+ /**
+ * Unique ID of the message, cycles around, in NBO.
+ */
+ uint32_t mid GNUNET_PACKED;
};
/**
- * Message for notifying a disconnection in a path
+ * Message for cadet data traffic.
*/
-struct GNUNET_CADET_ConnectionBroken
+struct GNUNET_CADET_ChannelAppDataMessage
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_CONNECTION_BROKEN
- */
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_APP_DATA.
+ */
struct GNUNET_MessageHeader header;
- /**
- * ID of the connection.
- */
- struct GNUNET_CADET_Hash cid;
+ /**
+ * Unique ID of the payload message.
+ */
+ struct ChannelMessageIdentifier mid;
- /**
- * ID of the endpoint
- */
- struct GNUNET_PeerIdentity peer1;
+ /**
+ * ID of the channel
+ */
+ struct GNUNET_CADET_ChannelTunnelNumber ctn;
- /**
- * ID of the endpoint
- */
- struct GNUNET_PeerIdentity peer2;
+ /**
+ * Payload follows
+ */
};
/**
- * Message to destroy a connection.
+ * Message to acknowledge end-to-end data.
*/
-struct GNUNET_CADET_ConnectionDestroy
+struct GNUNET_CADET_ChannelDataAckMessage
{
- /**
- * Type: GNUNET_MESSAGE_TYPE_CADET_CONNECTION_DESTROY
- */
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_APP_DATA_ACK
+ */
struct GNUNET_MessageHeader header;
- /**
- * ID of the connection.
- */
- struct GNUNET_CADET_Hash cid;
+ /**
+ * ID of the channel
+ */
+ struct GNUNET_CADET_ChannelTunnelNumber ctn;
+
+ /**
+ * Bitfield of already-received newer messages. Note that bit 0
+ * corresponds to @e mid + 1.
+ *
+ * pid + 0 @ LSB
+ * pid + 63 @ MSB
+ */
+ uint64_t futures GNUNET_PACKED;
+
+ /**
+ * Next message ID expected.
+ */
+ struct ChannelMessageIdentifier mid;
};