use sha2::{Digest, Sha256};
use std::{
fs::{self, File},
io::Read,
path::Path,
};
const DIGEST_BUFFER_BYTES: usize = 64 * 1024;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DigestError {
Unavailable,
NotRegularFile,
Empty,
OpenFailed,
ReadFailed,
SizeOverflow,
ChangedDuringRead,
}
impl DigestError {
pub fn reason(self) -> &'static str {
match self {
Self::Unavailable => "is unavailable",
Self::NotRegularFile => "is not a regular non-symlink file",
Self::Empty => "must be non-empty",
Self::OpenFailed => "cannot be opened",
Self::ReadFailed => "read failed",
Self::SizeOverflow => "size overflow",
Self::ChangedDuringRead => "changed during read",
}
}
}
impl std::fmt::Display for DigestError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "digest input {}", self.reason())
}
}
impl std::error::Error for DigestError {}
pub fn file_digest(path: &Path) -> Result<(u64, String), DigestError> {
let before = fs::symlink_metadata(path).map_err(|_| DigestError::Unavailable)?;
if before.file_type().is_symlink() || !before.is_file() {
return Err(DigestError::NotRegularFile);
}
if before.len() == 0 {
return Err(DigestError::Empty);
}
let mut file = File::open(path).map_err(|_| DigestError::OpenFailed)?;
let (size, digest) = hash_stream(&mut file)?;
if size == 0 {
return Err(DigestError::Empty);
}
post_read_check(path, size)?;
Ok((size, digest))
}
fn hash_stream(file: &mut File) -> Result<(u64, String), DigestError> {
let mut hasher = Sha256::new();
let mut size = 0u64;
let mut buffer = [0u8; DIGEST_BUFFER_BYTES];
loop {
let count = file
.read(&mut buffer)
.map_err(|_| DigestError::ReadFailed)?;
if count == 0 {
break;
}
size = add_size(size, count as u64)?;
hasher.update(&buffer[..count]);
}
let digest = hasher.finalize();
Ok((
size,
digest.iter().map(|byte| format!("{byte:02x}")).collect(),
))
}
fn add_size(size: u64, count: u64) -> Result<u64, DigestError> {
size.checked_add(count).ok_or(DigestError::SizeOverflow)
}
fn post_read_check(path: &Path, size: u64) -> Result<(), DigestError> {
let after = fs::symlink_metadata(path).map_err(|_| DigestError::ChangedDuringRead)?;
if !post_read_stable(&after, size) {
return Err(DigestError::ChangedDuringRead);
}
Ok(())
}
fn post_read_stable(after: &fs::Metadata, size: u64) -> bool {
!after.file_type().is_symlink() && after.is_file() && after.len() == size
}
#[cfg(test)]
mod tests {
use super::*;
use crate::test_temp_dir;
use std::path::PathBuf;
fn write_file(root: &Path, name: &str, bytes: &[u8]) -> PathBuf {
let path = root.join(name);
fs::write(&path, bytes).unwrap();
path
}
#[test]
fn regular_file_digest_is_the_lowercase_hex_sha256_of_its_bytes() {
let root = test_temp_dir("digest-regular");
let path = write_file(&root, "artifact", b"abc");
let (size, sha256) = file_digest(&path).unwrap();
assert_eq!(size, 3);
assert_eq!(
sha256,
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
);
assert_eq!(sha256.len(), 64);
assert_eq!(sha256, sha256.to_lowercase());
fs::remove_dir_all(root).unwrap();
}
#[test]
fn identical_bytes_digest_identically_and_different_bytes_differ() {
let root = test_temp_dir("digest-determinism");
let first = write_file(&root, "first", b"payload");
let second = write_file(&root, "second", b"payload");
let third = write_file(&root, "third", b"payload!");
let first_digest = file_digest(&first).unwrap();
let second_digest = file_digest(&second).unwrap();
let third_digest = file_digest(&third).unwrap();
assert_eq!(first_digest, second_digest);
assert_ne!(first_digest, third_digest);
assert_ne!(first_digest.0, third_digest.0);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn empty_file_is_refused_before_it_is_read() {
let root = test_temp_dir("digest-empty");
let path = write_file(&root, "empty", b"");
assert_eq!(file_digest(&path).unwrap_err(), DigestError::Empty);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn a_zero_length_read_is_refused_even_when_the_file_grew_empty_after_the_check() {
let root = test_temp_dir("digest-truncated");
let path = write_file(&root, "artifact", b"0123456789");
let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
assert_eq!(size, 10);
fs::write(&path, b"").unwrap();
assert_eq!(file_digest(&path).unwrap_err(), DigestError::Empty);
assert_eq!(
post_read_check(&path, size).unwrap_err(),
DigestError::ChangedDuringRead
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn directory_is_refused() {
let root = test_temp_dir("digest-directory");
assert_eq!(file_digest(&root).unwrap_err(), DigestError::NotRegularFile);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn missing_path_is_refused() {
let root = test_temp_dir("digest-missing");
let path = root.join("absent");
assert_eq!(file_digest(&path).unwrap_err(), DigestError::Unavailable);
fs::remove_dir_all(root).unwrap();
}
#[cfg(unix)]
#[test]
fn symlink_is_refused() {
let root = test_temp_dir("digest-symlink");
let target = write_file(&root, "target", b"payload");
let link = root.join("link");
std::os::unix::fs::symlink(&target, &link).unwrap();
assert_eq!(file_digest(&link).unwrap_err(), DigestError::NotRegularFile);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn post_read_length_change_is_refused() {
let root = test_temp_dir("digest-length-change");
let path = write_file(&root, "artifact", b"0123456789");
let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
assert_eq!(size, 10);
fs::write(&path, b"0123456789abcd").unwrap();
assert_eq!(
post_read_check(&path, size).unwrap_err(),
DigestError::ChangedDuringRead
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn post_read_type_change_is_refused() {
let root = test_temp_dir("digest-type-change");
let path = write_file(&root, "artifact", b"0123456789");
let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
fs::remove_file(&path).unwrap();
fs::create_dir(&path).unwrap();
assert_eq!(
post_read_check(&path, size).unwrap_err(),
DigestError::ChangedDuringRead
);
fs::remove_dir_all(root).unwrap();
}
#[cfg(unix)]
#[test]
fn post_read_symlink_change_is_refused() {
let root = test_temp_dir("digest-symlink-change");
let path = write_file(&root, "artifact", b"0123456789");
let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
fs::remove_file(&path).unwrap();
let target = write_file(&root, "target", b"0123456789");
std::os::unix::fs::symlink(&target, &path).unwrap();
assert_eq!(
post_read_check(&path, size).unwrap_err(),
DigestError::ChangedDuringRead
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn size_overflow_is_an_error_not_a_wrapped_value() {
assert_eq!(
add_size(u64::MAX, 1).unwrap_err(),
DigestError::SizeOverflow
);
assert_eq!(add_size(10, 5).unwrap(), 15);
}
}