he.h

Go to the documentation of this file.

/* *
 * Lightway Core
 * Copyright (C) 2021 Express VPN International Ltd.
 *
 * This program 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 2
 * of the License, or (at your option) any later version.
 *
 * This program 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.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef HE
#define HE

// Needed headers
#include <stdbool.h>
#include <stdint.h>

// Network headers
#include "he_plugin.h"

// WolfSSL
#ifndef WOLFSSL_USER_SETTINGS
#include <wolfssl/options.h>
#endif
#include <wolfssl/ssl.h>
#include <wolfssl/wolfcrypt/settings.h>
#include <wolfssl/wolfcrypt/random.h>

// Helper macros

#define HE_MAX_WIRE_MTU 1500
#define HE_MAX_MTU 1350
#define HE_MAX_MTU_STR "1350"

#define HE_WIRE_MINIMUM_PROTOCOL_MAJOR_VERSION 1
#define HE_WIRE_MINIMUM_PROTOCOL_MINOR_VERSION 0
#define HE_WIRE_MAXIMUM_PROTOCOL_MAJOR_VERSION 1
#define HE_WIRE_MAXIMUM_PROTOCOL_MINOR_VERSION 1

#ifdef __GNUC__
#define HE_DEPRECATED(name) __attribute__((deprecated("use " #name " instead")))
#elif defined(_MSC_VER)
#define HE_DEPRECATED(name) __declspec(deprecated("use " #name " instead"))
#endif

#define HE_CONFIG_TEXT_FIELD_LENGTH 50
#define HE_MAX_IPV4_STRING_LENGTH 24

typedef enum he_return_code {
  HE_SUCCESS = 0,
  HE_ERR_STRING_TOO_LONG = -1,
  HE_ERR_EMPTY_STRING = -2,
  HE_ERR_INVALID_CONN_STATE = -3,
  HE_ERR_NULL_POINTER = -4,
  HE_ERR_EMPTY_PACKET = -5,
  HE_ERR_PACKET_TOO_SMALL = -6,
  HE_ERR_ZERO_SIZE = -7,
  HE_ERR_NEGATIVE_NUMBER = -8,
  HE_ERR_INIT_FAILED = -9,
  HE_ERR_NO_MEMORY = -10,
  HE_ERR_NOT_HE_PACKET = -11,
  HE_ERR_SSL_BAD_FILETYPE = -12,
  HE_ERR_SSL_BAD_FILE = -13,
  HE_ERR_SSL_OUT_OF_MEMORY = -14,
  HE_ERR_SSL_ASN_INPUT = -15,
  HE_ERR_SSL_BUFFER = -16,
  HE_ERR_SSL_CERT = -17,
  HE_ERR_SSL_ERROR = -18,
  HE_ERR_CONF_USERNAME_NOT_SET = -19,
  HE_ERR_CONF_PASSWORD_NOT_SET = -20,
  HE_ERR_CONF_CA_NOT_SET = -21,
  HE_ERR_CONF_MTU_NOT_SET = -22,
  HE_WANT_READ = -23,
  HE_WANT_WRITE = -24,
  HE_ERR_CONF_OUTSIDE_WRITE_CB_NOT_SET = -25,
  HE_ERR_CONNECT_FAILED = -26,
  HE_CONNECTION_TIMED_OUT = -27,
  HE_ERR_NOT_CONNECTED = -28,
  HE_ERR_UNSUPPORTED_PACKET_TYPE = -29,
  HE_ERR_CONNECTION_WAS_CLOSED = -30,
  HE_ERR_BAD_PACKET = -31,
  HE_ERR_CALLBACK_FAILED = -32,
  HE_ERR_FAILED = -33,
  HE_ERR_SERVER_DN_MISMATCH = -34,
  HE_ERR_CANNOT_VERIFY_SERVER_CERT = -35,
  HE_ERR_NEVER_CONNECTED = -36,
  HE_ERR_INVALID_MTU_SIZE = -37,
  HE_ERR_CLEANUP_FAILED = -38,
  HE_ERR_REJECTED_SESSION = -39,
  HE_ERR_ACCESS_DENIED = -40,
  HE_ERR_PACKET_TOO_LARGE = -41,
  HE_ERR_INACTIVITY_TIMEOUT = -42,
  HE_ERR_POINTER_WOULD_OVERFLOW = -43,
  HE_ERR_INVALID_CONNECTION_TYPE = -46,
  HE_ERR_RNG_FAILURE = -47,
  HE_ERR_CONF_AUTH_CB_NOT_SET = -48,
  HE_ERR_PLUGIN_DROP = -49,
  HE_ERR_UNKNOWN_SESSION = -50,
  HE_ERR_SSL_ERROR_NONFATAL = -51,
  HE_ERR_INCORRECT_PROTOCOL_VERSION = -52,
  HE_ERR_CONF_CONFLICTING_AUTH_METHODS = -53,
  HE_ERR_ACCESS_DENIED_NO_AUTH_BUF_HANDLER = -54,
  HE_ERR_ACCESS_DENIED_NO_AUTH_USERPASS_HANDLER = -55,
} he_return_code_t;

typedef enum he_conn_state {
  HE_STATE_NONE = 0,
  HE_STATE_DISCONNECTED = 1,
  HE_STATE_CONNECTING = 2,
  HE_STATE_DISCONNECTING = 4,
  HE_STATE_AUTHENTICATING = 5,
  HE_STATE_LINK_UP = 6,
  HE_STATE_ONLINE = 7,
  HE_STATE_CONFIGURING = 8,
} he_conn_state_t;

typedef enum he_conn_event {
  HE_EVENT_FIRST_MESSAGE_RECEIVED = 1,
  HE_EVENT_PONG = 2,
  HE_EVENT_REJECTED_FRAGMENTED_PACKETS_SENT_BY_HOST = 3,
  HE_EVENT_SECURE_RENEGOTIATION_STARTED = 4,
  HE_EVENT_SECURE_RENEGOTIATION_COMPLETED = 5,
  HE_EVENT_PENDING_SESSION_ACKNOWLEDGED = 6,
} he_conn_event_t;

typedef enum he_padding_type {
  HE_PADDING_NONE = 0,
  HE_PADDING_FULL = 1,
  HE_PADDING_450 = 2
} he_padding_type_t;

typedef enum he_connection_type {
  HE_CONNECTION_TYPE_DATAGRAM = 0,
  HE_CONNECTION_TYPE_STREAM = 1
} he_connection_type_t;

typedef struct he_ssl_ctx he_ssl_ctx_t;
typedef struct he_conn he_conn_t;
typedef struct he_plugin_chain he_plugin_chain_t;
typedef struct he_network_config_ipv4 he_network_config_ipv4_t;

typedef struct he_client {
  he_ssl_ctx_t *ssl_ctx;
  he_conn_t *conn;
  he_plugin_chain_t *inside_plugins;
  he_plugin_chain_t *outside_plugins;
} he_client_t;

typedef void *(*he_malloc_t)(size_t size);
typedef void *(*he_calloc_t)(size_t nmemb, size_t size);
typedef void *(*he_realloc_t)(void *ptr, size_t size);
typedef void (*he_free_t)(void *ptr);

typedef he_return_code_t (*he_state_change_cb_t)(he_conn_t *conn, he_conn_state_t new_state,
                                                 void *context);

typedef he_return_code_t (*he_inside_write_cb_t)(he_conn_t *conn, uint8_t *packet, size_t length,
                                                 void *context);

typedef he_return_code_t (*he_outside_write_cb_t)(he_conn_t *conn, uint8_t *packet, size_t length,
                                                  void *context);

typedef he_return_code_t (*he_network_config_ipv4_cb_t)(he_conn_t *conn,
                                                        he_network_config_ipv4_t *config,
                                                        void *context);

typedef he_return_code_t (*he_event_cb_t)(he_conn_t *conn, he_conn_event_t event, void *context);

typedef he_return_code_t (*he_nudge_time_cb_t)(he_conn_t *conn, int timeout, void *context);

typedef bool (*he_auth_cb_t)(he_conn_t *conn, char const *username, char const *password,
                             void *context);

typedef bool (*he_auth_buf_cb_t)(he_conn_t *conn, uint8_t auth_type, uint8_t *buffer,
                                 uint16_t length, void *context);

typedef he_return_code_t (*he_populate_network_config_ipv4_cb_t)(he_conn_t *conn,
                                                                 he_network_config_ipv4_t *config,
                                                                 void *context);

typedef struct he_packet_buffer {
  // Buffer has data
  bool has_packet;
  // Size of packet
  int packet_size;
  // The packet itself
  uint8_t packet[HE_MAX_WIRE_MTU];
} he_packet_buffer_t;

// Note that this is *not* intended for use on the wire; this struct is part of
// the internal API and just conveniently connects these two numbers together.
typedef struct he_version_info {
  // Version of the wire protocol
  uint8_t major_version;
  uint8_t minor_version;
} he_version_info_t;

struct he_ssl_ctx {
  char server_dn[HE_CONFIG_TEXT_FIELD_LENGTH + 1];
  bool use_chacha;
  // Location of Client CA certificate in PEM format
  uint8_t *cert_buffer;
  size_t cert_buffer_size;

  // Server certificate location
  char const *server_cert;
  // Server certificate key location
  char const *server_key;

  he_connection_type_t connection_type;
  he_state_change_cb_t state_change_cb;
  he_inside_write_cb_t inside_write_cb;
  he_outside_write_cb_t outside_write_cb;
  he_network_config_ipv4_cb_t network_config_ipv4_cb;
  he_nudge_time_cb_t nudge_time_cb;
  // Callback for events
  he_event_cb_t event_cb;
  // Callbacks for auth (server-only)
  he_auth_cb_t auth_cb;
  he_auth_buf_cb_t auth_buf_cb;
  // Callback for populating the network config (server-only)
  he_populate_network_config_ipv4_cb_t populate_network_config_ipv4_cb;
  bool disable_roaming_connections;
  he_padding_type_t padding_type;
  bool use_aggressive_mode;

  WOLFSSL_CTX *wolf_ctx;
  // Random number generator
  RNG wolf_rng;

  he_version_info_t minimum_supported_version;
  he_version_info_t maximum_supported_version;
};

struct he_conn {
  bool is_server;

  he_conn_state_t state;

  uint8_t *incoming_data;
  size_t incoming_data_length;
  // WolfSSL stuff
  WOLFSSL *wolf_ssl;
  int wolf_timeout;
  uint8_t write_buffer[HE_MAX_WIRE_MTU];
  bool packet_seen;
  uint64_t session_id;
  uint64_t pending_session_id;
  he_packet_buffer_t read_packet;
  bool first_message_received;
  size_t incoming_data_left_to_read;
  uint8_t *incoming_data_read_offset_ptr;

  bool renegotiation_in_progress;
  bool renegotiation_due;

  bool is_nudge_timer_running;

  he_plugin_chain_t *inside_plugins;
  he_plugin_chain_t *outside_plugins;

  uint8_t auth_type;

  char username[HE_CONFIG_TEXT_FIELD_LENGTH + 1];
  char password[HE_CONFIG_TEXT_FIELD_LENGTH + 1];

  uint8_t auth_buffer[HE_MAX_MTU];
  uint16_t auth_buffer_length;

  int outside_mtu;

  void *data;

  // Data from the SSL contxt config copied here to make this hermetic
  bool disable_roaming_connections;
  he_padding_type_t padding_type;
  bool use_aggressive_mode;
  he_connection_type_t connection_type;

  he_state_change_cb_t state_change_cb;
  he_nudge_time_cb_t nudge_time_cb;
  he_inside_write_cb_t inside_write_cb;
  he_outside_write_cb_t outside_write_cb;
  he_network_config_ipv4_cb_t network_config_ipv4_cb;
  // Callback for events
  he_event_cb_t event_cb;
  // Callback for auth (server-only)
  he_auth_cb_t auth_cb;
  he_auth_buf_cb_t auth_buf_cb;
  // Callback for populating the network config (server-only)
  he_populate_network_config_ipv4_cb_t populate_network_config_ipv4_cb;

  he_version_info_t protocol_version;

  RNG wolf_rng;
};

struct he_plugin_chain {
  plugin_struct_t *plugin;
  he_plugin_chain_t *next;
};

// MSG IDs
typedef enum msg_ids {
  HE_MSGID_NOOP = 1,
  HE_MSGID_PING = 2,
  HE_MSGID_PONG = 3,
  HE_MSGID_AUTH = 4,
  HE_MSGID_DATA = 5,
  HE_MSGID_CONFIG_IPV4 = 6,
  HE_MSGID_AUTH_RESPONSE = 7,
  HE_MSGID_AUTH_RESPONSE_WITH_CONFIG = 8,
  HE_MSGID_EXTENSION = 9,
  HE_MSGID_SESSION_REQUEST = 10,
  HE_MSGID_SESSION_RESPONSE = 11,
  HE_MSGID_GOODBYE = 12,
  HE_MSGID_DEPRECATED_13 = 13
} msg_ids_t;

typedef enum he_auth_type { HE_AUTH_TYPE_USERPASS = 1 } he_auth_type_t;

typedef struct he_network_config_ipv4 {
  char local_ip[HE_MAX_IPV4_STRING_LENGTH];
  char peer_ip[HE_MAX_IPV4_STRING_LENGTH];
  char dns_ip[HE_MAX_IPV4_STRING_LENGTH];
  int mtu;
} he_network_config_ipv4_t;

#pragma pack(1)

typedef struct he_wire_hdr {
  // First two bytes to contain the 'H' and 'e'
  char he[2];
  // Version of the wire protocol
  uint8_t major_version;
  uint8_t minor_version;
  // Request aggressive mode
  uint8_t aggressive_mode;
  // Three bytes reserved for future use
  uint8_t reserved[3];
  // 64 bit session identifier
  uint64_t session;
} he_wire_hdr_t;

typedef struct he_msg_hdr {
  uint8_t msgid;
} he_msg_hdr_t;

typedef struct he_msg_ping {
  he_msg_hdr_t msg_header;
  uint32_t payload;
} he_msg_ping_t;

typedef struct he_msg_pong {
  he_msg_hdr_t msg_header;
  uint32_t payload;
} he_msg_pong_t;

typedef struct he_msg_auth_hdr {
  he_msg_hdr_t msg_header;
  uint8_t auth_type;
} he_msg_auth_hdr_t;

typedef struct he_msg_auth {
  he_msg_auth_hdr_t header;
  uint8_t username_length;
  uint8_t password_length;
  char username[HE_CONFIG_TEXT_FIELD_LENGTH];
  char password[HE_CONFIG_TEXT_FIELD_LENGTH];
} he_msg_auth_t;

typedef struct he_msg_auth_buf {
  he_msg_auth_hdr_t header;
  uint16_t buffer_length;
  uint8_t buffer[];
} he_msg_auth_buf_t;

typedef struct he_msg_config_ipv4 {
  he_msg_hdr_t msg_header;
  char local_ip[HE_MAX_IPV4_STRING_LENGTH];
  char peer_ip[HE_MAX_IPV4_STRING_LENGTH];
  char dns_ip[HE_MAX_IPV4_STRING_LENGTH];
  char mtu[HE_MAX_IPV4_STRING_LENGTH];
  uint64_t session;
} he_msg_config_ipv4_t;

typedef struct he_msg_data {
  he_msg_hdr_t msg_header;
  uint16_t length;
} he_msg_data_t;

typedef struct he_deprecated_msg_13 {
  he_msg_hdr_t msg_header;
  uint16_t length;
  uint16_t _unused;
} he_deprecated_msg_13_t;

#define HE_AUTH_STATUS_SUCCESS 0
#define HE_AUTH_STATUS_FAILURE 1

typedef struct he_msg_auth_response {
  he_msg_hdr_t msg_header;
  uint8_t status;
  uint8_t status_msg_length;
  char status_msg[HE_CONFIG_TEXT_FIELD_LENGTH];
} he_msg_auth_response_t;

typedef struct he_msg_session_request {
  he_msg_hdr_t msg_header;
} he_msg_session_request_t;

typedef struct he_msg_session_response {
  he_msg_hdr_t msg_header;
  uint64_t session;
} he_msg_session_response_t;

typedef struct he_msg_goodbye {
  he_msg_hdr_t msg_header;
} he_msg_goodbye_t;

#define HE_EXT_TYPE_REQUEST 1
#define HE_EXT_TYPE_RESPONSE 2

#define HE_EXT_ID_BLOCK_DNS_OVER_TLS 1

#define HE_EXT_PAYLOAD_TYPE_MSGPACK 1
#define HE_EXT_PAYLOAD_TYPE_BINARY 2
#define HE_EXT_PAYLOAD_TYPE_INT16 3

typedef struct he_msg_extension {
  he_msg_hdr_t msg_header;
  uint16_t extension_id;
  uint8_t msg_type;
  uint8_t payload_type;
  uint16_t payload_length;
  uint8_t data;

} he_msg_extension_t;

#pragma pack()

static const uint64_t HE_PACKET_SESSION_REJECT = 0xFFFFFFFFFFFFFFFF;
static const uint64_t HE_PACKET_SESSION_EMPTY = 0x0000000000000000;

// D/TLS headers + AES crypto fields
#define HE_WOLF_MAX_HEADER_SIZE 37
#define HE_IPV4_HEADER_SIZE 20
#define HE_TCP_HEADER_SIZE 20
#define HE_UDP_HEADER_SIZE 8
// Add a gap to avoid normal ADSL / PPPoX type overhead
#define HE_HEADER_SAFE_GAP 28
static const size_t HE_PACKET_OVERHEAD = sizeof(he_deprecated_msg_13_t) + sizeof(he_wire_hdr_t) +
                                         HE_IPV4_HEADER_SIZE + HE_UDP_HEADER_SIZE +
                                         HE_WOLF_MAX_HEADER_SIZE + HE_HEADER_SAFE_GAP;

#define HE_MSS_OVERHEAD (HE_IPV4_HEADER_SIZE + HE_UDP_HEADER_SIZE)

#endif