db_sync.h File Reference

Server-to-server SQLite database synchronisation over TCP. More...

#include <cwist/security/db_crypt/db_crypt.h>
#include <sqlite3.h>
#include <stddef.h>

Include dependency graph for db_sync.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	CWIST_DB_SYNC_DEFAULT_PORT   9877
#define	CWIST_DB_SYNC_OK   0
	Return codes.
#define	CWIST_DB_SYNC_ERR_ARGS   (-1)
#define	CWIST_DB_SYNC_ERR_NET   (-2)
#define	CWIST_DB_SYNC_ERR_CRYPTO   (-3)
#define	CWIST_DB_SYNC_ERR_MEM   (-4)
#define	CWIST_DB_SYNC_ERR_PROTO   (-5)

Functions
int	cwist_db_sync_serve (sqlite3 *db, const cwist_db_crypt_ctx_t *ctx, int port)
	Serve the database once: accept one connection, send the sealed blob, then close.
int	cwist_db_sync_pull (const char *host, int port, const cwist_db_crypt_ctx_t *ctx, unsigned char **out_bytes, size_t *out_len)
	Pull a database from a sync server.

Detailed Description

Server-to-server SQLite database synchronisation over TCP.

The server serialises its in-memory SQLite database, encrypts the bytes using the KEK/DEK hierarchy from db_crypt, and streams the sealed blob to any connecting client.

Wire protocol (per-connection)

Client → Server: 4-byte magic 0x43 0x57 0x53 0x59 ("CWSY") Server → Client: 8-byte little-endian uint64 blob_length Server → Client: blob_length bytes (the sealed blob)

The client verifies the magic, reads the length, then opens the blob with cwist_db_crypt_open() using its copy of the KEK.

Definition in file db_sync.h.

Macro Definition Documentation

CWIST_DB_SYNC_DEFAULT_PORT

#define CWIST_DB_SYNC_DEFAULT_PORT   9877

Definition at line 26 of file db_sync.h.

CWIST_DB_SYNC_ERR_ARGS

#define CWIST_DB_SYNC_ERR_ARGS   (-1)

Definition at line 30 of file db_sync.h.

CWIST_DB_SYNC_ERR_CRYPTO

#define CWIST_DB_SYNC_ERR_CRYPTO   (-3)

Definition at line 32 of file db_sync.h.

CWIST_DB_SYNC_ERR_MEM

#define CWIST_DB_SYNC_ERR_MEM   (-4)

Definition at line 33 of file db_sync.h.

CWIST_DB_SYNC_ERR_NET

#define CWIST_DB_SYNC_ERR_NET   (-2)

Definition at line 31 of file db_sync.h.

CWIST_DB_SYNC_ERR_PROTO

#define CWIST_DB_SYNC_ERR_PROTO   (-5)

Definition at line 34 of file db_sync.h.

CWIST_DB_SYNC_OK

#define CWIST_DB_SYNC_OK   0

Return codes.

Definition at line 29 of file db_sync.h.

Function Documentation

cwist_db_sync_pull()

int cwist_db_sync_pull	(	const char *	host,
		int	port,
		const cwist_db_crypt_ctx_t *	ctx,
		unsigned char **	out_bytes,
		size_t *	out_len
	)

Pull a database from a sync server.

Connects to host:port, exchanges the handshake, receives the sealed blob, decrypts it, and returns the raw SQLite bytes. The caller is responsible for loading the bytes into an SQLite instance via sqlite3_deserialize().

Parameters

	host	Hostname or IP of the sync server.
	port	TCP port of the sync server.
	ctx	Decryption key context (kek must match server's kek).
[out]	out_bytes	Decrypted SQLite bytes (caller must free()).
[out]	out_len	Length of out_bytes.

Returns

CWIST_DB_SYNC_OK on success, negative on failure.

Pull a database from a sync server.

Parameters

host	Remote host name or address to connect to.
port	Remote TCP port, or the default when <= 0.
ctx	Encryption context used to decrypt the transferred blob.
out_bytes	Output pointer that receives the decrypted SQLite image.
out_len	Output pointer that receives the decrypted byte count.

Returns

CWIST_DB_SYNC_OK on success, or a protocol/network/crypto error code.

Definition at line 163 of file db_sync.c.

References cap, cwist_db_crypt_open(), CWIST_DB_SYNC_DEFAULT_PORT, CWIST_DB_SYNC_ERR_ARGS, CWIST_DB_SYNC_ERR_CRYPTO, CWIST_DB_SYNC_ERR_MEM, CWIST_DB_SYNC_ERR_NET, CWIST_DB_SYNC_ERR_PROTO, CWIST_DB_SYNC_MAX_BLOB_SIZE, and CWIST_DB_SYNC_OK.

cwist_db_sync_serve()

int cwist_db_sync_serve	(	sqlite3 *	db,
		const cwist_db_crypt_ctx_t *	ctx,
		int	port
	)

Serve the database once: accept one connection, send the sealed blob, then close.

Serialises db using sqlite3_serialize(), seals the bytes with ctx, listens on port, accepts the first authorised connection, sends the sealed blob, and returns. This is intentionally single-shot so the caller can embed it in a loop or background thread.

Parameters

db	Source SQLite3 handle (read-locked during serialise).
ctx	Encryption key context.
port	TCP port to listen on.

Returns

CWIST_DB_SYNC_OK on success, negative on failure.

Serve the database once: accept one connection, send the sealed blob, then close.

Parameters

db	SQLite connection whose main database should be transferred.
ctx	Encryption context used to seal the serialized bytes.
port	TCP port to listen on, or the default when <= 0.

Returns

CWIST_DB_SYNC_OK on success, or a protocol/network/crypto error code.

Definition at line 69 of file db_sync.c.

References cap, cwist_db_crypt_seal(), CWIST_DB_SYNC_DEFAULT_PORT, CWIST_DB_SYNC_ERR_ARGS, CWIST_DB_SYNC_ERR_CRYPTO, CWIST_DB_SYNC_ERR_MEM, CWIST_DB_SYNC_ERR_NET, CWIST_DB_SYNC_ERR_PROTO, and CWIST_DB_SYNC_OK.