scion.h

Go to the documentation of this file.

// Copyright 2024 ETH Zurich
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
 
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdbool.h>
#include <stdint.h>
#include <sys/socket.h>
#include <sys/time.h>
 
#define SCION_SO_DEBUG 200
 
#define SCION_FETCH_OPT_DEBUG 1
 
#define SCION_IA_STRLEN 21
 
enum scion_error {
    SCION_ERR_GENERIC = -1,
    SCION_ERR_MEM_ALLOC_FAIL = -2,
    SCION_ERR_NO_PATHS = -3,
    SCION_ERR_BUF_TOO_SMALL = -4,
    SCION_ERR_ADDR_FAMILY_UNKNOWN = -5,
    SCION_ERR_MAX_HDR_LEN_EXCEEDED = -6,
    SCION_ERR_FILE_NOT_FOUND = -7,
    SCION_ERR_TOPOLOGY_INVALID = -8,
    SCION_ERR_ADDR_FAMILY_MISMATCH = -9,
    SCION_ERR_NETWORK_ADDR_FAMILY_MISMATCH = -10,
    SCION_ERR_PROTO_UNKNOWN = -11,
    SCION_ERR_NOT_CONNECTED = -12,
    SCION_ERR_DST_MISMATCH = -13,
    SCION_ERR_INVALID_ISD_AS_STR = -14,
    SCION_ERR_WOULD_BLOCK = -15,
    SCION_ERR_ADDR_INVALID = -16,
    SCION_ERR_ALREADY_BOUND = -17,
    SCION_ERR_FLAG_NOT_IMPLEMENTED = -18,
    SCION_ERR_FLAG_NOT_SUPPORTED = -19,
    SCION_ERR_SEND_FAIL = -20,
    SCION_ERR_RECV_FAIL = -21,
    SCION_ERR_ADDR_IN_USE = -22,
    SCION_ERR_ADDR_NOT_AVAILABLE = -23,
    SCION_ERR_OUTPUT_QUEUE_FULL = -24,
    SCION_ERR_SOCK_OPT_INVALID = -25,
    SCION_ERR_ADDR_BUF_TOO_SMALL = -26,
    SCION_ERR_PATH_EXPIRED = -27,
    SCION_ERR_NOT_BOUND = -28,
    SCION_ERR_NETWORK_UNKNOWN = -29,
    SCION_ERR_MSG_TOO_LARGE = -30,
    SCION_ERR_SRC_ADDR_UNKNOWN = -31,
    SCION_ERR_BOOTSTRAPPING_FAIL = -32,
    SCION_ERR_SOCK_TYPE_UNKNOWN = -33,
    SCION_ERR_PROTO_INCOMPATIBLE = -34,
    // Internal errors
    SCION_ERR_NOT_ENOUGH_DATA = -201,
    SCION_ERR_PACKET_FIELD_INVALID = -202,
    SCION_ERR_GRPC_FAIL = -203,
    SCION_ERR_META_HDR_INVALID = -204,
    SCION_ERR_PATH_TYPE_INVALID = -205,
    SCION_ERR_SCMP_CODE_INVALID = -206,
};
 
char *scion_strerror(int err);
 
enum scion_addr_family {
    SCION_AF_INET = AF_INET,
    SCION_AF_INET6 = AF_INET6
};
 
enum scion_sock_type {
    SCION_SOCK_DGRAM = SOCK_DGRAM,
    SCION_SOCK_RAW = SOCK_RAW,
};
 
enum scion_proto {
    SCION_PROTO_UDP = 17,
    SCION_PROTO_SCMP = 202
};
 
typedef uint64_t scion_ia;
 
int scion_ia_parse(const char *str, size_t len, scion_ia *ia);
 
int scion_ia_str(scion_ia ia, char *buf, size_t buflen);
 
void scion_ia_print(scion_ia ia);
 
struct scion_topology;
 
int scion_topology_from_file(struct scion_topology **topology, const char *path);
 
