From 1f304618ad6ca180b15aef61505bcb33164c9d90 Mon Sep 17 00:00:00 2001 From: DcruBro Date: Thu, 8 Oct 2026 18:04:28 +0200 Subject: [PATCH] build out public api header --- .gitignore | 3 +- README.md | 3 + include/bravais.h | 166 +++++++++++++++++++++++++++++++++++++++++ src/bravais_internal.h | 4 + 4 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 src/bravais_internal.h diff --git a/.gitignore b/.gitignore index e83892b..7f28e0e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ build/ build*/ -.DS_Store \ No newline at end of file +.DS_Store +.vscode/ \ No newline at end of file diff --git a/README.md b/README.md index e69de29..81c51ff 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,3 @@ +# libbravais + +C library for working with Bravais VPN packets. \ No newline at end of file diff --git a/include/bravais.h b/include/bravais.h index bcbdf0e..39215fe 100644 --- a/include/bravais.h +++ b/include/bravais.h @@ -1,4 +1,170 @@ +// libbravais public api header file + #ifndef BRAVAIS_H #define BRAVAIS_H +#include +#include + +#include "bravais/export.h" // Generated by cmake + +#ifdef __cplusplus +extern "C" { +#endif + +#define BRAVAIS_VERSION_MAJOR 0 +#define BRAVAIS_VERSION_MINOR 1 +#define BRAVAIS_VERSION_PATCH 0 +#define BRAVAIS_VERSION ((BRAVAIS_VERSION_MAJOR << 16) | (BRAVAIS_VERSION_MINOR << 8) | BRAVAIS_VERSION_PATCH) + +#define BRAVAIS_NO_TIMEOUT UINT64_MAX + +typedef enum { + // Error codes; Generally <0 = error, 0 = success + BRAVAIS_EMPTY = 1, // Nothing to emit right now + BRAVAIS_OK = 0, + BRAVAIS_ERR_INVALID_ARG = -1, + BRAVAIS_ERR_BUFFER_TOO_SMALL = -2, + BRAVAIS_ERR_MALFORMED = -3, + BRAVAIS_ERR_OUT_OF_MEMORY = -4, + BRAVAIS_ERR_UNSUPPORTED = -5, + + BRAVAIS_ERR_UNKNOWN = -1000 +} bravais_result_t; + +typedef enum { + BRAVAIS_ROLE_INITIATOR, + BRAVAIS_ROLE_RESPONDER +} bravais_role_t; + +typedef enum { + BRAVAIS_TRANSPORT_MODE_RAW, + BRAVAIS_TRANSPORT_MODE_QUIC +} bravais_transport_mode_t; + +typedef enum { + BRAVAIS_LOG_LEVEL_DEBUG, + BRAVAIS_LOG_LEVEL_INFO, + BRAVAIS_LOG_LEVEL_WARN, + BRAVAIS_LOG_LEVEL_ERROR +} bravais_log_level_t; + +/** + * @brief Logging callback function type + * @param userData User-defined data passed to the logging function + * @param level The log level of the message + * @param message The log message string + */ +typedef void (*bravais_log_fn_t)(void* userData, bravais_log_level_t level, const char* message); + +typedef struct { + bravais_role_t role; + bravais_transport_mode_t transportMode; + bravais_log_fn_t logFn; + void* logUserData; + + // TODO: Add more configuration options here as needed +} bravais_config_t; + +typedef struct bravais_conn bravais_conn_t; // Opaque connection type + +// ============================================================================= +// Public API functions +// ============================================================================= + +/** + * @brief Runtime library version number, packed as (major << 16) | (minor << 8) | patch + * @return The version number, packed as (major << 16) | (minor << 8) | patch + */ +BRAVAIS_API uint32_t bravais_version(void); + +/** + * @brief Initialize the config struct with defaults for all optional fields. + * @param config Pointer to a bravais_config_t struct to initialize. + * @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG if the config pointer is NULL. + * @attention The caller must still set role and transportMode manually. + */ +BRAVAIS_API bravais_result_t bravais_config_init(const bravais_config_t* config); + +/** + * @brief Create a new connection. + * @param config The configuration to use for the new connection. + * @param outConn A pointer to a bravais_conn_t pointer that will be set to the new connection. Set to NULL on failure. + * @return BRAVAIS_OK on success, BRAVAIS_ERR_INVALID_ARG, or BRAVAIS_ERR_OUT_OF_MEMORY. + * @attention The config is copied. The caller may reuse or discard it afterwards. + */ +BRAVAIS_API bravais_result_t bravais_conn_create(const bravais_config_t* config, bravais_conn_t** outConn); + +/** + * @brief Destroy a connection. + * @param conn The connection to destroy. + * @attention NULL is a no-op. + */ +BRAVAIS_API void bravais_conn_destroy(bravais_conn_t* conn); + +/** + * @brief Feed one datagram received from the network. + * @param conn The connection to feed the datagram to. + * @param data The datagram data received from the network. + * @param dataLen The length of the datagram data. + * @param nowMs The current time in milliseconds (unix epoch). + * @return BRAVAIS_OK on success, BRAVAIS_ERR_INVALID_ARG, or BRAVAIS_ERR_MALFORMED (datagram is malformed). + * @attention Any resulting output is queued. Drain it with the poll functions. + */ +BRAVAIS_API bravais_result_t bravais_recv_datagram(bravais_conn_t* conn, const uint8_t* data, size_t dataLen, uint64_t nowMs); + +/** + * @brief Submit one plaintext packet read from the TUN device. + * @param conn The connection to submit the packet to. + * @param data The packet data read from the TUN device. + * @param dataLen The length of the packet data. + * @param nowMs The current time in milliseconds (unix epoch). + * @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG. + * @attention The packet is encrypted and queued for sending. Drain it with bravais_poll_datagram(). + */ +BRAVAIS_API bravais_result_t bravais_send_packet(bravais_conn_t* conn, const uint8_t* data, size_t dataLen, uint64_t nowMs); + +/** + * @brief Take the next datagram to send to the network, if any. + * @param conn The connection to poll for datagrams. + * @param out A buffer to write the datagram to. + * @param outCap The capacity of the output buffer. + * @param outLen A pointer to a size_t that will be set to the length of the datagram written to the output buffer. + * @return BRAVAIS_OK on success, BRAVAIS_EMPTY if no datagram is available (this is NOT an error), or BRAVAIS_ERR_BUFFER_TOO_SMALL. + * @attention The caller must provide a buffer large enough to hold the datagram. + */ +BRAVAIS_API bravais_result_t bravais_poll_datagram(bravais_conn_t* conn, uint8_t* out, size_t outCap, size_t* outLen); + +/** + * @brief Take the next decrypted packet to write to the TUN device, if any. + * @param conn The connection to poll for packets. + * @param out A buffer to write the packet to. + * @param outCap The capacity of the output buffer. + * @param outLen A pointer to a size_t that will be set to the length of the packet written to the output buffer. + * @return BRAVAIS_OK on success, BRAVAIS_EMPTY if no packet is available (this is NOT an error), or BRAVAIS_ERR_BUFFER_TOO_SMALL. + * @attention The caller must provide a buffer large enough to hold the packet. + * @attention Same buffer semantics as bravais_poll_datagram(). + * + */ +BRAVAIS_API bravais_result_t bravais_poll_plaintext(bravais_conn_t* conn, uint8_t* out, size_t outCap, size_t* outLen); + +/** + * @brief Earliest time the connection needs bravais_on_timeout() called. + * @return Absolute deadline in milliseconds (unix epoch) for the next timeout, or BRAVAIS_NO_TIMEOUT if no timeout is needed. + */ +BRAVAIS_API uint64_t bravais_get_next_timeout(bravais_conn_t* conn); + +/** + * @brief Run any timers due at nowMs. + * @param conn The connection to run timers for. + * @param nowMs The current time in milliseconds (unix epoch). + * @return BRAVAIS_OK on success, or BRAVAIS_ERR_INVALID_ARG. + * @attention Safe to call early. No-op if no timers are due yet. + */ +BRAVAIS_API bravais_result_t bravais_on_timeout(bravais_conn_t* conn, uint64_t nowMs); + +#ifdef __cplusplus +} +#endif + #endif // BRAVAIS_H diff --git a/src/bravais_internal.h b/src/bravais_internal.h new file mode 100644 index 0000000..65eda5b --- /dev/null +++ b/src/bravais_internal.h @@ -0,0 +1,4 @@ +#ifndef BRAVAIS_INTERNAL_H +#define BRAVAIS_INTERNAL_H + +#endif // BRAVAIS_INTERNAL_H