use std::fs::File;
use std::io::Read;
use std::path::Path;
use crate::compressed_vfs::{FLAG_ENCRYPTED, HEADER_FLAGS_OFFSET, LEGACY_MAGIC, MAGIC};
use crate::{
ManagedConnection, SQLiteCompressedContainerAnchor, SQLiteCompressionOptions, SQLiteError,
};
const SQLITE_MAGIC: &[u8; 16] = b"SQLite format 3\0";
const DETECT_PREFIX_LEN: usize = 16;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DatabaseFileFormat {
Missing,
PlainSQLite,
CompressedContainer { encrypted: bool },
Unrecognized,
}
impl DatabaseFileFormat {
#[must_use]
pub fn requires_key(self) -> bool {
matches!(
self,
Self::CompressedContainer { encrypted: true } | Self::Unrecognized
)
}
}
pub fn detect_database_file_format(path: &Path) -> std::io::Result<DatabaseFileFormat> {
let mut file = match File::open(path) {
Ok(file) => file,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
return Ok(DatabaseFileFormat::Missing);
}
Err(err) => return Err(err),
};
let mut prefix = [0_u8; DETECT_PREFIX_LEN];
let mut read = 0;
while read < prefix.len() {
let n = file.read(&mut prefix[read..])?;
if n == 0 {
break;
}
read += n;
}
if read == 0 {
return Ok(DatabaseFileFormat::Missing);
}
if read < DETECT_PREFIX_LEN {
return Ok(DatabaseFileFormat::Unrecognized);
}
if &prefix == SQLITE_MAGIC {
return Ok(DatabaseFileFormat::PlainSQLite);
}
if &prefix[..MAGIC.len()] == MAGIC || &prefix[..LEGACY_MAGIC.len()] == LEGACY_MAGIC {
let flags = u32::from_le_bytes([
prefix[HEADER_FLAGS_OFFSET],
prefix[HEADER_FLAGS_OFFSET + 1],
prefix[HEADER_FLAGS_OFFSET + 2],
prefix[HEADER_FLAGS_OFFSET + 3],
]);
return Ok(DatabaseFileFormat::CompressedContainer {
encrypted: flags & FLAG_ENCRYPTED != 0,
});
}
Ok(DatabaseFileFormat::Unrecognized)
}
impl ManagedConnection {
pub fn open_auto(path: &Path, key: Option<&str>) -> Result<Self, SQLiteError> {
Self::open_detected(path, key, None)
}
pub fn open_auto_with_anchor(
path: &Path,
key: &str,
trusted_anchor: SQLiteCompressedContainerAnchor,
) -> Result<Self, SQLiteError> {
Self::open_detected(path, Some(key), Some(trusted_anchor))
}
fn open_detected(
path: &Path,
key: Option<&str>,
anchor: Option<SQLiteCompressedContainerAnchor>,
) -> Result<Self, SQLiteError> {
let key = match key {
Some("") => return Err(SQLiteError::EmptyEncryptionKey),
other => other,
};
let format = detect_database_file_format(path)?;
if anchor.is_some()
&& format != (DatabaseFileFormat::CompressedContainer { encrypted: true })
{
return Err(SQLiteError::StorageBackend(
"a trusted anchor requires an existing encrypted compressed container".into(),
));
}
match format {
DatabaseFileFormat::Missing => match key {
Some(key) => Self::open_encrypted(path, key),
None => Self::open(path),
},
DatabaseFileFormat::PlainSQLite => match key {
Some(_) => Err(SQLiteError::NotEncrypted),
None => Self::open(path),
},
DatabaseFileFormat::CompressedContainer { encrypted: true } => match key {
Some(key) => match anchor {
Some(anchor) => Self::open_compressed_encrypted_with_anchor(
path,
key,
SQLiteCompressionOptions::default(),
anchor,
),
None => Self::open_compressed_encrypted(
path,
key,
SQLiteCompressionOptions::default(),
),
},
None => Err(SQLiteError::EncryptionKeyRequired),
},
DatabaseFileFormat::CompressedContainer { encrypted: false } => match key {
Some(_) => Err(SQLiteError::NotEncrypted),
None => Self::open_compressed(path, SQLiteCompressionOptions::default()),
},
DatabaseFileFormat::Unrecognized => match key {
Some(key) => Self::open_encrypted(path, key),
None => Err(SQLiteError::EncryptionKeyRequired),
},
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::compressed_vfs::SQLiteCompressionOptions;
use crate::connection::ManagedConnection;
fn temp_dir() -> tempfile::TempDir {
tempfile::tempdir().expect("tempdir")
}
#[test]
fn automatic_anchored_open_preserves_exact_state_and_rejects_missing_files() {
let directory = temp_dir();
for (index, compression) in [
SQLiteCompressionOptions::lz4(),
SQLiteCompressionOptions::zstd(),
]
.into_iter()
.enumerate()
{
let path = directory.path().join(format!("anchored-{index}"));
let old_file = directory.path().join(format!("old-{index}"));
let key = "automatic-anchor-key";
let connection =
ManagedConnection::open_compressed_encrypted(&path, key, compression).unwrap();
connection
.with(|sql| {
Ok(sql.execute_batch("CREATE TABLE t (n INTEGER); INSERT INTO t VALUES (7)")?)
})
.unwrap();
drop(connection);
let first = crate::read_authenticated_anchor(&path, key).unwrap();
std::fs::copy(&path, &old_file).unwrap();
for part in 0..3 {
let mut invalid = first;
match part {
0 => invalid.database_id[0] ^= 1,
1 => invalid.generation ^= 1,
_ => invalid.state_tag[0] ^= 1,
}
assert!(ManagedConnection::open_auto_with_anchor(&path, key, invalid).is_err());
}
let connection = ManagedConnection::open_auto_with_anchor(&path, key, first).unwrap();
connection
.with(|sql| Ok(sql.execute_batch("INSERT INTO t VALUES (8)")?))
.unwrap();
drop(connection);
let current = crate::read_authenticated_anchor(&path, key).unwrap();
assert_eq!(first.database_id, current.database_id);
assert!(current.generation > first.generation);
assert_ne!(current.state_tag, first.state_tag);
assert!(ManagedConnection::open_auto_with_anchor(&path, key, first).is_err());
let connection = ManagedConnection::open_auto_with_anchor(&path, key, current).unwrap();
let count: i64 = connection
.with(|sql| Ok(sql.query_row("SELECT count(*) FROM t", [], |row| row.get(0))?))
.unwrap();
assert_eq!(count, 2);
drop(connection);
std::fs::copy(&old_file, &path).unwrap();
assert!(ManagedConnection::open_auto_with_anchor(&path, key, current).is_err());
let missing = directory.path().join(format!("missing-{index}"));
assert!(ManagedConnection::open_auto_with_anchor(&missing, key, current).is_err());
assert!(!missing.exists());
let plain = directory.path().join(format!("plain-{index}"));
let connection = ManagedConnection::open(&plain).unwrap();
connection
.with(|sql| Ok(sql.execute_batch("CREATE TABLE retained (n INTEGER)")?))
.unwrap();
drop(connection);
let before = std::fs::read(&plain).unwrap();
assert!(ManagedConnection::open_auto_with_anchor(&plain, key, current).is_err());
assert_eq!(std::fs::read(&plain).unwrap(), before);
}
}
#[test]
fn automatic_connections_preserve_data_and_encryption_across_all_codecs() {
let directory = temp_dir();
for (index, compression) in [
None,
Some(SQLiteCompressionOptions::zstd()),
Some(SQLiteCompressionOptions::lz4()),
]
.into_iter()
.enumerate()
{
for key in [None, Some("automatic-open-test-key")] {
let path = directory.path().join(format!("{index}-{}", key.is_some()));
let connection = match (compression, key) {
(None, key) => ManagedConnection::open_auto(&path, key),
(Some(options), None) => ManagedConnection::open_compressed(&path, options),
(Some(options), Some(key)) => {
ManagedConnection::open_compressed_encrypted(&path, key, options)
}
}
.unwrap();
connection
.with(|sqlite| {
Ok(sqlite.execute_batch(
"CREATE TABLE retained (n INTEGER); INSERT INTO retained VALUES (101)",
)?)
})
.unwrap();
drop(connection);
let reopened = ManagedConnection::open_auto(&path, key).unwrap();
let value = reopened
.with(|sqlite| {
Ok(sqlite
.query_row("SELECT n FROM retained", [], |row| row.get::<_, i64>(0))?)
})
.unwrap();
assert_eq!(value, 101);
drop(reopened);
if key.is_some() {
assert!(matches!(
ManagedConnection::open_auto(&path, None),
Err(SQLiteError::EncryptionKeyRequired)
));
assert!(ManagedConnection::open_auto(&path, Some("wrong-key")).is_err());
} else {
assert!(matches!(
ManagedConnection::open_auto(&path, Some("unused-key")),
Err(SQLiteError::NotEncrypted)
));
}
}
}
}
#[test]
fn automatic_connections_reject_empty_keys_before_creating_files() {
let directory = temp_dir();
let path = directory.path().join("absent.db");
assert!(matches!(
ManagedConnection::open_auto(&path, Some("")),
Err(SQLiteError::EmptyEncryptionKey)
));
assert!(!path.exists());
std::fs::write(&path, b"a foreign file with an unrecognized header").unwrap();
assert!(matches!(
ManagedConnection::open_auto(&path, None),
Err(SQLiteError::EncryptionKeyRequired)
));
}
#[test]
fn missing_file_detects_as_missing() {
let dir = temp_dir();
let path = dir.path().join("absent.db");
assert_eq!(
detect_database_file_format(&path).unwrap(),
DatabaseFileFormat::Missing
);
}
#[test]
fn empty_file_detects_as_missing() {
let dir = temp_dir();
let path = dir.path().join("empty.db");
std::fs::write(&path, b"").unwrap();
assert_eq!(
detect_database_file_format(&path).unwrap(),
DatabaseFileFormat::Missing
);
}
#[test]
fn plaintext_sqlite_detects_as_plain() {
let dir = temp_dir();
let path = dir.path().join("plain.db");
{
let conn = ManagedConnection::open(&path).unwrap();
conn.with(|c| Ok(c.execute_batch("CREATE TABLE t (id INTEGER)")?))
.unwrap();
}
assert_eq!(
detect_database_file_format(&path).unwrap(),
DatabaseFileFormat::PlainSQLite
);
}
#[test]
fn sqlcipher_database_detects_as_unrecognized() {
let dir = temp_dir();
let path = dir.path().join("cipher.db");
{
let conn = ManagedConnection::open_encrypted(&path, "secret").unwrap();
conn.with(|c| Ok(c.execute_batch("CREATE TABLE t (id INTEGER)")?))
.unwrap();
}
assert_eq!(
detect_database_file_format(&path).unwrap(),
DatabaseFileFormat::Unrecognized
);
}
#[test]
fn compressed_container_detects_with_encryption_flag() {
let dir = temp_dir();
let plain = dir.path().join("container.db");
{
let conn =
ManagedConnection::open_compressed(&plain, SQLiteCompressionOptions::default())
.unwrap();
conn.with(|c| Ok(c.execute_batch("CREATE TABLE t (id INTEGER)")?))
.unwrap();
}
assert_eq!(
detect_database_file_format(&plain).unwrap(),
DatabaseFileFormat::CompressedContainer { encrypted: false }
);
let encrypted = dir.path().join("container-enc.db");
{
let conn = ManagedConnection::open_compressed_encrypted(
&encrypted,
"secret",
SQLiteCompressionOptions::default(),
)
.unwrap();
conn.with(|c| Ok(c.execute_batch("CREATE TABLE t (id INTEGER)")?))
.unwrap();
}
assert_eq!(
detect_database_file_format(&encrypted).unwrap(),
DatabaseFileFormat::CompressedContainer { encrypted: true }
);
}
#[test]
fn legacy_compressed_header_is_classified_for_an_explicit_migration_error() {
let dir = temp_dir();
let path = dir.path().join("legacy-container.db");
let mut prefix = [0_u8; DETECT_PREFIX_LEN];
prefix[..LEGACY_MAGIC.len()].copy_from_slice(LEGACY_MAGIC);
prefix[8..12].copy_from_slice(&1_u32.to_le_bytes());
prefix[HEADER_FLAGS_OFFSET..HEADER_FLAGS_OFFSET + 4]
.copy_from_slice(&FLAG_ENCRYPTED.to_le_bytes());
std::fs::write(&path, prefix).unwrap();
assert_eq!(
detect_database_file_format(&path).unwrap(),
DatabaseFileFormat::CompressedContainer { encrypted: true }
);
}
#[test]
fn short_or_foreign_files_detect_as_unrecognized() {
let dir = temp_dir();
let short = dir.path().join("short.bin");
std::fs::write(&short, b"abc").unwrap();
assert_eq!(
detect_database_file_format(&short).unwrap(),
DatabaseFileFormat::Unrecognized
);
let foreign = dir.path().join("foreign.bin");
std::fs::write(&foreign, vec![0xAB_u8; 64]).unwrap();
assert_eq!(
detect_database_file_format(&foreign).unwrap(),
DatabaseFileFormat::Unrecognized
);
}
#[test]
fn requires_key_reflects_format() {
assert!(!DatabaseFileFormat::Missing.requires_key());
assert!(!DatabaseFileFormat::PlainSQLite.requires_key());
assert!(!DatabaseFileFormat::CompressedContainer { encrypted: false }.requires_key());
assert!(DatabaseFileFormat::CompressedContainer { encrypted: true }.requires_key());
assert!(DatabaseFileFormat::Unrecognized.requires_key());
}
}