1mod directory;
10
11pub use directory::SealedDirectory;
12
13use std::fmt;
14use std::fs::{self, File, OpenOptions};
15use std::io::{self, BufReader, ErrorKind, Read, Write};
16use std::os::unix::fs::FileExt;
17use std::path::{Path, PathBuf};
18use std::sync::Arc;
19
20use anyhow::{Context, Result, anyhow};
21use chacha20poly1305::aead::{Aead, KeyInit, Payload};
22use chacha20poly1305::{XChaCha20Poly1305, XNonce};
23use hkdf::Hkdf;
24use rand::TryRngCore;
25use rand::rngs::OsRng;
26use sha2::Sha256;
27
28use crate::keys::KeyGuard;
29
30pub const CHUNK_LEN: usize = 64 * 1024;
31const MAGIC: &[u8; 8] = b"SBSEAL\x00\x01";
32const KEY_ID_LEN: usize = 8;
33const FILE_ID_LEN: usize = 16;
34const HEADER_LEN: usize = MAGIC.len() + KEY_ID_LEN + FILE_ID_LEN;
35const TAG_LEN: usize = 16;
36const SEALED_CHUNK_LEN: usize = CHUNK_LEN + TAG_LEN;
37const AAD_DOMAIN: &[u8] = b"second-brain sealed file v1";
38const KEY_ID_INFO: &[u8] = b"second-brain sealed file key id v1";
39const CIPHER_KEY_INFO: &[u8] = b"second-brain sealed file cipher v1";
40const TMP_MARKER: &str = ".seal-tmp.";
41
42#[derive(Clone, Copy, PartialEq, Eq, Hash)]
43pub struct SealKeyId(pub [u8; KEY_ID_LEN]);
44
45impl fmt::Display for SealKeyId {
46 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
47 f.write_str(&crate::keys::hex(&self.0))
48 }
49}
50
51impl fmt::Debug for SealKeyId {
52 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
53 write!(f, "SealKeyId({self})")
54 }
55}
56
57pub struct SealKey {
60 id: SealKeyId,
61 secret: KeyGuard<[u8; 32]>,
62 cipher: XChaCha20Poly1305,
63}
64
65impl SealKey {
66 pub fn generate() -> Result<Self> {
67 Self::from_bytes(KeyGuard::random()?)
68 }
69
70 pub fn from_bytes(secret: KeyGuard<[u8; 32]>) -> Result<Self> {
71 let hkdf = Hkdf::<Sha256>::new(None, secret.expose());
72 let mut id = [0u8; KEY_ID_LEN];
73 hkdf.expand(KEY_ID_INFO, &mut id)
74 .map_err(|e| anyhow!("deriving a sealing key id: {e}"))?;
75 let mut cipher_key = KeyGuard::new([0u8; 32]);
76 hkdf.expand(CIPHER_KEY_INFO, cipher_key.expose_mut())
77 .map_err(|e| anyhow!("deriving a sealing cipher key: {e}"))?;
78 let cipher = XChaCha20Poly1305::new(cipher_key.expose().into());
79 Ok(Self {
80 id: SealKeyId(id),
81 secret,
82 cipher,
83 })
84 }
85
86 pub fn id(&self) -> SealKeyId {
87 self.id
88 }
89
90 pub(crate) fn expose(&self) -> &[u8; 32] {
91 self.secret.expose()
92 }
93}
94
95impl fmt::Debug for SealKey {
96 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
97 write!(f, "SealKey({})", self.id)
98 }
99}
100
101#[derive(Clone, Debug)]
104pub struct SealKeys {
105 current: Arc<SealKey>,
106 retired: Arc<[Arc<SealKey>]>,
107}
108
109impl SealKeys {
110 pub fn new(current: SealKey, retired: Vec<SealKey>) -> Self {
111 Self {
112 current: Arc::new(current),
113 retired: retired.into_iter().map(Arc::new).collect(),
114 }
115 }
116
117 pub fn single(current: SealKey) -> Self {
118 Self::new(current, Vec::new())
119 }
120
121 pub fn current_id(&self) -> SealKeyId {
122 self.current.id
123 }
124
125 pub fn retired_ids(&self) -> Vec<SealKeyId> {
126 self.retired.iter().map(|k| k.id).collect()
127 }
128
129 fn find(&self, id: SealKeyId) -> Option<&SealKey> {
130 std::iter::once(&self.current)
131 .chain(self.retired.iter())
132 .find(|k| k.id == id)
133 .map(|k| k.as_ref())
134 }
135}
136
137#[derive(Debug, Clone, PartialEq, Eq)]
140pub enum SealError {
141 NotSealed,
143 UnknownKey(SealKeyId),
145 Damaged,
148 KeyRequired,
150}
151
152impl fmt::Display for SealError {
153 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
154 match self {
155 Self::NotSealed => f.write_str("the file is not sealed"),
156 Self::UnknownKey(id) => {
157 write!(f, "the file is sealed under key {id}, which is not held")
158 }
159 Self::Damaged => f.write_str("the sealed file is damaged or truncated"),
160 Self::KeyRequired => f.write_str("the file is sealed and no key was given to open it"),
161 }
162 }
163}
164
165impl std::error::Error for SealError {}
166
167pub fn seal_error(error: &anyhow::Error) -> Option<&SealError> {
169 error.chain().find_map(|e| e.downcast_ref::<SealError>())
170}
171
172#[derive(Clone, Copy)]
173struct Header {
174 key_id: SealKeyId,
175 file_id: [u8; FILE_ID_LEN],
176}
177
178impl Header {
179 fn fresh(key: &SealKey) -> Result<Self> {
180 let mut file_id = [0u8; FILE_ID_LEN];
181 OsRng
182 .try_fill_bytes(&mut file_id)
183 .map_err(|e| anyhow!("reading OS randomness: {e}"))?;
184 Ok(Self {
185 key_id: key.id,
186 file_id,
187 })
188 }
189
190 fn encode(&self) -> [u8; HEADER_LEN] {
191 let mut out = [0u8; HEADER_LEN];
192 out[..MAGIC.len()].copy_from_slice(MAGIC);
193 out[MAGIC.len()..MAGIC.len() + KEY_ID_LEN].copy_from_slice(&self.key_id.0);
194 out[MAGIC.len() + KEY_ID_LEN..].copy_from_slice(&self.file_id);
195 out
196 }
197
198 fn decode(bytes: &[u8]) -> Option<Self> {
199 if bytes.len() < HEADER_LEN || &bytes[..MAGIC.len()] != MAGIC {
200 return None;
201 }
202 let mut key_id = [0u8; KEY_ID_LEN];
203 key_id.copy_from_slice(&bytes[MAGIC.len()..MAGIC.len() + KEY_ID_LEN]);
204 let mut file_id = [0u8; FILE_ID_LEN];
205 file_id.copy_from_slice(&bytes[MAGIC.len() + KEY_ID_LEN..HEADER_LEN]);
206 Some(Self {
207 key_id: SealKeyId(key_id),
208 file_id,
209 })
210 }
211
212 fn nonce(&self, chunk: u64) -> XNonce {
213 let mut nonce = [0u8; FILE_ID_LEN + 8];
214 nonce[..FILE_ID_LEN].copy_from_slice(&self.file_id);
215 nonce[FILE_ID_LEN..].copy_from_slice(&chunk.to_be_bytes());
216 nonce.into()
217 }
218
219 fn aad(&self, name: &str, chunk: u64, last: bool) -> Vec<u8> {
220 let mut aad = Vec::with_capacity(AAD_DOMAIN.len() + HEADER_LEN + name.len() + 13);
221 aad.extend_from_slice(AAD_DOMAIN);
222 aad.extend_from_slice(&self.encode());
223 aad.extend_from_slice(&(name.len() as u32).to_be_bytes());
224 aad.extend_from_slice(name.as_bytes());
225 aad.extend_from_slice(&chunk.to_be_bytes());
226 aad.push(u8::from(last));
227 aad
228 }
229}
230
231#[derive(Clone, Copy)]
234struct Layout {
235 chunks: u64,
236 last_len: usize,
237}
238
239impl Layout {
240 fn of(file_len: u64) -> Option<Self> {
241 let body = file_len.checked_sub(HEADER_LEN as u64)?;
242 if body < TAG_LEN as u64 {
243 return None;
244 }
245 let chunks = body.div_ceil(SEALED_CHUNK_LEN as u64).max(1);
246 let last_sealed = body - (chunks - 1) * SEALED_CHUNK_LEN as u64;
247 let last_len = usize::try_from(last_sealed).ok()?.checked_sub(TAG_LEN)?;
248 if chunks > 1 && last_len == 0 {
249 return None;
250 }
251 Some(Self { chunks, last_len })
252 }
253
254 fn plaintext_len(&self) -> u64 {
255 (self.chunks - 1) * CHUNK_LEN as u64 + self.last_len as u64
256 }
257
258 fn chunk_len(&self, chunk: u64) -> usize {
259 if chunk + 1 == self.chunks {
260 self.last_len
261 } else {
262 CHUNK_LEN
263 }
264 }
265
266 fn offset(chunk: u64) -> u64 {
267 HEADER_LEN as u64 + chunk * SEALED_CHUNK_LEN as u64
268 }
269}
270
271fn seal_chunk(
272 key: &SealKey,
273 header: &Header,
274 name: &str,
275 chunk: u64,
276 last: bool,
277 plaintext: &[u8],
278) -> Result<Vec<u8>> {
279 let aad = header.aad(name, chunk, last);
280 key.cipher
281 .encrypt(
282 &header.nonce(chunk),
283 Payload {
284 msg: plaintext,
285 aad: &aad,
286 },
287 )
288 .map_err(|_| anyhow!("sealing chunk {chunk} of {name}"))
289}
290
291fn open_chunk(
292 key: &SealKey,
293 header: &Header,
294 name: &str,
295 chunk: u64,
296 last: bool,
297 sealed: &[u8],
298) -> Result<Vec<u8>> {
299 let aad = header.aad(name, chunk, last);
300 key.cipher
301 .decrypt(
302 &header.nonce(chunk),
303 Payload {
304 msg: sealed,
305 aad: &aad,
306 },
307 )
308 .map_err(|_| {
309 anyhow::Error::new(SealError::Damaged)
310 .context(format!("opening chunk {chunk} of {name}"))
311 })
312}
313
314fn key_for<'a>(keys: &'a SealKeys, header: &Header) -> Result<&'a SealKey> {
315 keys.find(header.key_id)
316 .ok_or_else(|| SealError::UnknownKey(header.key_id).into())
317}
318
319fn short_read_as(error: io::Error, cause: SealError) -> anyhow::Error {
322 if error.kind() == ErrorKind::UnexpectedEof {
323 cause.into()
324 } else {
325 error.into()
326 }
327}
328
329pub fn seal(keys: &SealKeys, name: &str, plaintext: &[u8]) -> Result<Vec<u8>> {
331 let mut writer = SealWriter::new(Vec::new(), keys, name)?;
332 writer.write_all(plaintext)?;
333 writer.finish()
334}
335
336pub fn open(keys: &SealKeys, name: &str, sealed: &[u8]) -> Result<Vec<u8>> {
338 let header = Header::decode(sealed).ok_or(SealError::NotSealed)?;
339 let key = key_for(keys, &header)?;
340 let layout = Layout::of(sealed.len() as u64).ok_or(SealError::Damaged)?;
341 let mut out = Vec::with_capacity(usize::try_from(layout.plaintext_len())?);
342 for chunk in 0..layout.chunks {
343 let start = usize::try_from(Layout::offset(chunk))?;
344 let end = start + layout.chunk_len(chunk) + TAG_LEN;
345 let last = chunk + 1 == layout.chunks;
346 out.extend_from_slice(&open_chunk(
347 key,
348 &header,
349 name,
350 chunk,
351 last,
352 &sealed[start..end],
353 )?);
354 }
355 Ok(out)
356}
357
358pub fn looks_sealed(bytes: &[u8]) -> bool {
360 Header::decode(bytes).is_some()
361}
362
363pub fn key_id_of(bytes: &[u8]) -> Option<SealKeyId> {
366 Header::decode(bytes).map(|h| h.key_id)
367}
368
369pub fn sealed_key_id(path: &Path) -> Result<Option<SealKeyId>> {
372 let mut file = File::open(path).with_context(|| format!("opening {}", path.display()))?;
373 let mut head = [0u8; HEADER_LEN];
374 match file.read_exact(&mut head) {
375 Ok(()) => Ok(Header::decode(&head).map(|h| h.key_id)),
376 Err(e) if e.kind() == ErrorKind::UnexpectedEof => Ok(None),
377 Err(e) => Err(e).with_context(|| format!("reading {}", path.display())),
378 }
379}
380
381pub fn read_file(path: &Path, keys: Option<&SealKeys>, name: &str) -> Result<Vec<u8>> {
386 let mut file = File::open(path).with_context(|| format!("opening {}", path.display()))?;
387 let mut head = [0u8; HEADER_LEN];
388 let sealed = match file.read_exact_at(&mut head, 0) {
389 Ok(()) => Header::decode(&head).is_some(),
390 Err(e) if e.kind() == ErrorKind::UnexpectedEof => false,
391 Err(e) => return Err(e).with_context(|| format!("reading {}", path.display())),
392 };
393 match keys {
394 Some(keys) if sealed => SealedReader::from_file(file, path, keys, name)?.read_all(),
395 None if sealed => Err(anyhow::Error::new(SealError::KeyRequired)
396 .context(format!("opening {}", path.display()))),
397 _ => {
398 let mut plaintext = Vec::new();
399 file.read_to_end(&mut plaintext)
400 .with_context(|| format!("reading {}", path.display()))?;
401 Ok(plaintext)
402 }
403 }
404}
405
406pub fn write_file(
410 path: &Path,
411 keys: Option<&SealKeys>,
412 name: &str,
413 plaintext: &[u8],
414) -> Result<()> {
415 let (tmp_path, file) = create_tmp(path)?;
416 let result = (|| {
417 let mut file = file;
418 match keys {
419 Some(keys) => {
420 let mut writer = SealWriter::new(io::BufWriter::new(&mut file), keys, name)?;
421 writer.write_all(plaintext)?;
422 writer.finish()?.flush()?;
423 }
424 None => file.write_all(plaintext)?,
425 }
426 file.sync_all()?;
427 Ok::<_, anyhow::Error>(())
428 })();
429 finish_tmp(result, &tmp_path, path)
430}
431
432pub fn reseal_file(path: &Path, keys: &SealKeys, name: &str) -> Result<bool> {
437 let sealed_under = sealed_key_id(path)?;
438 if sealed_under == Some(keys.current_id()) {
439 return Ok(false);
440 }
441 let (tmp_path, file) = create_tmp(path)?;
442 let result = (|| {
443 let mut file = file;
444 {
445 let mut writer = SealWriter::new(io::BufWriter::new(&mut file), keys, name)?;
446 match sealed_under {
447 Some(_) => {
448 let reader = SealedReader::open(path, keys, name)?;
449 for chunk in 0..reader.layout.chunks {
450 writer.write_all(&reader.read_chunk(chunk)?)?;
451 }
452 }
453 None => {
454 let mut source = BufReader::new(
455 File::open(path).with_context(|| format!("opening {}", path.display()))?,
456 );
457 io::copy(&mut source, &mut writer)?;
458 }
459 }
460 writer.finish()?.flush()?;
461 }
462 file.sync_all()?;
463 Ok::<_, anyhow::Error>(())
464 })();
465 finish_tmp(result, &tmp_path, path)?;
466 Ok(true)
467}
468
469pub fn is_tmp_name(name: &str) -> bool {
472 name.contains(TMP_MARKER)
473}
474
475fn create_tmp(path: &Path) -> Result<(PathBuf, File)> {
476 let mut suffix = [0u8; 8];
477 OsRng
478 .try_fill_bytes(&mut suffix)
479 .map_err(|e| anyhow!("reading OS randomness: {e}"))?;
480 let file_name = path
481 .file_name()
482 .and_then(|n| n.to_str())
483 .ok_or_else(|| anyhow!("{} has no utf-8 file name", path.display()))?;
484 let tmp_path = path.with_file_name(format!(
485 "{file_name}{TMP_MARKER}{}",
486 crate::keys::hex(&suffix)
487 ));
488 let file = OpenOptions::new()
489 .write(true)
490 .create_new(true)
491 .open(&tmp_path)
492 .with_context(|| format!("creating {}", tmp_path.display()))?;
493 Ok((tmp_path, file))
494}
495
496fn finish_tmp(result: Result<()>, tmp_path: &Path, path: &Path) -> Result<()> {
497 let renamed = result.and_then(|()| {
498 fs::rename(tmp_path, path)
499 .with_context(|| format!("renaming {} to {}", tmp_path.display(), path.display()))
500 });
501 if renamed.is_err()
502 && let Err(e) = fs::remove_file(tmp_path)
503 && e.kind() != ErrorKind::NotFound
504 {
505 tracing::warn!("cannot remove {}: {e}", tmp_path.display());
506 }
507 renamed?;
508 if let Some(parent) = path.parent() {
509 File::open(parent)
510 .and_then(|dir| dir.sync_all())
511 .with_context(|| format!("syncing {}", parent.display()))?;
512 }
513 Ok(())
514}
515
516pub struct SealWriter<W: Write> {
520 inner: Option<W>,
521 key: Arc<SealKey>,
522 header: Header,
523 name: String,
524 chunk: u64,
525 buf: Vec<u8>,
526}
527
528impl<W: Write> SealWriter<W> {
529 pub fn new(mut inner: W, keys: &SealKeys, name: &str) -> Result<Self> {
530 let key = keys.current.clone();
531 let header = Header::fresh(&key)?;
532 inner.write_all(&header.encode())?;
533 Ok(Self {
534 inner: Some(inner),
535 key,
536 header,
537 name: name.to_string(),
538 chunk: 0,
539 buf: Vec::with_capacity(CHUNK_LEN + 1),
540 })
541 }
542
543 fn inner(&mut self) -> io::Result<&mut W> {
544 self.inner
545 .as_mut()
546 .ok_or_else(|| io::Error::other("the sealed file was already finished"))
547 }
548
549 fn emit(&mut self, last: bool) -> io::Result<()> {
550 let take = self.buf.len().min(CHUNK_LEN);
551 let sealed = seal_chunk(
552 &self.key,
553 &self.header,
554 &self.name,
555 self.chunk,
556 last,
557 &self.buf[..take],
558 )
559 .map_err(io::Error::other)?;
560 self.inner()?.write_all(&sealed)?;
561 self.buf.drain(..take);
562 self.chunk += 1;
563 Ok(())
564 }
565
566 pub fn finish(mut self) -> Result<W> {
568 self.finish_ref()?;
569 self.inner
570 .take()
571 .ok_or_else(|| anyhow!("the sealed file was already finished"))
572 }
573
574 fn finish_ref(&mut self) -> io::Result<()> {
575 while self.buf.len() > CHUNK_LEN {
576 self.emit(false)?;
577 }
578 self.emit(true)?;
579 self.inner()?.flush()
580 }
581}
582
583impl<W: Write> Write for SealWriter<W> {
584 fn write(&mut self, data: &[u8]) -> io::Result<usize> {
585 self.inner()?;
586 let mut rest = data;
587 while !rest.is_empty() {
588 if self.buf.len() > CHUNK_LEN {
589 self.emit(false)?;
590 }
591 let room = CHUNK_LEN + 1 - self.buf.len();
592 let take = rest.len().min(room);
593 self.buf.extend_from_slice(&rest[..take]);
594 rest = &rest[take..];
595 }
596 Ok(data.len())
597 }
598
599 fn flush(&mut self) -> io::Result<()> {
600 self.inner()?.flush()
601 }
602}
603
604pub struct SealedReader {
606 file: File,
607 key: Arc<SealKey>,
608 header: Header,
609 layout: Layout,
610 name: String,
611}
612
613impl fmt::Debug for SealedReader {
614 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
615 write!(f, "SealedReader({})", self.name)
616 }
617}
618
619impl SealedReader {
620 pub fn open(path: &Path, keys: &SealKeys, name: &str) -> Result<Self> {
621 let file = File::open(path).with_context(|| format!("opening {}", path.display()))?;
622 Self::from_file(file, path, keys, name)
623 }
624
625 fn from_file(file: File, path: &Path, keys: &SealKeys, name: &str) -> Result<Self> {
626 let mut head = [0u8; HEADER_LEN];
627 file.read_exact_at(&mut head, 0)
628 .map_err(|e| short_read_as(e, SealError::NotSealed))
629 .with_context(|| format!("reading {}", path.display()))?;
630 let header = Header::decode(&head)
631 .ok_or(SealError::NotSealed)
632 .with_context(|| format!("reading {}", path.display()))?;
633 let key = std::iter::once(&keys.current)
634 .chain(keys.retired.iter())
635 .find(|k| k.id == header.key_id)
636 .cloned()
637 .ok_or(SealError::UnknownKey(header.key_id))
638 .with_context(|| format!("opening {}", path.display()))?;
639 let file_len = file.metadata()?.len();
640 let layout = Layout::of(file_len)
641 .ok_or(SealError::Damaged)
642 .with_context(|| format!("opening {}", path.display()))?;
643 Ok(Self {
644 file,
645 key,
646 header,
647 layout,
648 name: name.to_string(),
649 })
650 }
651
652 pub fn len(&self) -> u64 {
653 self.layout.plaintext_len()
654 }
655
656 pub fn is_empty(&self) -> bool {
657 self.len() == 0
658 }
659
660 pub fn key_id(&self) -> SealKeyId {
661 self.header.key_id
662 }
663
664 pub fn file_id(&self) -> u128 {
666 u128::from_be_bytes(self.header.file_id)
667 }
668
669 pub fn chunks(&self) -> u64 {
670 self.layout.chunks
671 }
672
673 pub fn read_chunk(&self, chunk: u64) -> Result<Vec<u8>> {
674 anyhow::ensure!(
675 chunk < self.layout.chunks,
676 "{} has no chunk {chunk}",
677 self.name
678 );
679 let mut sealed = vec![0u8; self.layout.chunk_len(chunk) + TAG_LEN];
680 self.file
681 .read_exact_at(&mut sealed, Layout::offset(chunk))
682 .map_err(|e| short_read_as(e, SealError::Damaged))
683 .with_context(|| format!("reading chunk {chunk} of {}", self.name))?;
684 let last = chunk + 1 == self.layout.chunks;
685 open_chunk(&self.key, &self.header, &self.name, chunk, last, &sealed)
686 }
687
688 pub fn read_all(&self) -> Result<Vec<u8>> {
689 let mut out = Vec::with_capacity(usize::try_from(self.len())?);
690 for chunk in 0..self.layout.chunks {
691 out.extend_from_slice(&self.read_chunk(chunk)?);
692 }
693 Ok(out)
694 }
695}
696
697#[cfg(test)]
698mod tests;