Merge pull request #7 from powersync-ja/sqlite-randomness

Configurable UUID randomness

Author: rkistner

UUID.md

@@ -0,0 +1,40 @@
+### sqlite3 sqlite3_randomness
+
+As part of the extension, we provide `uuid()` and `gen_random_uuid()` functions, which generate a UUIDv4. We want reasonable guarantees that these uuids are unguessable, so we need to use a [cryptographically secure pseudorandom number generator](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator) (CSPRNG). Additionally, we want this to be fast (generating uuids shouldn't be a bottleneck for inserting rows).
+
+We provide two options:
+
+1. The `getrandom` crate, via the `getrandom` feature (enabled by default).
+2. `sqlite3_randomness`, when `getradnom` feature is not enabled.
+
+Everywhere it's available, `getrandom` is recommended. One exception is WASI, where `sqlite3_randomness` is simpler. In that case, make sure the VFS xRandomness function provides secure random values.
+
+## Details
+
+SQLite has a sqlite3_randomness function, that does:
+
+1. Seed using the VFS xRandomness function.
+2. Generate a sequence using ChaCha20 (CSPRNG, as long as the seed is sufficiently random).
+
+The VFS implementations differ:
+
+1. For unix (Linux, macOS, Android and iOS), the default VFS uses `/dev/urandom` for the xRandomness seed above. This is generally secure.
+2. For Windows, the default VFS uses a some system state such as pid, current time, current tick count for the entropy. This is okay for generating random numbers, but not quite secure (may be possible to guess).
+3. For wa-sqlite, it defaults to the unix VFS. Emscripten intercepts the `/dev/urandom` call and provides values using `crypto.getRandomValues()`: https://github.com/emscripten-core/emscripten/blob/2a00e26013b0a02411af09352c6731b89023f382/src/library.js#L2151-L2163
+4. Dart sqlite3 WASM uses `Random.secure()` to provide values. This is relatively slow, but only for the seed, so that's fine. This translates to `crypto.getRandomValues()` in JS.
+
+### getrandom crate
+
+The Rust uuid crate uses the getrandom crate for the "v4" feature by default.
+
+Full platform support is listed here: https://docs.rs/getrandom/latest/getrandom/
+
+Summary:
+
+- Linux, Android: getrandom system call if available, falling batch to `/dev/urandom`.
+- Windows: [BCryptGenRandom](https://docs.microsoft.com/en-us/windows/win32/api/bcrypt/nf-bcrypt-bcryptgenrandom)
+- macOS: [getentropy](https://www.unix.com/man-page/mojave/2/getentropy/)
+- iOS: [CCRandomGenerateBytes](https://opensource.apple.com/source/CommonCrypto/CommonCrypto-60074/include/CommonRandom.h.auto.html)
+- WASI (used for Dart sqlite3 WASM build): [random_get](https://wasix.org/docs/api-reference/wasi/random_get)
+
+The WASI one may be problematic, since that's not provided in all environments.

crates/core/Cargo.toml

@@ -23,16 +23,19 @@ serde = { version = "1.0", default-features = false, features = ["alloc", "deriv
 [dependencies.uuid]
 version = "1.4.1"
 default-features = false
-features = [
-    "v4"
-]
+features = []
 
 
 [dev-dependencies]
 
 
 [features]
+default = ["getrandom"]
+
 loadable_extension = ["sqlite_nostd/loadable_extension"]
 static = ["sqlite_nostd/static"]
 omit_load_extension = ["sqlite_nostd/omit_load_extension"]
+# Enable to use the getrandom crate instead of sqlite3_randomness
+# Enable for Windows builds; do not enable for WASM
+getrandom = ["uuid/v4"]
 

crates/core/src/operations.rs

@@ -6,7 +6,6 @@ use serde_json as json;
 
 use sqlite_nostd as sqlite;
 use sqlite_nostd::{Connection, ResultCode};
-use uuid::Uuid;
 use crate::error::{SQLiteError, PSResult};
 
 use crate::ext::SafeManagedStmt;
@@ -263,7 +262,7 @@ pub fn delete_pending_buckets(
 pub fn delete_bucket(
     db: *mut sqlite::sqlite3, name: &str) -> Result<(), SQLiteError> {
 
-    let id = Uuid::new_v4();
+    let id = gen_uuid();
     let new_name = format!("$delete_{}_{}", name, id.hyphenated().to_string());
 
     // language=SQLite

crates/core/src/util.rs

@@ -8,6 +8,7 @@ use serde_json as json;
 
 use sqlite::{Connection, ResultCode};
 use sqlite_nostd as sqlite;
+use uuid::{Builder,Uuid};
 use sqlite_nostd::ManagedStmt;
 
 use crate::error::SQLiteError;
@@ -84,6 +85,25 @@ pub fn deserialize_optional_string_to_i64<'de, D>(deserializer: D) -> Result<Opt
     }
 }
 
+// Use getrandom crate to generate UUID.
+// This is not available in all WASM builds - use the default in those cases.
+#[cfg(feature = "getrandom")]
+pub fn gen_uuid() -> Uuid {
+    let id = Uuid::new_v4();
+    id
+}
+
+// Default - use sqlite3_randomness to generate UUID
+// This uses ChaCha20 PRNG, with /dev/urandom as a seed on unix.
+// On Windows, it uses custom logic for the seed, which may not be secure.
+// Rather avoid this version for most builds.
+#[cfg(not(feature = "getrandom"))]
+pub fn gen_uuid() -> Uuid {
+    let mut random_bytes: [u8; 16] = [0; 16];
+    sqlite::randomness(&mut random_bytes);
+    let id = Builder::from_random_bytes(random_bytes).into_uuid();
+    id
+}
 
 pub const MAX_OP_ID: &str = "9223372036854775807";
 

crates/core/src/uuid.rs

@@ -9,16 +9,17 @@ use core::slice;
 use sqlite::ResultCode;
 use sqlite_nostd as sqlite;
 use sqlite_nostd::{Connection, Context};
-use uuid::Uuid;
 
 use crate::create_sqlite_text_fn;
 use crate::error::SQLiteError;
+use crate::util::*;
+
 
 fn uuid_v4_impl(
     _ctx: *mut sqlite::context,
     _args: &[*mut sqlite::value],
 ) -> Result<String, ResultCode> {
-    let id = Uuid::new_v4();
+    let id = gen_uuid();
     Ok(id.hyphenated().to_string())
 }
 

crates/loadable/Cargo.toml

@@ -13,8 +13,12 @@ name = "powersync"
 crate-type = ["cdylib"]
 
 [dependencies]
-powersync_core = { path="../core" }
 sqlite_nostd = { workspace=true }
 
+[dependencies.powersync_core]
+path = "../core"
+default-features = false
+features = []
+
 [features]
-default = ["powersync_core/loadable_extension", "sqlite_nostd/loadable_extension"]
+default = ["powersync_core/loadable_extension", "sqlite_nostd/loadable_extension", "powersync_core/getrandom"]

crates/loadable/src/lib.rs

@@ -37,6 +37,17 @@ pub fn __rust_alloc_error_handler(_: core::alloc::Layout) -> ! {
     core::intrinsics::abort()
 }
 
+#[cfg(target_family = "wasm")]
+#[no_mangle]
+static __rust_alloc_error_handler_should_panic: u8 = 0;
+
+#[cfg(target_family = "wasm")]
+#[no_mangle]
+static _CLOCK_PROCESS_CPUTIME_ID: i32 = 1;
+
+#[cfg(target_family = "wasm")]
+#[no_mangle]
+static _CLOCK_THREAD_CPUTIME_ID: i32 = 1;
 
 // Not used, but must be defined in some cases. Most notably when using native sqlite3 and loading
 // the extension.