scion_ia scion_topology_get_local_ia(struct scion_topology *topo);
 
void scion_topology_free(struct scion_topology *topo);
 
int scion_bootstrap(const char *topology_path);
 
struct scion_network;
 
int scion_network(struct scion_network **net, struct scion_topology *topology);
 
void scion_network_free(struct scion_network *net);
 
enum scion_addr_family scion_network_get_local_addr_family(struct scion_network *net);
 
struct scion_path;
 
int scion_path_reverse(struct scion_path *path);
 
size_t scion_path_get_numhops(const struct scion_path *path);
 
void scion_path_free(struct scion_path *path);
 
#define SCION_PATH_METADATA_LATENCY_IS_UNSET(latency) (latency.tv_sec == 0 && latency.tv_usec == -1)
#define SCION_PATH_METADATA_BANDWIDTH_IS_UNSET(bandwidth) (bandwidth == 0)
#define SCION_PATH_METADATA_GEO_IS_UNSET(geo) (geo.latitude == NAN && geo.longitude == NAN && geo.address == NULL)
#define SCION_PATH_METADATA_INTERNAL_HOPS_IS_UNSET(internal_hops) (internal_hops == 0)
 
typedef uint64_t scion_ifid;
 
struct scion_path_interface {
    scion_ifid id;
    scion_ia ia;
};
 
struct scion_geo_coordinates {
    float latitude;
    float longitude;
    char *address;
};
 
enum scion_link_type {
    SCION_LINK_TYPE_UNSPECIFIED = 0,
    SCION_LINK_TYPE_DIRECT = 1,
    SCION_LINK_TYPE_MULTI_HOP = 2,
    SCION_LINK_TYPE_OPEN_NET = 3
};
 
struct scion_path_metadata {
    scion_ia *ases;
    size_t ases_len;
 
    struct scion_path_interface *interfaces;
    size_t interfaces_len;
 
    uint32_t mtu;
    int64_t expiry;
 
    struct timeval *latencies;
 
    uint64_t *bandwidths;
 
    struct scion_geo_coordinates *geo;
 
    enum scion_link_type *link_types;
 
    //
    uint32_t *internal_hops;
 
    char **notes;
};
 
const struct scion_path_metadata *scion_path_get_metadata(const struct scion_path *path);
 
void scion_path_print(const struct scion_path *path);
 
void scion_path_print_metadata(const struct scion_path *path);
 
struct scion_path_collection;
 
typedef bool (*scion_path_predicate_fn)(struct scion_path *path, void *ctx);
 
struct scion_path_predicate {
    scion_path_predicate_fn fn;
    void *ctx;
};
 
typedef int (*scion_path_comparator_fn)(struct scion_path *path_one, struct scion_path *path_two, void *ctx);
 
struct scion_path_comparator {
    scion_path_comparator_fn fn;
    void *ctx;
    bool ascending;
};
 
void scion_path_collection_free(struct scion_path_collection *paths);
 
struct scion_path *scion_path_collection_find(
    struct scion_path_collection *paths, struct scion_path_predicate predicate);
 
struct scion_path *scion_path_collection_pop(struct scion_path_collection *paths);
 
struct scion_path *scion_path_collection_first(struct scion_path_collection *paths);
 
void scion_path_collection_sort(struct scion_path_collection *paths, struct scion_path_comparator comparator);
 
void scion_path_collection_filter(struct scion_path_collection *paths, struct scion_path_predicate predicate);
 
size_t scion_path_collection_size(struct scion_path_collection *paths);
 
struct scion_path **scion_path_collection_as_array(struct scion_path_collection *paths, size_t *len);
 
void scion_path_collection_print(struct scion_path_collection *paths);
 
int scion_path_collection_fetch(
    struct scion_network *network, scion_ia dst, uint opt, struct scion_path_collection **paths);
 
typedef void (*scion_policy_fn)(struct scion_path_collection *paths, void *ctx);
 
struct scion_policy {
    scion_policy_fn fn;
 
