Two-level key hierarchy for encrypting an SQLite database blob. More...

#include <stddef.h>
#include <stdint.h>

Include dependency graph for db_crypt.h:

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

Classes
struct	cwist_db_crypt_ctx_t
	Caller-managed key pair. More...

Macros
#define	CWIST_DB_CRYPT_OK 0
	Return codes.

#define	CWIST_DB_CRYPT_ERR_ARGS (-1)

#define	CWIST_DB_CRYPT_ERR_CRYPTO (-2)

#define	CWIST_DB_CRYPT_ERR_FORMAT (-3)

#define	CWIST_DB_CRYPT_ERR_MEM (-4)

#define	CWIST_DB_CRYPT_KEY_LEN 32

#define	CWIST_DB_CRYPT_IV_LEN 16

#define	CWIST_DB_CRYPT_HDR_LEN 109

Typedefs
typedef struct cwist_db_crypt_ctx_t	cwist_db_crypt_ctx_t
	Caller-managed key pair.

Functions
unsigned char *	cwist_db_crypt_seal (const cwist_db_crypt_ctx_t ctx, const unsigned char sqlite_bytes, size_t sqlite_len, size_t *out_len)
	Encrypt an SQLite database blob.

unsigned char *	cwist_db_crypt_open (const cwist_db_crypt_ctx_t ctx, const unsigned char blob, size_t blob_len, size_t *out_len)
	Decrypt a sealed blob produced by cwist_db_crypt_seal().

Detailed Description

Two-level key hierarchy for encrypting an SQLite database blob.

Encryption model

Plaintext SQLite bytes are encrypted with AES-256-CBC using a random Data Encryption Key (DEK). The DEK is then wrapped (encrypted) with a Key Encryption Key (KEK) that the caller manages.

Wire format produced by cwist_db_crypt_seal()

Offset Length Content

0 4 Magic "CWDB" (0x43 0x57 0x44 0x42) 4 1 Version byte (0x01) 5 16 KEK IV – random IV used to encrypt the DEK blob 21 64 Encrypted DEK blob – AES-256-CBC( KEK, KEK_IV, DEK_IV(16) || DEK(32) ) = 64 bytes (48-byte plaintext padded to next AES block boundary) 85 16 DEK IV – random IV used to encrypt the SQLite bytes 85 8 Plaintext length (little-endian uint64) 93 N AES-256-CBC( DEK, DEK_IV, sqlite_bytes ) padded to 16

Definition in file db_crypt.h.

Macro Definition Documentation

◆ CWIST_DB_CRYPT_ERR_ARGS

#define CWIST_DB_CRYPT_ERR_ARGS (-1)

Definition at line 34 of file db_crypt.h.

◆ CWIST_DB_CRYPT_ERR_CRYPTO

#define CWIST_DB_CRYPT_ERR_CRYPTO (-2)

Definition at line 35 of file db_crypt.h.

◆ CWIST_DB_CRYPT_ERR_FORMAT

#define CWIST_DB_CRYPT_ERR_FORMAT (-3)

Definition at line 36 of file db_crypt.h.

◆ CWIST_DB_CRYPT_ERR_MEM

#define CWIST_DB_CRYPT_ERR_MEM (-4)

Definition at line 37 of file db_crypt.h.

◆ CWIST_DB_CRYPT_HDR_LEN

#define CWIST_DB_CRYPT_HDR_LEN 109

Header overhead: magic(4)+ver(1)+kek_iv(16)+enc_dek(64)+dek_iv(16)+ptlen(8)

Definition at line 43 of file db_crypt.h.

◆ CWIST_DB_CRYPT_IV_LEN

#define CWIST_DB_CRYPT_IV_LEN 16

AES block / IV size.

Definition at line 41 of file db_crypt.h.

◆ CWIST_DB_CRYPT_KEY_LEN

#define CWIST_DB_CRYPT_KEY_LEN 32

Size constants (bytes). AES-256 key length.

Definition at line 40 of file db_crypt.h.

◆ CWIST_DB_CRYPT_OK

#define CWIST_DB_CRYPT_OK 0

Return codes.

Definition at line 33 of file db_crypt.h.

Typedef Documentation

◆ cwist_db_crypt_ctx_t

typedef struct cwist_db_crypt_ctx_t cwist_db_crypt_ctx_t

Caller-managed key pair.

Both kek and dek are 32-byte (AES-256) keys. kek must be provided by the caller. dek is generated randomly on each cwist_db_crypt_seal() call and stored encrypted in the output blob; it is recovered automatically by cwist_db_crypt_open().

Function Documentation

◆ cwist_db_crypt_open()

unsigned char * cwist_db_crypt_open	(	const cwist_db_crypt_ctx_t *	ctx,
		const unsigned char *	blob,
		size_t	blob_len,
		size_t *	out_len
	)

Decrypt a sealed blob produced by cwist_db_crypt_seal().

Recovers the DEK from the blob header, decrypts the SQLite bytes, and returns the original database content.

Parameters

	ctx	Key context (kek must match the one used for sealing).
	blob	Sealed blob.
	blob_len	Length of `blob`.
[out]	out_len	Length of the returned plaintext.

Returns: Heap-allocated SQLite bytes, or NULL on error. Caller must free().

Definition at line 160 of file db_crypt.c.

References cap, CWIST_DB_CRYPT_HDR_LEN, CWIST_DB_CRYPT_IV_LEN, CWIST_DB_CRYPT_KEY_LEN, cwist_db_crypt_ctx_t::kek, and OPENSSL_cleanse.

Referenced by cwist_db_sync_pull().

◆ cwist_db_crypt_seal()

unsigned char * cwist_db_crypt_seal	(	const cwist_db_crypt_ctx_t *	ctx,
		const unsigned char *	sqlite_bytes,
		size_t	sqlite_len,
		size_t *	out_len
	)

Encrypt an SQLite database blob.

Generates a random DEK and IV pair, encrypts sqlite_bytes with the DEK, wraps the DEK under the KEK, and returns the complete sealed blob.