    void *ctx;
};
 
extern const struct scion_policy scion_policy_highest_mtu;
 
extern const struct scion_policy scion_policy_least_hops;
 
extern const struct scion_policy scion_policy_lowest_latency;
 
extern const struct scion_policy scion_policy_highest_bandwidth;
 
struct scion_policy scion_policy_min_mtu(uint32_t *mtu);
 
struct scion_socket;
 
typedef void scion_socket_scmp_error_cb(uint8_t *buf, size_t size, void *ctx);
 
int scion_socket(struct scion_socket **scion_sock, enum scion_addr_family addr_family, int type,
    enum scion_proto protocol, struct scion_network *network);
 
int scion_bind(struct scion_socket *scion_sock, const struct sockaddr *addr, socklen_t addrlen);
 
int scion_connect(struct scion_socket *scion_sock, const struct sockaddr *addr, socklen_t addrlen, scion_ia ia);
 
ssize_t scion_send(struct scion_socket *scion_sock, const void *buf, size_t size, int flags);
 
ssize_t scion_sendto(struct scion_socket *scion_sock, const void *buf, size_t size, int flags,
    const struct sockaddr *dst_addr, socklen_t addrlen, scion_ia dst_ia, struct scion_path *path);
 
ssize_t scion_sendmsg(
    struct scion_socket *scion_sock, const struct msghdr *msg, int flags, scion_ia dst_ia, struct scion_path *path);
 
ssize_t scion_recv(struct scion_socket *scion_sock, void *buf, size_t size, int flags);
 
ssize_t scion_recvfrom(struct scion_socket *scion_sock, void *buf, size_t size, int flags, struct sockaddr *src_addr,
    socklen_t *addrlen, scion_ia *src_ia, struct scion_path **path);
 
ssize_t scion_recvmsg(
    struct scion_socket *scion_sock, struct msghdr *msg, int flags, scion_ia *src_ia, struct scion_path **path);
 
int scion_close(struct scion_socket *scion_sock);
 
int scion_getsockopt(struct scion_socket *scion_sock, int level, int optname, void *optval, socklen_t *optlen);
 
int scion_setsockopt(struct scion_socket *scion_sock, int level, int optname, const void *optval, socklen_t optlen);
 
int scion_getsockname(struct scion_socket *scion_sock, struct sockaddr *addr, socklen_t *addrlen, scion_ia *ia);
 
int scion_getsockfd(struct scion_socket *scion_sock, int *fd);
 
int scion_setsockerrcb(struct scion_socket *scion_sock, scion_socket_scmp_error_cb cb, void *ctx);
 
int scion_setsockpolicy(struct scion_socket *scion_sock, struct scion_policy policy);
 
void scion_addr_print(const struct sockaddr *addr, scion_ia ia);
 
uint8_t scion_scmp_get_type(const uint8_t *buf, uint16_t buf_len);
 
uint8_t scion_scmp_get_code(const uint8_t *buf, uint16_t buf_len);
 
bool scion_scmp_is_error(const uint8_t *buf, uint16_t buf_len);
 
enum scion_scmp_echo_type {
    SCION_ECHO_TYPE_REQUEST = 128,
    SCION_ECHO_TYPE_REPLY = 129
};
 
struct scion_scmp_echo {
    enum scion_scmp_echo_type type;
    uint16_t id;
    uint16_t seqno;
    uint8_t *data;
    uint16_t data_length;
};
 
uint16_t scion_scmp_echo_len(struct scion_scmp_echo *scmp_echo);
 
int scion_scmp_echo_serialize(const struct scion_scmp_echo *scmp_echo, uint8_t *buf, uint16_t buf_len);
 
int scion_scmp_echo_deserialize(const uint8_t *buf, uint16_t buf_len, struct scion_scmp_echo *scmp_echo);
 
void scion_scmp_echo_free_members(struct scion_scmp_echo *scmp_echo);
 
#ifdef __cplusplus
}
#endif